# Using the Amazon Connect SDK without a package manager
Using Connect SDK without package manager

This guide is intended for developers building Amazon Connect integrations who do not use npm, webpack, or other JavaScript package managers and bundlers in their web applications. This includes developers building custom StreamsJS-based contact center interfaces or third-party applications that run within the Amazon Connect Agent Workspace.

Amazon Connect recommends using a package manager such as npm and a bundler such as webpack or Vite for SDK integration. These tools provide dependency management, automatic updates, tree-shaking, and a streamlined development workflow. If you choose not to use these tools, this guide describes an alternative approach.

The Amazon Connect SDK is distributed as npm packages. These packages use Node.js-style module resolution and cannot be loaded directly in a browser using a `<script>` tag. If your development environment does not include a package manager or bundler, you must create a prebuilt script file that bundles the SDK packages into a browser-compatible format.

## Your responsibility
Your responsibility

When working without a package manager, it becomes your responsibility to:

1. Set up a one-time build environment to create the bundle

1. Select the specific SDK packages your application requires

1. Build and maintain the bundled script file

1. Update the bundle when SDK versions change

## Why a bundle is required
Why a bundle is required

SDK packages use ES module imports like `import { ContactClient } from "@amazon-connect/contact"`. Browsers cannot resolve these package specifiers directly. A bundler resolves these imports, combines the code, and produces a single file the browser can execute.

## Exposing the SDK as a global
Exposing the SDK as a global

When using `<script>` tags, there is no module system to share code between files. The bundle must attach the SDK to a global variable (such as ` window.AmazonConnectSDK`) so your application scripts can access it. This is different from npm-based projects where you import directly from packages.

## Available packages
Available packages

The SDK consists of multiple packages. Select only the packages your application needs. Examples include:


| Package | Purpose | 
| --- | --- | 
|  @amazon-connect/core  | Core SDK functionality and provider types | 
|  @amazon-connect/contact  | ContactClient for contact operations | 
|  @amazon-connect/email  | EmailClient for email channel operations | 
|  @amazon-connect/app  | App initialization for third-party applications | 
|  @amazon-connect/app-manager  | Plugin for hosting Connect first-party apps (Cases, Step-by-Step Guides) | 
|  @amazon-connect/voice  | VoiceClient for voice channel operations | 

See the [Amazon Connect SDK repository](https://github.com/amazon-connect/AmazonConnectSDK) for the complete list of available packages.

# Building the script file
Building the script file

This section provides step-by-step instructions for creating a browser-consumable bundle from the SDK npm packages.

## Prerequisites
Prerequisites

The following prerequisites are required:
+ Node.js 18 or later installed
+ npm (comes with Node.js)
+ A text editor

## Step 1: Create the build project directory
Step 1: Create directory

Create a new directory to hold your build configuration. This directory will contain npm tooling but the output bundle will be usable without npm.

```
mkdir connect-sdk-bundle
cd connect-sdk-bundle
```

## Step 2: Initialize the npm project
Step 2: Initialize npm

```
npm init -y
```

## Step 3: Install the SDK packages you need
Step 3: Install packages

For an email-based solution using EmailClient and ContactClient:

```
npm install @amazon-connect/core @amazon-connect/contact @amazon-connect/email
```

If you are building a third-party app (not embedded in StreamsJS), also install:

```
npm install @amazon-connect/app
```

If you are integrating with StreamsJS and want to host Connect first-party apps (such as Cases or Step-by-Step Guides), also install:

```
npm install @amazon-connect/app-manager
```

## Step 4: Install the bundler
Step 4: Install bundler

Install esbuild, a fast JavaScript bundler:

```
npm install --save-dev esbuild
```

## Step 5: Create the entry file
Step 5: Create entry file

Create a file that imports the SDK modules you need and exposes them as a global:

```
mkdir src
```

 **For StreamsJS integration** (` src/entry-streams.js`):

```
// Entry file for StreamsJS integration
import { ContactClient } from "@amazon-connect/contact";
import { EmailClient } from "@amazon-connect/email";

// Expose the SDK on the window object
window.AmazonConnectSDK = {
  ContactClient,
  EmailClient,
};
```

 **For StreamsJS with first-party apps** (` src/entry-streams-with-apps.js`):

If you want to host Connect first-party apps like Cases or Step-by-Step Guides alongside the CCP, include the app-manager plugin:

```
// Entry file for StreamsJS integration with 1P app support
import { ContactClient } from "@amazon-connect/contact";
import { EmailClient } from "@amazon-connect/email";
import { AppManagerPlugin } from "@amazon-connect/app-manager";

// Expose the SDK on the window object
window.AmazonConnectSDK = {
  AppManagerPlugin,
  ContactClient,
  EmailClient,
};
```

 **For third-party app** (`src/entry-app.js` ):

```
// Entry file for third-party app integration
import { AmazonConnectApp } from "@amazon-connect/app";
import { ContactClient } from "@amazon-connect/contact";
import { EmailClient } from "@amazon-connect/email";

// Expose the SDK on the window object
window.AmazonConnectSDK = {
  AmazonConnectApp,
  ContactClient,
  EmailClient,
};
```

## Step 6: Add build scripts to package.json
Step 6: Add build scripts

Edit `package.json` to add build scripts:

```
{
  "name": "connect-sdk-bundle",
  "version": "1.0.0",
  "scripts": {
    "build:streams": "esbuild src/entry-streams.js --bundle --minify --sourcemap --format=iife --target=es2020 --outfile=dist/connect-sdk-streams.bundle.js",
    "build:app": "esbuild src/entry-app.js --bundle --minify --sourcemap --format=iife --target=es2020 --outfile=dist/connect-sdk-app.bundle.js",
    "build": "npm run build:streams && npm run build:app"
  }
}
```

## Step 7: Build the bundle
Step 7: Build bundle

```
npm run build
```

This creates the following files in the `dist/` directory:
+ `connect-sdk-streams.bundle.js` - Bundle for StreamsJS integration
+ `connect-sdk-streams.bundle.js.map` - Source map for debugging
+ `connect-sdk-app.bundle.js` - Bundle for third-party apps
+ `connect-sdk-app.bundle.js.map` - Source map for debugging

## Step 8: Copy the bundle to your project
Step 8: Copy bundle

Copy the appropriate `.js` file (and optionally the `.map` file for debugging) to your static website's assets folder:

```
cp dist/connect-sdk-streams.bundle.js /path/to/your/website/assets/vendor/
# or
cp dist/connect-sdk-app.bundle.js /path/to/your/website/assets/vendor/
```

## Complete build project structure
Project structure

After completing all steps, your build project should look like this:

```
connect-sdk-bundle/
├── package.json
├── package-lock.json
├── node_modules/
├── src/
│   ├── entry-streams.js
│   └── entry-app.js
└── dist/
    ├── connect-sdk-streams.bundle.js
    ├── connect-sdk-streams.bundle.js.map
    ├── connect-sdk-app.bundle.js
    └── connect-sdk-app.bundle.js.map
```

# Using the SDK with StreamsJS
Using with StreamsJS

This section explains how to use the prebuilt bundle in a solution that uses Amazon Connect Streams (StreamsJS).

## Prerequisites
Prerequisites

The following prerequisites are required:
+ The Amazon Connect Streams library loaded on your page
+ The `connect-sdk-streams.bundle.js` file from the building section

## HTML setup
HTML setup

```
<!DOCTYPE html>
<html>
  <head>
    <title>Connect StreamsJS with SDK</title>
  </head>
  <body>
    <div id="ccp-container" style="width: 400px; height: 600px;"></div>

    <!-- Load Amazon Connect Streams first -->
    <script src="https://your-domain.com/amazon-connect-streams.min.js"></script>

    <!-- Load the SDK bundle -->
    <script src="/assets/vendor/connect-sdk-streams.bundle.js"></script>

    <!-- Your application code -->
    <script src="/app.js"></script>
  </body>
</html>
```

## JavaScript implementation
JavaScript implementation

In your `app.js` file:

```
// Initialize the CCP
var ccpContainer = document.getElementById("ccp-container");

connect.core.initCCP(ccpContainer, {
  ccpUrl: "https://your-instance.my.connect.aws/ccp-v2/",
  loginPopup: true,
  loginPopupAutoClose: true,
});

// Get the SDK provider from Streams after CCP initializes
connect.core.onInitialized(function () {
  // Retrieve the provider from the Streams SDK client config
  var sdkConfig = connect.core.getSDKClientConfig();
  var provider = sdkConfig.provider;

  // Create the SDK clients using the provider
  var contactClient = new AmazonConnectSDK.ContactClient(provider);
  var emailClient = new AmazonConnectSDK.EmailClient(provider);

  // Example: Subscribe to contact lifecycle events
  contactClient.onIncoming(function (event) {
    console.log("Incoming contact:", event.contactId);
  });

  contactClient.onConnected(function (event) {
    console.log("Contact connected:", event.contactId);
  });

  contactClient.onCleared(function (event) {
    console.log("Contact cleared:", event.contactId);
  });
});
```

## Hosting Connect first-party apps (optional)
Hosting first-party apps

If you want to host Connect first-party apps like Cases or Step-by-Step Guides alongside your CCP, include the `@amazon-connect/app-manager` package in your bundle and apply the plugin during CCP initialization:

```
connect.core.initCCP(ccpContainer, {
  ccpUrl: "https://your-instance.my.connect.aws/ccp-v2/",
  loginPopup: true,
  loginPopupAutoClose: true,
  // Apply the plugin to enable 1P app hosting
  plugins: AmazonConnectSDK.AppManagerPlugin,
});
```

## Key points for StreamsJS integration
Key points

1. Load the Streams library before the SDK bundle

1. Retrieve the provider using ` connect.core.getSDKClientConfig().provider` after CCP initializes

1. Instantiate SDK clients with `new AmazonConnectSDK.ContactClient(provider)`

1. The `AppManagerPlugin` is only required if hosting Connect first-party apps

# Using the SDK in a 3P app
Using in 3P app

This section explains how to use the prebuilt bundle in a third-party application that runs within the Amazon Connect Agent Workspace.

## Prerequisites
Prerequisites

The following prerequisites are required:
+ Your application is registered as a third-party app in Amazon Connect
+ The `connect-sdk-app.bundle.js` file from the building section

## HTML setup
HTML setup

```
<!DOCTYPE html>
<html>
  <head>
    <title>Connect Third-Party App</title>
  </head>
  <body>
    <div id="app-container"></div>

    <!-- Load the SDK bundle -->
    <script src="/assets/vendor/connect-sdk-app.bundle.js"></script>

    <!-- Your application code -->
    <script src="/app.js"></script>
  </body>
</html>
```

## JavaScript implementation
JavaScript implementation

In your `app.js` file:

```
// Initialize the third-party app - this must be called first
var initResult = AmazonConnectSDK.AmazonConnectApp.init({
  // Optional lifecycle callbacks
  onCreate: function (event) {
    console.log("App created");
  },
  onDestroy: function (event) {
    console.log("App destroyed");
  },
});

// Get the provider from the init result
var provider = initResult.provider;

// Create the SDK clients using the provider
var contactClient = new AmazonConnectSDK.ContactClient(provider);
var emailClient = new AmazonConnectSDK.EmailClient(provider);

// Example: Subscribe to contact lifecycle events
contactClient.onIncoming(function (event) {
  console.log("Incoming contact:", event.contactId);
});

contactClient.onConnected(function (event) {
  console.log("Contact connected:", event.contactId);
});

contactClient.onCleared(function (event) {
  console.log("Contact cleared:", event.contactId);
});
```

## Key points for third-party apps
Key points

1. Call `AmazonConnectSDK.AmazonConnectApp.init()` before using any SDK functionality

1. The `init()` function returns an object containing the ` provider`

1. Instantiate SDK clients with `new AmazonConnectSDK.ContactClient(provider)`

1. Lifecycle callbacks (`onCreate`, `onDestroy`) are optional but useful for managing app state

# Updating the bundle
Updating the bundle

When a new version of the SDK is released:

1. Navigate to your build project directory

1. Update the SDK packages:

   ```
   npm update @amazon-connect/core @amazon-connect/contact @amazon-connect/email
   ```

1. Rebuild the bundle:

   ```
   npm run build
   ```

1. Copy the new bundle to your website

1. Test your application to verify compatibility

# Troubleshooting
Troubleshooting

This section describes common issues and resolutions when using the SDK without a package manager.

## Bundle is too large
Bundle is too large

If the bundle size is a concern, ensure you only import the packages you need. Each additional package increases bundle size.

## "AmazonConnectSDK is not defined" error
SDK not defined error

Verify that the bundle script tag appears before your application script in the HTML, and that the path to the bundle file is correct.

## Provider is undefined
Provider is undefined

 **For StreamsJS:** Ensure you are accessing the provider after `connect.core.onInitialized()` fires.

 **For third-party apps:** Ensure you call ` AmazonConnectSDK.AmazonConnectApp.init()` and capture its return value.

## SDK methods not working
SDK methods not working

Verify you passed the provider when creating the clients. The provider establishes the communication channel between your code and Amazon Connect.