npm package: @iterable/web-sdk
Description: Iterable SDK for JavaScript and Node.
Author: Iterable
Latest version: 2.2.2

![Iterable-Logo](https://user-images.githubusercontent.com/7387001/129065810-44b39e27-e319-408c-b87c-4d6b37e1f3b2.png)

# Iterable's Web SDK

[Iterable](https://www.iterable.com) is a growth-marketing platform that helps
you to create better experiences for—and deeper relationships with—your customers. 
Use it to send customized email, SMS, push notification, in-app message,
embedded message, and web push notification campaigns to your customers.

This SDK helps you integrate your web apps with Iterable.

# Table of contents

- [Other documentation](#other-documentation)
- [Installation](#installation)
- [Functions](#functions)
- [Classes, interfaces, types, and enums](#classes-interfaces-types-and-enums)
- [FAQ](#faq)
- [Link handling](#link-handling)
- [TypeScript](#typescript)
- [Development and Testing](#development-and-testing)
- [Contributing](#contributing)
- [License](#license)

# Other documentation

This document contains reference information about the Web SDK. For other
information, please see:

- [In-Browser Messaging Overview](https://support.iterable.com/hc/articles/4418166649748)
- [Embedded Messaging Overview](https://support.iterable.com/hc/articles/23060529977364)
- [Overview of Iterable's Web SDK](https://support.iterable.com/hc/articles/10359708795796)
- [Setting up Iterable's Web SDK](https://support.iterable.com/hc/articles/4419628585364)
- [Embedded Messages with Iterable's Web SDK](https://support.iterable.com/hc/articles/27537816889108)

# Using the SDK

In general, to use the SDK, you'll need to follow these steps:

1. In Iterable, [create a JWT-enabled, web API key](https://support.iterable.com/hc/articles/360043464871). 
   The SDK can use this key to authenticate with Iterable's API endpoints. This
   will ensure the SDK has access to all the necessary. Save the API key and
   its associated JWT secret, since you'll need them both.

2. Work with your Engineering team to create a web service the SDK can call
   to fetch a valid JWT token for the signed-in user. To learn more about how
   to do this, read [JWT-Enabled API Keys](https://support.iterable.com/hc/articles/360050801231).

3. [Install](#installation) the SDK in your web app.

4. Use the API key to initialize the SDK, as described in [`initialize`](#initialize) 
   and [`initializeWithConfig`](#initializewithconfig). When you initialize the 
   SDK, pass in a method that can call the web service (created in step 2)
   to fetch a valid JWT token for the signed-in user.

5. To identify the user to the SDK, call `setEmail` or `setUserID` (returned by 
   [`initialize`](#initialize) or [`initializeWithConfig`](#initializewithconfig)). 
   The SDK uses the user's `email` or `userId` to fetch a valid JWT token from 
   your server. 

6. After the SDK successfully sets the user's `email` or `userId` and the SDK
   fetches a JWT token, you can make API requests to Iterable. For example, you
   can call [`track`](#track) to track events, or [`getInAppMessages`](#getinappmessages) 
   to fetch in-app messages, etc. Other methods are described [below](#functions).

# Installation

To install the SDK, use Yarn, npm, or a `script` tag:

- npm

  ```
  npm install @iterable/web-sdk
  ```

- Yarn

  ```
  yarn add @iterable/web-sdk
  ```

- `script` tag

  ```js
  <script src="https://unpkg.com/@iterable/web-sdk/index.js"></script>
  ```

⚠️ Node.js Version Requirement
Important: This SDK requires Node.js as defined in `package.json`.

Please ensure your development environment meets the minimum required Node.js version. Depending on your current setup, you may already be using a compatible version. If not, you will need to upgrade Node.js to proceed with installation and use of the SDK.

You can check your current Node version by running:

```bash
node -v
```

If an upgrade is needed, we recommend using nvm or your preferred version manager for easy installation.

# Functions

Iterable's Web SDK exposes the following functions, which you can use in your
website code.

For information about the data the SDK sends and receives when making calls to
Iterable's API, see the [API Overview](https://support.iterable.com/hc/articles/204780579).

| Method Name                                                                       | Description |
| --------------------------------------------------------------------------------- | ----------- |
| [`baseIterableRequest`](#baseiterablerequest)                                     |  Executes a custom API request to Iterable, using an extended request configuration for validation and optional features. Valid for web API keys and their supported endpoints only. [Learn more](https://support.iterable.com/hc/articles/360043464871-API-Keys#client-side-keys)  |
| [`filterHiddenInAppMessages`](#filterhiddeninappmessages)                         | From an array of passed-in in-app messages, filters out messages that have already been read, messages that should not be displayed, and messages that only contain JSON data. |
| [`filterOnlyReadAndNeverTriggerMessages`](#filteronlyreadandnevertriggermessages) | From an array of passed-in in-app messages, filters out messages that have already been read and messages that should not be displayed. |
| [`getInAppMessages`](#getInAppMessages)                                           | Fetches in-app messages by calling [`GET /api/inApp/getMessages`](https://support.iterable.com/hc/articles/204780579#get-api-inapp-getmessages). |
| [`initialize`](#initialize)                                                       | Initializes the SDK with an API key and a JWT refresh method. Returns methods you can use to identify the current user, work with JWT tokens, and log the user out (see [`WithJWT`](#withjwt)). |
| [`initializeWithConfig`](#initializeWithConfig)                                   | Similar to `initialize`, but also takes a set of configuration options as a parameter. Returns methods you can use to identify the current user, work with JWT tokens, and log the user out (see [`WithJWT`](#withjwt)). |
| [`IterableEmbeddedCard`](#iterableembeddedcard)                                   | Returns a string of the HTML for an out-of-the-box [card](https://support.iterable.com/hc/articles/23230946708244#cards) view for an embedded message. |
| [`IterableEmbeddedBanner`](#iterableembeddedbanner)                               | Returns a string of the HTML for an out-of-the-box [banner](https://support.iterable.com/hc/articles/23230946708244#banners) view for an embedded message. |
| [`IterableEmbeddedNotification`](#iterableembeddednotification)                   | Returns a string of the HTML for an out-of-the-box [notification](https://support.iterable.com/hc/articles/23230946708244#notifications) view for an embedded message. |
| [`sortInAppMessages`](#sortinappmessages)                                         | Sorts an array of in-app messages by priority, and then creation date. |
| [`track`](#track)                                                                 | Tracks a custom event by calling [`POST /api/events/track`](https://support.iterable.com/hc/articles/204780579#post-api-events-track). |
| [`trackEmbeddedClick`](#trackEmbeddedClick)                                       | Tracks an [`embeddedClick`](https://support.iterable.com/hc/articles/23061677642260#embeddedclick-events) event by calling [`POST /api/embedded-messaging/events/click`](https://support.iterable.com/hc/articles/204780579#post-api-embedded-messaging-events-click). |
| [`trackEmbeddedReceived`](#trackEmbeddedReceived)                                 | Tracks an [`embeddedReceived`](https://support.iterable.com/hc/articles/23061677642260#embeddedreceived-events) event by calling [`POST /api/embedded-messaging/events/received`](https://support.iterable.com/hc/articles/204780579#post-api-embedded-messaging-events-received). |
| [`trackEmbeddedSession`](#trackEmbeddedSession)                                   | Tracks an [`embeddedSession`](https://support.iterable.com/hc/articles/23061677642260#embeddedsession-events) event and related [`embeddedImpression`](https://support.iterable.com/hc/articles/23061677642260#embeddedimpression-events) events by calling [`POST /api/embedded-messaging/events/session`](https://support.iterable.com/hc/articles/204780579#post-api-embedded-messaging-events-session). |                                                                                            |
| [`trackInAppClick`](#trackInAppClick)                                             | Tracks an `inAppClick` event by calling [`POST /api/events/trackInAppClick`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappclick). |
| [`trackInAppClose`](#trackInAppClose)                                             | Tracks an `inAppClose` event by calling [`POST /api/events/trackInAppClose`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappclose). |
| [`trackInAppConsume`](#trackInAppConsume)                                         | Deletes an in-app message from the server by calling [`POST /api/events/trackInAppConsume`](https://support.iterable.com/hc/articles/204780579#post-api-events-inappconsume). |
| [`trackInAppDelivery`](#trackInAppDelivery)                                       | Tracks an `inAppDelivery` event by calling [`POST /api/events/trackInAppDelivery`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappdelivery). |
| [`trackInAppOpen`](#trackInAppOpen)                                               | Tracks an `inAppOpen` event by calling [`POST /api/events/trackInAppOpen`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappopen). |
| [`trackPurchase`](#trackPurchase)                                                 | Tracks a `purchase` event by calling [`POST /api/commerce/trackPurchase`](https://support.iterable.com/hc/articles/204780579#post-api-commerce-trackpurchase). |
| [`updateCart`](#updateCart)                                                       | Updates the shopping cart items on the user's Iterable profile by calling [`POST /api/commerce/updateCart`](https://support.iterable.com/hc/articles/204780579#post-api-commerce-updatecart). |
| [`updateSubscriptions`](#updateSubscriptions)                                     | Updates the user's subscriptions by calling [`POST /api/users/updateSubscriptions`](https://support.iterable.com/hc/articles/204780579#post-api-users-updatesubscriptions). |
| [`updateUser`](#updateUser)                                                       | Updates the data on a user's Iterable profile by calling [`POST /api/users/updateUser`](https://support.iterable.com/hc/articles/204780579#post-api-users-update). |
| [`updateUserEmail`](#updateUserEmail)                                             | Updates the current user's `email` by calling [`POST /api/users/updateEmail`](https://support.iterable.com/hc/articles/204780579#post-api-users-updateemail). Causes the SDK to fetch a JWT for the new email address. |
| [`setVisitorUsageTracked`](#setVisitorUsageTracked)                                 | Enables or disables unknown visitor tracking based on user consent (UUA). Returned by `initialize`/`initializeWithConfig`. |
| [`clearVisitorEventsAndUserData`](#clearVisitorEventsAndUserData)                 | Clears unknown visitor session data and queued events (UUA). Returned by `initialize`/`initializeWithConfig`. |

Notes:

- The SDK does not track `inAppDelete` events.

- :rotating_light: Due to a limitation in WebKit (which affects iOS web browsers,
  like Safari), in-app messages displayed in an iOS web browser browser can't 
  automatically track `inAppClick`  events or handle custom CTAs. This will impact
  analytics for all Safari and mobile iOS users.

## `baseIterableRequest`

Executes a custom API request to Iterable, using an extended request configuration for validation and optional features. Valid for web API keys and their supported endpoints only. [Learn more](https://support.iterable.com/hc/articles/360043464871-API-Keys#client-side-keys) 

```ts
function baseIterableRequest(
  payload: ExtendedRequestConfig
): IterablePromise<T = any>
```

Parameters:
- `payload` - A request config see [`ExtendedRequestConfig`](#extendedrequestconfig)

Example:
```ts
baseIterableRequest<IterableResponse>({
        method: 'GET',
        url: '/embedded-messaging/messages',
        params: {
          placementIds: [1, 2, 3],
          platform: 'Web',
          sdkVersion: '1.0.0',
          packageName: 'pkgName'
        }
      });
```

See also:

- [`IterablePromise`](#iterablepromise)

## `filterHiddenInAppMessages`

From an array of passed-in in-app messages, filters out messages that have
already been read, messages that should not be displayed, and messages that only
contain JSON data.

```ts
const filterHiddenInAppMessages = (
  messages: Partial<InAppMessage>[] = []
): Partial<InAppMessage>[]
```

See also:

- [`InAppMessage`](#inappmessage)

## `filterOnlyReadAndNeverTriggerMessages`

From an array of passed-in in-app messages, filters out messages that have
already been read and messages that should not be displayed.

```ts
const filterOnlyReadAndNeverTriggerMessages = (
  messages: Partial<InAppMessage>[] = []
): Partial<InAppMessage>[]
```

See also:

- [`InAppMessage`](#inappmessage)

## `getInAppMessages`

Fetches in-app messages by calling [`GET /api/inApp/getMessages`](https://support.iterable.com/hc/articles/204780579#get-api-inapp-getmessages).

```ts
// Returns a promise that resolves to an InAppMessageResponse, which has an
// array of fetched in-app messages.
function getInAppMessages(
  payload: InAppMessagesRequestParams
): IterablePromise<InAppMessageResponse>;

// Returns methods to request messages from the server, pause message display, 
// restart message display, and trigger the display of a message.
function getInAppMessages(
  payload: InAppMessagesRequestParams,
  options: {
    display: DisplayOptions;
  }
): GetInAppMessagesResponse

```

`payload` options (see [`InAppMessagesRequestParams`](#inappmessagesrequestparams)):

| Property Name               | Description                                                                                                                                                                                                                                                                                | Value                                                             | Default     |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | ----------- |
| `animationDuration`         | How long (in ms) it should take messages to animate in and out                                                                                                                                                                                                                            | `number`                                                          | `400`       |
| `bottomOffset`              | How much space (px or %) to create between the bottom of the screen and a message. Not applicable for center, top, or full-screen messages.                                                                                                                                                | `string`                                                          | `undefined` |
| `closeButton`               | Properties that define a custom close button to display on a message.                                                                                                                                                                                                                      | `CloseButtonOptions` (see below)                                  | `undefined` |
| `displayInterval`           | How long (in ms) to wait before showing the next in-app message after closing the currently open one                                                                                                                                                                                     | `number`                                                          | `30000`     |
| `handleLinks`               | How to open links. If `undefined`, use browser-default behavior. `open-all-new-tab` opens all in new tab, `open-all-same-tab` opens all in same tab, `external-new-tab` opens only off-site links in new tab, otherwise same tab. Overrides the target attribute defined on link elements. | `'open-all-new-tab' \| 'open-all-same-tab' \| 'external-new-tab'` | `undefined` |
| `onOpenNodeToTakeFocus`     | The DOM element that should receive keyboard focus when the in-app message opens. Any query selector is valid. If not specified, the first interactive element receives focus.                                                                                                             | `string`                                                          | `undefined` |
| `onOpenScreenReaderMessage` | The text a screen reader should read when opening the message.                                                                                                                                                                                                                             | `string`                                                          | `undefined` |
| `rightOffset`               | The amount of space (px or %) to create between the right of the screen and the message. Not applicable for center or full-screen messages.                                                                                                                                                | `string`                                                          | `undefined` |
| `topOffset`                 | How much space (px or %) to create between the top of the screen and a message. Not applicable for center, bottom, or full-screen messages.                                                                                                                                                | `string`                                                          | `undefined` |

`closeButton` options (see [`CloseButton`](#closebutton)):

| Property Name               | Description                                                                  | Value                      | Default       |
| --------------------------- | ---------------------------------------------------------------------------- | -------------------------- | ------------- |
| `color`                     | The button's color (does not affect custom icons)                            | `string`                   | `undefined`   |
| `iconPath`                  | Custom pathname to an image or SVG to use (instead of the default "X")       | `string`                   | `undefined`   |
| `isRequiredToDismissMessage`| If `true`, users cannot dismiss in-app messages by clicking outside of them. | `boolean`                  | `undefined`   |
| `position`                  | Where the button should display on an in-app message                         | `'top-right' \| 'top-left'`| `'top-right'` |
| `sideOffset`                | How much space to leave between the button and side of the container         | `string`                   | `'4%'`        |
| `size`                      | How large to set the width, height, and font-size                            | `string \| number`         | `24`          |
| `topOffset`                 | How much space to leave between the button and the top of the container      | `string`                   | `'4%'`        |

Example:

```ts
import { getInAppMessages } from '@iterable/web-sdk';

getInAppMessages({ count: 20, packageName: 'mySite1' })
  .then((resp) => {
    // This is an iframe element that can be attached to the DOM 
    const messageIframe = resp.data.inAppMessages[0].content.html;
    document.body.appendChild(messageIframe);
    // Additional styling logic can be done here to render the message in a 
    // custom way
  })
  .catch();
```

This code, which doesn't include the `options` parameter, fetches in-app messages
from Iterable and places the first one on the page. However, it won't be visible.
To render it, modify the page's CSS to display the message as necessary. You'll
also need to set up click handlers to handle click events, close the message,
etc.

Here's some example code that shows messages automatically:

```ts
import { getInAppMessages } from '@iterable/web-sdk';

const { request, pauseMessageStream, resumeMessageStream } = getInAppMessages(
  {
    count: 20,
    packageName: 'my-website',
    displayInterval: 5000,
    onOpenScreenReaderMessage:
      'The screen reader will read this',
    onOpenNodeToTakeFocus: 'input',
    closeButton: {
      color: 'red',
      size: '16px',
      topOffset: '20px'
    }
  },
  { display: 'immediate' }
);

request().then().catch();
```

This example uses custom sorting and filtering, and displays messages at the
app's discretion:

```ts
import {
  getInAppMessages,
  sortInAppMessages,
  filterHiddenInAppMessages
} from '@iterable/web-sdk';

const {
  request,
  pauseMessageStream,
  resumeMessageStream,
  triggerDisplayMessages
} = getInAppMessages(
  {
    count: 20,
    packageName: 'my-website',
    displayInterval: 5000,
    onOpenScreenReaderMessage: 'The screen reader will read this',
    onOpenNodeToTakeFocus: 'input',
    closeButton: {
      color: 'red',
      size: '16px',
      topOffset: '20px'
    }
  },
  { display: 'deferred' }
);

request()
  .then((response) => {
    // Do your own manipulation here 
    const filteredMessages = yourOwnSortingAndFiltering(response.data.inAppMessages);

    // Or, feel free to take advantage of the sorting/filtering methods used 
    // internally
    const furtherManipulatedMessages = sortInAppMessages(
      filterHiddenInAppMessages(response.data.inAppMessages)
    ) as InAppMessage[];

    // Then display them whenever you want
    triggerDisplayMessages(furtherManipulatedMessages);
  })
  .catch();
```

:rotating_light: With the `deferred` option, the SDK does **not** filter or sort
the messages. The messages come back exactly as retrieved from the API, without
modification. This means that you may (for example) show in-app messages marked as
`read`, or show messages in the default order (based on `priority`), rather
than a custom order that you control.

In this case, to apply the SDK's default sorting and filtering, use the 
[`sortInAppMessages`](#sortinappmessages) and [`filterHiddenInAppMessages`](#filterhiddeninappmessages) 
methods. Also, see [`filterOnlyReadAndNeverTriggerMessages`](#filteronlyreadandnevertriggermessages), 
which is similar to `filterHiddenInAppMessages` but does not filter out 
JSON-only messages.

Notes:

- :rotating_light: [v1.0.0](https://github.com/Iterable/iterable-web-sdk/releases/tag/v1.0.0) 
  of this SDK removes support for `showMessagesAutomatically?: boolean`. If needed, 
  please update your `getInAppMessages` requests to use `options: { display: 'deferred' | 'immediate' }`.

See also: 

- [`DisplayOptions`](#displayoptions)
- [`GetInAppMessagesResponse`](#getinappmessagesresponse)
- [`InAppMessagesRequestParams`](#inappmessagesrequestparams)
- [`InAppMessageResponse`](#inappmessageresponse)
- [`IterablePromise`](#iterablepromise)

## `initialize`

Initializes the SDK with an API key and a JWT refresh method. Returns methods
you can use to identify the current user, work with JWT tokens, and log the 
user out (see [`WithJWT`](#withjwt)).

```ts
function initialize(
  authToken: string,
  generateJWT: (payload: GenerateJWTPayload) => Promise<string>
): WithJWT;
```

`generateJWT` should be a function that takes a `userId` or `email` and uses
it to fetch, from your server, a valid JWT token for that user. The function
should return the token as a string.

Example:

```ts
import { initialize } from '@iterable/web-sdk';

const { clearRefresh, setEmail, setUserID, logout } = initialize(
  '<YOUR_API_KEY>',
  // email will be defined if you call setEmail 
  // userID_ will be defined if you call setUserID
  ({ email, userID }) =>
    yourAsyncJWTGeneratorMethod({ email, userID }).then(
      ({ jwt_token }) => jwt_token
    )
);
```

See also:

- [`GenerateJWTPayload`](#generatejwtpayload) 
- [`WithJWT`](#withjwt)

## `initializeWithConfig`

Similar to `initialize`, but also takes a set of configuration options as a 
parameter. Returns methods you can use to identify the current user, work with
JWT tokens, and log the user out (see [`WithJWT`](#withjwt)).

The configuration options you can pass to this function are useful if you
need to [point the SDK to Iterable's EU API endpoints](#iterables-european-data-center-eudc) 
or [allow JavaScript execution in Safari tabs](#safari-allowing-javascript-execution-in-tabs-opened-by-in-app-message-link-clicks).

```ts
function initializeWithConfig(initializeParams: WithJWTParams): WithJWT;
```

Example:

```ts
import { initializeWithConfig } from '@iterable/web-sdk';

const { clearRefresh, setEmail, setUserID, logout } = initializeWithConfig({
  authToken: '<YOUR_API_KEY>',
  configOptions: {
    isEuIterableService: false,
    dangerouslyAllowJsPopups: true,
  },
  
  // email will be defined if you call setEmail
  // userID will be defined if you call setUserID
  generateJWT: ({ email, userID }) =>
    yourAsyncJWTGeneratorMethod({ email, userID }).then(
      ({ jwt_token }) => jwt_token
    )
}
);
```

`generateJWT` should be a function that takes a `userId` or `email` and uses
it to fetch, from your server, a valid JWT token for that user. The function
should return the token as a string.

See also:

- [`WithJWT`](#withjwt)
- [`WithJWTParams`](#withjwtparams)

## `IterableEmbeddedCard`

Returns a string of the HTML for an out-of-the-box [card](https://support.iterable.com/hc/articles/23230946708244#cards) 
view for an embedded message.

```ts
const emptyElement = {
  id: '',
  styles: ''
};

function IterableEmbeddedCard({
  appPackageName,
  message,
  htmlElements = {
    parent: emptyElement,
    img: emptyElement,
    title: emptyElement,
    primaryButton: emptyElement,
    secondaryButton: emptyElement,
    body: emptyElement,
    buttonsDiv: emptyElement,
    textTitle: emptyElement
  },
  errorCallback
}: OOTB): string
```

Parameters:

- `appPackageName` – The package name you use to identify your website to
  Iterable's Web SDK.
- `message` – The `IterableEmbeddedMessage` object that represents the
  message you want to display.
- `htmlElements` – Custom styles (type [`Elements`](#elements)) for the SDK to use 
  when displaying the embedded message. For details, see [Custom Styles](https://support.iterable.com/hc/articles/27537816889108#custom-styles).
- `errorCallback` – A callback that the SDK calls if it encounters an error
  when tracking [`embeddedClick`](https://support.iterable.com/hc/articles/23061677642260#embeddedclick-events) 
  events.

```js
import { IterableEmbeddedCard } from '@iterable/web-sdk';

const card = IterableEmbeddedCard({
  appPackageName,
  message,
  htmlElements,
  errorCallback: (error) => console.log('handleError: ', error)
});
```

To display the message, set the `innerHTML` of an HTML element to the string
returned by `IterableEmbeddedCard`.

For more info, see:

- [Out-of-the-Box Views](https://support.iterable.com/hc/articles/27537816889108#out-of-the-box-views).
- For default card styles, see the [`src/components/card/styles.ts`](https://github.com/Iterable/iterable-web-sdk/blob/main/src/components/card/styles.ts)
  in the Web SDK GitHub repository. 
- To learn how to apply custom styles, see [Custom Styles](https://support.iterable.com/hc/articles/27537816889108#custom-styles).

Also see:

- [`Elements`](#elements)
- [`OOTB`](#ootb)

## `IterableEmbeddedBanner`

Returns a string of the HTML for an out-of-the-box [banner](https://support.iterable.com/hc/articles/23230946708244#banners) 
view for an embedded message.

```ts
function IterableEmbeddedBanner({
  appPackageName,
  message,
  htmlElements = {
    parent: emptyElement,
    img: emptyElement,
    title: emptyElement,
    primaryButton: emptyElement,
    secondaryButton: emptyElement,
    body: emptyElement,
    buttonsDiv: emptyElement,
    textTitle: emptyElement,
    textTitleImg: emptyElement
  },
  errorCallback
}: OOTB): string 
```

Parameters:

- `appPackageName` – The package name you use to identify your website to
  Iterable's Web SDK.
- `message` – The `IterableEmbeddedMessage` object that represents the message 
  you want to display.
- `htmlElements` – Custom styles (type [`Elements`](#elements)) for the SDK to use 
  when displaying the embedded message. For details, see [Custom Styles](https://support.iterable.com/hc/articles/27537816889108#custom-styles).
- `errorCallback` – A callback that the SDK calls if it encounters an error
  when tracking [`embeddedClick`](https://support.iterable.com/hc/articles/23061677642260#embeddedclick-events) 
  events.

For example:

```js
import { IterableEmbeddedBanner } from '@iterable/web-sdk';

const banner = IterableEmbeddedBanner({
  appPackageName,
  message,
  htmlElements,
  errorCallback: (error) => console.log('handleError: ', error)
});
```

To display the message, set the `innerHTML` of an HTML element to the string
returned by `IterableEmbeddedBanner`.

For more info, see:

- [Creating an Out-of-the-Box View](https://support.iterable.com/hc/articles/27537816889108).
- For default banner styles, see the [`src/components/banner/styles.ts`](https://github.com/Iterable/iterable-web-sdk/blob/main/src/components/banner/styles.ts)
  in the Web SDK GitHub repository. 
- To learn how to apply custom styles, see [Custom Styles](https://support.iterable.com/hc/articles/27537816889108#custom-styles).

Also see:

- [`OOTB`](#ootb)
- [`Elements`](#elements)

## `IterableEmbeddedNotification`

Returns a string of the HTML for an out-of-the-box [notification](https://support.iterable.com/hc/articles/23230946708244#notifications) 
view for an embedded message.

```ts
function IterableEmbeddedNotification({
  appPackageName,
  message,
  htmlElements = {
    parent: emptyElement,
    title: emptyElement,
    primaryButton: emptyElement,
    secondaryButton: emptyElement,
    body: emptyElement,
    buttonsDiv: emptyElement,
    textTitle: emptyElement
  },
  errorCallback
}: OOTB): string
```

Parameters:

- `appPackageName` – The package name you use to identify your website to
  Iterable's Web SDK.
- `message` – The `IterableEmbeddedMessage` object that represents the message 
  you want to display.
- `htmlElements` – Custom styles (type [`Elements`](#elements)) for the SDK to use 
  when displaying the embedded message. For details, see [Custom Styles](https://support.iterable.com/hc/articles/27537816889108#custom-styles).
- `errorCallback` – A callback that the SDK calls if it encounters an error
  when tracking [`embeddedClick`](https://support.iterable.com/hc/articles/23061677642260#embeddedclick-events) 
  events.

```js
import { IterableEmbeddedNotification } from '@iterable/web-sdk';

const notification = IterableEmbeddedNotification({
  appPackageName,
  message,
  htmlElements,
  errorCallback: (error) => console.log('handleError: ', error)
});
```

To display the message, set the `innerHTML` of an HTML element to the string
returned by `IterableEmbeddedNotification`.

For more info, see:

- [Creating an Out-of-the-Box View](https://support.iterable.com/hc/articles/27537816889108).
- For default notification styles, see the [`src/components/notification/styles.ts`](https://github.com/Iterable/iterable-web-sdk/blob/main/src/components/notification/styles.ts)
- To learn how to apply custom styles, see [Custom Styles](https://support.iterable.com/hc/articles/27537816889108#custom-styles).

Also see:

- [`OOTB`](#ootb)
- [`Elements`](#elements)

## `sortInAppMessages`

Sorts an array of in-app messages by priority, and then creation date.

```ts
const sortInAppMessages = (messages: Partial<InAppMessage>[] = []) => {
  return messages.sort(by(['priorityLevel', 'asc'], ['createdAt', 'asc']));
};
```

In-app messages can have these [priority values](https://support.iterable.com/hc/articles/7412316462996#display-priority):

- Low - `priorityLevel` of 400.5
- Medium - `priorityLevel` of 300.5
- High - `priorityLevel` of 200.5
- Critical - `priorityLevel` of 100.5
- Proof - `priorityLevel` of 100.0

Also see:

- [`InAppMessage`](#inappmessage)

## `track`

Tracks a custom event by calling [`POST /api/events/track`](https://support.iterable.com/hc/articles/204780579#post-api-events-track).

```ts
track: (payload: InAppTrackRequestParams): IterablePromise<IterableResponse>
```
 
Example:

```ts
import { track } from '@iterable/web-sdk';

track({ eventName: 'my-event' }).then().catch();
```

See also:

- [`InAppTrackRequestParams`](#inapptrackrequestparams)
- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)

## `trackEmbeddedClick`

Tracks an [`embeddedClick`](https://support.iterable.com/hc/articles/23061677642260#embeddedclick-events) 
event by calling [`POST /api/embedded-messaging/events/click`](https://support.iterable.com/hc/articles/204780579#post-api-embedded-messaging-events-click).

```ts
const trackEmbeddedClick = (
  payload: IterableEmbeddedClickRequestPayload
): IterablePromise<IterableResponse>
```

Example:

```js
import { trackEmbeddedClick } from '@iterable/web-sdk';

trackEmbeddedClick({
  messageId: message.metadata.messageId,
  buttonIdentifier: button.id,
  targetUrl: defaultUrl,
  appPackageName
}).then((response) => {
  if (response.status != 200) {
    console.log("Failure tracking embedded click")
  }
}).catch((error) => {
  console.log("Error tracking embedded click: ", error);
});
```

See also:

- [`IterableEmbeddedClickRequestPayload`](#iterableembeddedclickrequestpayload)
- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)

## `trackEmbeddedReceived`

Tracks an [`embeddedReceived`](https://support.iterable.com/hc/articles/23061677642260#embeddedreceived-events) 
event by calling [`POST /api/embedded-messaging/events/received`](https://support.iterable.com/hc/articles/204780579#post-api-embedded-messaging-events-received).

Generally, there's no need to call this method, since the SDK automatically 
tracks an `embeddedReceived` event for each message it fetches from the server.

```ts
const trackEmbeddedReceived = (
  messageId: string,
  appPackageName: string
): IterablePromise<IterableResponse>
```

Example:

```ts
import { trackEmbeddedReceived } from '@iterable/web-sdk';

trackEmbeddedReceived(messageId, packageName)
  .then((response: any) => {
    setTrackResponse(JSON.stringify(response.data));
    setTrackingEvent(false);
  })
  .catch((error: any) => {
    setTrackResponse(JSON.stringify(error.response.data));
    setTrackingEvent(false);
  });
```

See also:

- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)

## `trackEmbeddedSession`

Tracks an [`embeddedSession`](https://support.iterable.com/hc/articles/23061677642260#embeddedsession-events) 
event and related [`embeddedImpression`](https://support.iterable.com/hc/articles/23061677642260#embeddedimpression-events)
events by calling [`POST /api/embedded-messaging/events/session`](https://support.iterable.com/hc/articles/204780579#post-api-embedded-messaging-events-session).

Generally, rather than calling this method, you'll track sessions and impresions 
using the SDK's [`IterableEmbeddedSessionManager`](#iterableembeddedsessionmanager).

```ts
const trackEmbeddedSession = (
  payload: IterableEmbeddedSessionRequestPayload
): IterablePromise<IterableResponse>
```

Example:

```ts
import { trackEmbeddedSession } from '@iterable/web-sdk';

trackEmbeddedSession(sessionData)
  .then((response: any) => {
    setTrackResponse(JSON.stringify(response.data));
    setTrackingEvent(false);
  })
  .catch((error: any) => {
    setTrackResponse(JSON.stringify(error.response.data));
    setTrackingEvent(false);
  });
```

See also:

- [`IterableEmbeddedSessionRequestPayload`](#iterableembeddedsessionrequestpayload)
- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)

## `trackInAppClick`

Tracks an `inAppClick` event by calling [`POST /api/events/trackInAppClick`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappclick).

```ts
const trackInAppClick = (
  payload: Omit<InAppEventRequestParams, 'inboxSessionId' | 'closeAction'>,
  sendBeacon = false
): IterablePromise<IterableResponse>
```

Example:

```ts
import { trackInAppClick } from '@iterable/web-sdk';

trackInAppClick({
  messageId: '123',
  deviceInfo: { appPackageName: 'my-website' }
})
  .then()
  .catch();
```

See also:

- [`InAppEventRequestParams`](#inappeventrequestparams)
- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)

## `trackInAppClose`

Tracks an `inAppClose` event by calling [`POST /api/events/trackInAppClose`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappclose).

```ts
const trackInAppClose = (payload: InAppEventRequestParams): IterablePromise<IterableResponse>
```

Example:

```ts
import { trackInAppClose } from '@iterable/web-sdk';

trackInAppClose({
  messageId: '123',
  deviceInfo: { appPackageName: 'my-website' }
})
  .then()
  .catch();
```

See also:

- [`InAppEventRequestParams`](#inappeventrequestparams)
- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)

## `trackInAppConsume`

Deletes an in-app message from the server by calling [`POST /api/events/trackInAppConsume`](https://support.iterable.com/hc/articles/204780579#post-api-events-inappconsume).

```ts
const trackInAppConsume = (
  payload: Omit<
    InAppEventRequestParams,
    'clickedUrl' | 'closeAction' | 'inboxSessionId'
  >
): IterablePromise<IterableResponse>
```

Example:

```ts
import { trackInAppConsume } from '@iterable/web-sdk';

trackInAppConsume({
  messageId: '123',
  deviceInfo: { appPackageName: 'my-website' }
})
  .then()
  .catch();
```

See also:

- [`InAppEventRequestParams`](#inappeventrequestparams)
- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)

## `trackInAppDelivery`

Tracks an `inAppDelivery` event by calling [`POST /api/events/trackInAppDelivery`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappdelivery).

```ts
const trackInAppDelivery = (
  payload: Omit<
    InAppEventRequestParams,
    'clickedUrl' | 'closeAction' | 'inboxSessionId'
  >
): IterablePromise<IterableResponse>
```

Example:

```ts
import { trackInAppDelivery } from '@iterable/web-sdk';

trackInAppDelivery({
  messageId: '123',
  deviceInfo: { appPackageName: 'my-website' }
})
  .then()
  .catch();
```

See also:

- [`InAppEventRequestParams`](#inappeventrequestparams)
- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)

## `trackInAppOpen`

Tracks an `inAppOpen` event by calling [`POST /api/events/trackInAppOpen`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappopen).

```ts
const trackInAppOpen = (
  payload: Omit<
    InAppEventRequestParams,
    'clickedUrl' | 'inboxSessionId' | 'closeAction'
  >
): IterablePromise<IterableResponse>
```

Example:

```ts
import { trackInAppOpen } from '@iterable/web-sdk';

trackInAppOpen({
  messageId: '123',
  deviceInfo: { appPackageName: 'my-website' }
})
  .then()
  .catch();
```

See also:

- [`InAppEventRequestParams`](#inappeventrequestparams)
- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)

## `trackPurchase`

Tracks a `purchase` event by calling [`POST /api/commerce/trackPurchase`](https://support.iterable.com/hc/articles/204780579#post-api-commerce-trackpurchase).

```ts
const trackPurchase = (payload: TrackPurchaseRequestParams): IterablePromise<IterableResponse>
```

Example:

```ts
import { trackPurchase } from '@iterable/web-sdk';

trackPurchase({
  items: [{ id: '123', name: 'keyboard', price: 100, quantity: 2 }],
  total: 200
})
  .then()
  .catch();
```

See also:

- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)
- [`TrackPurchaseRequestParams`](#trackpurchaserequestparams)

## `updateCart`

Updates the shopping cart items on the user's Iterable profile by calling [`POST /api/commerce/updateCart`](https://support.iterable.com/hc/articles/204780579#post-api-commerce-updatecart).

```ts
const updateCart = (payload: UpdateCartRequestParams): IterablePromise<IterableResponse>
```

Example:

```ts
import { updateCart } from '@iterable/web-sdk';

updateCart({
  items: [{ id: '123', price: 100, name: 'keyboard', quantity: 1 }]
})
  .then()
  .catch();
```

See also:

- [`UpdateCartRequestParams`](#updatecartrequestparams)
- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)

## `updateSubscriptions`

Updates the user's subscriptions by calling [`POST /api/users/updateSubscriptions`](https://support.iterable.com/hc/articles/204780579#post-api-users-updatesubscriptions).

```ts
const updateSubscriptions = (
  payload: Partial<UpdateSubscriptionParams> = {}
): IterablePromise<IterableResponse>
```

Example:

```ts
import { updateSubscriptions } from '@iterable/web-sdk';

updateSubscriptions({ emailListIds: [1, 2, 3] })
  .then()
  .catch();
```

See also:

- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)
- [`UpdateSubscriptionParams`](#updatesubscriptionparams)

## `updateUser`

Updates the data on a user's Iterable profile by calling [`POST /api/users/updateUser`](https://support.iterable.com/hc/articles/204780579#post-api-users-update).

```ts
const updateUser = (payload: UpdateUserParams = {}): IterablePromise<IterableResponse>
```

Example:

```ts
import { updateUser } from '@iterable/web-sdk';

updateUser({ dataFields: {} }).then().catch();
```

See also:

- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)
- [`UpdateUserParams`](#updateuserparams)

## `updateUserEmail`
## `setVisitorUsageTracked`

Enables or disables unknown visitor tracking based on user consent (UUA). Returned by `initialize` and `initializeWithConfig`.

```ts
setVisitorUsageTracked: (consent: boolean) => void
```

- `true`: begin or continue collecting unknown events (and start/restore unknown session if enabled)
- `false`: stop collecting and clear unknown user data

## `clearVisitorEventsAndUserData`

Clears unknown visitor session data and queued events (UUA). Returned by `initialize` and `initializeWithConfig`.

```ts
clearVisitorEventsAndUserData: () => void
```

Updates the current user's `email` by calling [`POST /api/users/updateEmail`](https://support.iterable.com/hc/articles/204780579#post-api-users-updateemail).
Causes the SDK to fetch a JWT for the new email address.

```ts
updateUserEmail: (newEmail: string): IterablePromise<IterableResponse>
```

Example:

```ts
import { updateUserEmail } from '@iterable/web-sdk';

updateUserEmail('user@example.com').then().catch();
```

See also:

- [`IterablePromise`](#iterablepromise)
- [`IterableResponse`](#iterableresponse)

# Classes, interfaces, types, and enums

This section describes classes, interfaces, and enums to be aware of when working 
with Embedded Messaging in Iterable's Web SDK.

| Type                                                                              | Description |
| --------------------------------------------------------------------------------- | ----------- |
| [`CloseButton`](#closebutton)                                                     | Specifies how the SDK should display a close button on the associated in-app message. Passed as part of [`InAppMessagesRequestParams`](#inappmessagesrequestparams). |
| [`CloseButtonPosition`](#closebuttonposition)                                     | Specifies the position of the close button on the associated in-app message. |
| [`CommerceItem`](#commerceitem)                                                   | An item being purchased or added to a shopping cart. Include when calling [`trackPurchase`](#trackpurchase) or [`updateCart`](#updatecart). |
| [`CommerceUser`](#commerceuser)                                                   | Information about the user associated with a purchase or cart update. Include when calling [`trackPurchase`](#trackpurchase) or [`updateCart`](#updatecart). |
| [`DisplayOptions`](#displayoptions)                                               | Display options to pass to [`getInAppMessages`](#getinappmessages) to indicate whether messages should be displayed immediately or later. |
| [`DisplayPosition`](#displayposition)                                             | Describes where an in-app message should be displayed. Part of [`WebInAppDisplaySettings`](#webinappdisplaysettings). |
| [`Elements`](#elements)                                                           | Custom styles to apply to `IterableEmbeddedCard`, `IterableEmbeddedBanner`, and `IterableEmbeddedNotification` views for embedded messages. |
| [`GenerateJWTPayload`](#generatejwtpayload)                                       | The payload to pass to the `generateJWT` function when calling [`initialize`](#initialize) or [`initializeWithConfig`](#initializewithconfig). |
| [`ErrorHandler`](#errorhandler)                                                   | An error-handling function. Passed as a parameter to [`IterableEmbeddedCard`](#iterableembeddedcard), [`IterableEmbeddedBanner`](#iterableembeddedbanner), and [`IterableEmbeddedNotification`](#iterableembeddednotification), which use the method to handle errors when tracking `embeddedClick` events. |
| [`GetInAppMessagesResponse`](#getinappmessagesresponse)                           | Return value for [`getInAppMessages`](#getinappmessages), when it's called without the `options` parameter. |
| [`HandleLinks`](#handlelinks)                                                     | Describes where in-app links should be opened. Part of [`InAppMessagesRequestParams`](#inappmessagesrequestparams). |
| [`InAppMessage`](#inappmessage)                                                   | A single in-app message. |
| [`InAppDisplaySetting`](#inappdisplaysetting)                                     | Display settings for an in-app message, including padding percentages. |
| [`InAppEventRequestParams`](#inappeventrequestparams)                             | Data to pass to [`trackInAppClick`](#trackinappclick), [`trackInAppClose`](#trackinappclose), [`trackInAppConsume`](#trackinappconsume), [`trackInAppDelivery`](#trackinappdelivery), and [`trackInAppOpen`](#trackinappopen). |
| [`InAppMessagesRequestParams`](#inappmessagesrqeuestparams)                       | Data to pass to [`getInAppMessages`](#getinappmessages). |
| [`InAppMessageResponse`](#inappmessageresponse)                                   | Return value for [`getInAppMessages`](#getinappmessages), when it's called with the `options` parameter. |
| [`InAppTrackRequestParams`](#inapptrackrequestparams)                             | Data to pass to [`track`](#track). |
| [`IterableAction`](#iterableaction)                                               | An action associated with a click. The type of the action, and its associated URL. |
| [`IterableActionContext`](#iterableactioncontext)                                 | Information about the context of an `IterableAction`. For example, the associated message type. Only used with embedded messages. |
| [`IterableActionSource`](#iterableactionsource)                                   | An enum of possible message types to which an `IterableAction` can be associated. Currently, only `EMBEDDED` is supported. |
| [`IterableConfig`](#iterableconfig)                                               | A class that can hold configuration information for the SDK. Currently, only `urlHandler` and `customActionHandler` are supported (static properties), and these are only invoked for URLs and custom actions coming from embedded messages. |
| [`IterableCustomActionHandler`](#iterablecustomactionhandler)                     | An interface that defines `handleIterableCustomAction`, which the SDK can call to handle custom action URLs (`action://`) URLs that result from from clicks on embedded messages. |
| [`IterableEmbeddedButton`](#iterableembeddedbutton)                               | Payload for a button associated with an embedded message. |  
| [`IterableEmbeddedButtonAction`](#iterableembeddedbuttonaction)                   | Payload for the action associated with an embedded message button. |
| [`IterableEmbeddedClickRequestPayload`](#iterableembeddedclickrequestpayload)     | Data to pass to [`trackEmbeddedClick`](#trackembeddedclick). | 
| [`IterableEmbeddedDefaultAction`](#iterableembeddeddefaultaction)                 | The default action associated with an embedded message. Invoked when a user clicks on an embedded message, but outside of its buttons. | 
| [`IterableEmbeddedElements`](#iterableembeddedelements)                           | Content associated with an embedded message — title, body, media URL, buttons, default action, and extra text fields. |
| [`IterableEmbeddedImpression`](#iterableembeddedimpression)                       | The number of times a given embedded message appeared during a specific session, and the total duration of all those appearances. Also includes other metadata about the impression. |
| [`IterableEmbeddedManager`](#iterableembeddedmanager)                             | Used to fetch embedded messages from Iterable, and pass them to application code as necessary. |
| [`IterableEmbeddedMessage`](#iterableembeddedmessage)                             | A single embedded message to display, including title text, body text, buttons, an image URL, click actions, text fields, and JSON data. |
| [`IterableEmbeddedMessageUpdateHandler`](#iterableembeddedmessageupdatehandler)   | An object that defines `onMessagesUpdated` and `onEmbeddedMessagingDisabled` methods. If this object is registered as an update listener for embedded messages (you can do this by calling `addUpdateListener` on [`IterableEmbeddedManager`](#iterableembeddedmanager)), the SDK calls these methods as necessary after fetching embedded messages from the server. |
| [`IterableEmbeddedMetadata`](#iterableembeddedmetadata)                           | Identifying information about an embedded message. |
| [`IterableEmbeddedSession`](#iterableembeddedsession)                             | Represents a period of time during which a user was on a page where they could potentially view embedded messages. Contains an ID, a start time, and an end time. |
| [`IterableEmbeddedSessionManager`](#iterableembeddedsessionmanager)               | Used to track sessions and impressions, and to save them back to Iterable. |
| [`IterableEmbeddedSessionRequestPayload`](#iterableembeddedsessionrequestpayload) | Data to pass to [`trackEmbeddedSession`](#trackembeddedsession). You won't usually interact manually with this interface, since the [`IterableEmbeddedSessionManager`](#iterableembeddedsessionmanager) handles the tracking of sessions and impressions for you. |
| [`IterableEmbeddedText`](#iterableembeddedtext)                                   | Extra text fields sent along with an embedded message. Like custom JSON, these text fields can be used to pass data as part of an embedded message. |
| [`IterableErrorStatus`](#iterableerrorstatus)                                     | Errors that can come back with an [`IterableResponse`](#iterableresponse). |
| [`IterablePromise`](#iterablepromise)                                             | A promise. |
| [`IterableResponse`](#iterableresponse)                                           | A response from Iterable's API. |
| [`IterableUrlHandler`](#iterableurlhandler)                                       | An interface that defines `handleIterableURL`, which the SDK can call to handle standard URLs (`https://`, `custom://`, but not `action://`) that result from from clicks on embedded messages. |
| [`OOTB`](#ootb)                                                                   | A type that defines the parameters to provide when calling `IterableEmbeddedCard`, `IterableEmbeddedBanner`, and `IterableEmbeddedNotification`. |
| [`Options`](#options)                                                             | Configuration options to pass to [`initializeWithConfig`](#initializewithconfig). |
| [`OutOfTheBoxButton`](#outoftheboxbutton)                                         | Custom styles to apply to buttons in an embedded message. The same as `OutOfTheBoxElement`, but with an extra `disabledStyles` string. |
| [`OutOfTheBoxElement`](#outoftheboxelement)                                       | The custom styles to apply to a single element of an embedded message. |
| [`SDKInAppMessagesParams`](#sdkinappmessagesparams)                               | Parent interface for [`InAppMessagesRequestParams`](#inappmessagesrequestparams). |
| [`TrackPurchaseRequestParams`](#trackpurchaserequestparams)                       | Parameters to pass to [`trackPurchase`](#trackpurchase). |
| [`UpdateCartRequestParams`](#updatecartrequestparams)                             | Data to pass to [`updateCart`](#updatecart). |
| [`UpdateSubscriptionParams`](#updatesubscriptionparams)                           | Data to pass to [`updateSubscriptions`](#updatesubscriptions). |
| [`UpdateUserParams`](#updateuserparams)                                           | Data to pass to [`updateUser`](#updateuser). |
| [`WebInAppDisplaySettings`](#webinappdisplaysettings)                             | An object that contains information about how to display the associated in-app message. |
| [`WithJWT`](#withjwt)                                                             | Return value from [`initialize`](#initialize) and [`initializeWithConfig`](#initializeWithConfig). |
| [`WithJWTParams`](#withjwtparams)                                                 | Parameters to pass to [`initializeWithConfig`](#initializewithconfig). |

## `CloseButton`

Specifies how the SDK should display a close button on the associated in-app message. 
Passed as part of [`InAppMessagesRequestParams`](#inappmessagesrequestparams).

```ts
type CloseButton = {
    color?: string;
    iconPath?: string;
    // If true, prevent user from dismissing in-app message by clicking outside 
    // of message
    isRequiredToDismissMessage?: boolean;
    position?: CloseButtonPosition;
    sideOffset?: string;
    size?: string | number;
    topOffset?: string;
};
```

See also:

- [`CloseButtonPosition`](#closebuttonposition)

## `CloseButtonPosition`

Specifies the position of the close button on the associated in-app message.

```ts
declare enum CloseButtonPosition {
    TopLeft = "top-left",
    TopRight = "top-right"
}
```

## `CommerceItem`

An item being purchased or added to a shopping cart. Include when calling 
[`trackPurchase`](#trackpurchase) or [`updateCart`](#updatecart).

```ts
interface CommerceItem {
  id: string;
  sku?: string;
  name: string;
  description?: string;
  categories?: string[];
  price: number;
  quantity: number;
  imageUrl?: string;
  url?: string;
  dataFields?: Record<string, any>;
}
```

## `CommerceUser`

Information about the user associated with a purchase or cart update. Include
when calling [`trackPurchase`](#trackpurchase) or [`updateCart`](#updatecart).

```ts
interface CommerceUser {
  dataFields?: Record<string, any>;
  preferUserId?: boolean;
  mergeNestedObjects?: boolean;
}
```

## `DisplayOptions`

Display options to pass to [`getInAppMessages`](#getinappmessages) to indicate
whether messages should be displayed immediately or later.

```ts
declare enum DisplayOptions {
    Immediate = "immediate",
    Deferred = "deferred"
}
```

## `DisplayPosition`

Describes where an in-app message should be displayed. Part of [`WebInAppDisplaySettings`](#webinappdisplaysettings).

```ts
declare enum DisplayPosition {
    Center = "Center",
    TopRight = "TopRight",
    BottomRight = "BottomRight",
    Full = "Full"
}
```

See also:

- [`WebInAppDisplaySettings`](#webinappdisplaysettings)

## `Elements`

Custom styles to apply to `IterableEmbeddedCard`, `IterableEmbeddedBanner`, and
`IterableEmbeddedNotification` views for embedded messages.

```ts
type Elements = {
  // img div
  img?: OutOfTheBoxElement;
  // title div
  title?: OutOfTheBoxElement;
  // primary button div
  primaryButton?: OutOfTheBoxButton;
  // secondary button div
  secondaryButton?: OutOfTheBoxButton;
  // body button div
  body?: OutOfTheBoxElement;
  // root OOTB div
  parent?: OutOfTheBoxElement;
  // button wrapper div
  buttonsDiv?: OutOfTheBoxElement;
  // title and parent wrapper div
  textTitle?: OutOfTheBoxElement;
  // textTitleImg div
  textTitleImg?: OutOfTheBoxElement;
};
```

See also:

- [`OutOfTheBoxElement`](#outoftheboxelement)
- [`OutOfTheBoxButton`](#outoftheboxbutton)

## `GenerateJWTPayload`

The payload to pass to the `generateJWT` function when calling [`initialize`](#initialize) 
or [`initializeWithConfig`](#initializewithconfig).

```ts
interface GenerateJWTPayload {
  email?: string;
  userID?: string;
}
```

## `ErrorHandler`

An error-handling function. Passed as a parameter to [`IterableEmbeddedCard`](#iterableembeddedcard), 
[`IterableEmbeddedBanner`](#iterableembeddedbanner), and [`IterableEmbeddedNotification`](#iterableembeddednotification), 
which use the method to handle errors when tracking `embeddedClick` events.

```ts
interface ErrorHandler {
  (error: any): void;
}
```

## `GetInAppMessagesResponse`

Return value for [`getInAppMessages`](#getinappmessages), when it's called without 
the `options` parameter.

```ts
interface GetInAppMessagesResponse {
  pauseMessageStream: () => void;
  resumeMessageStream: () => Promise<HTMLIFrameElement | ''>;
  request: () => IterablePromise<InAppMessageResponse>;
  triggerDisplayMessages: (
    messages: Partial<InAppMessage>[]
  ) => Promise<HTMLIFrameElement | ''>;
}
```

## `HandleLinks`

Describes where in-app links should be opened. Part of [`InAppMessagesRequestParams`](#inappmessagesrequestparams).

```ts
declare enum HandleLinks {
    OpenAllNewTab = "open-all-new-tab",
    OpenAllSameTab = "open-all-same-tab",
    ExternalNewTab = "external-new-tab"
}
```

## `InAppMessage`

A single in-app message.

```ts
interface InAppMessage {
  messageId: string;
  campaignId: number;
  createdAt: number;
  expiresAt: number;
  content: {
    payload?: Record<string, any>;
    html: string | HTMLIFrameElement;
    inAppDisplaySettings: {
      top: InAppDisplaySetting;
      right: InAppDisplaySetting;
      left: InAppDisplaySetting;
      bottom: InAppDisplaySetting;
      bgColor?: {
        alpha: number;
        hex: string;
      };
      shouldAnimate?: boolean;
    };
    webInAppDisplaySettings: WebInAppDisplaySettings;
  };
  customPayload: Record<string, any>;
  trigger: {
    type: string;
  };
  saveToInbox: boolean;
  inboxMetadata: {
    title: string;
    subtitle: string;
    icon: string;
  };
  priorityLevel: number;
  read: boolean;
}
```

See also:

- [`InAppDisplaySetting`](#inappdisplaysetting)
- [`WebInAppDisplaySettings`](#webinappdisplaysettings)

## `InAppDisplaySetting`

Display settings for an in-app message, including padding percentages.

```ts
interface InAppDisplaySetting {
  percentage?: number;
  displayOption?: string;
}
```

## `InAppEventRequestParams`

Data to pass to [`trackInAppClick`](#trackinappclick), [`trackInAppClose`](#trackinappclose),
[`trackInAppConsume`](#trackinappconsume), [`trackInAppDelivery`](#trackinappdelivery), and
[`trackInAppOpen`](#trackinappopen).

```ts
interface InAppEventRequestParams {
  messageId: string;
  clickedUrl?: string;
  messageContext?: {
    saveToInbox?: boolean;
    silentInbox?: boolean;
    location?: string;
  };
  closeAction?: string;
  deviceInfo: {
    appPackageName: string; 
  };
  inboxSessionId?: string;
  createdAt?: number;
}
```

## `InAppMessagesRequestParams`

Data to pass to [`getInAppMessages`](#getinappmessages).

```ts
interface InAppMessagesRequestParams extends SDKInAppMessagesParams {
    count: number;
    SDKVersion?: string;
    packageName: string;
}
```

See also:

- [`SDKInAppMessagesParams`](#sdkinappmessagesparams)

## `InAppMessageResponse`

Return value for [`getInAppMessages`](#getinappmessages), when it's called with
the `options` parameter.

```ts
interface InAppMessageResponse {
  inAppMessages: Partial<InAppMessage>[];
}
```

See also:

- [`InAppMessage`](#inappmessage)

## `InAppTrackRequestParams`

Data to pass to [`track`](#track).

```ts
interface InAppTrackRequestParams {
  eventName: string;
  id?: string;
  createdAt?: number;
  dataFields?: Record<string, any>;
  campaignId?: number;
  templateId?: number;
}
```

## `IterableAction`

An action associated with a click. The type of the action, and its associated
URL. Only used with embedded messages.

```ts
interface IterableAction {
  type: string;
  data: string;
}
```

The values for `type` and `data` depend on the type of action assigned to the
campaign in Iterable:

- For **Open URL** actions, `type` is `openUrl` and `data` contains the URL.
- For **Custom action** actions, `type` is the URL, and `data` is empty.

## `IterableActionContext`

Information about the context of an `IterableAction`. For example, the
associated message type. Only used with embedded messages.

```ts
interface IterableActionContext {
  action: IterableAction;
  source: IterableActionSource;
}
```

See also:

- [`IterableAction`](#iterableaction)
- [`IterableActionSource`](#iterableactionsource)

## `IterableActionSource`

An enum of possible message types to which an `IterableAction` can be associated. 
Currently, only `EMBEDDED` is supported.

```ts
enum IterableActionSource {
  EMBEDDED = 'EMBEDDED'
}
```

## `IterableConfig`

A class that can hold configuration information for the SDK. Currently, only
`urlHandler` and `customActionHandler` are supported (static properties), and
these are only invoked for URLs and custom actions coming from embedded messages.

```ts
class IterableConfig {
  public static urlHandler: IterableUrlHandler | null = null;
  public static customActionHandler: IterableCustomActionHandler | null = null;
}
```

See also:

- [`IterableUrlHandler`](#iterableurlhandler)
- [`IterableCustomActionHandler`](#iterablecustomactionhandler)

## `IterableCustomActionHandler`

An interface that defines `handleIterableCustomAction`, which the SDK can call to 
handle custom action URLs (`action://`) URLs that result from from clicks on 
embedded messages.

```ts
interface IterableCustomActionHandler {
  handleIterableCustomAction(
    action: IterableAction,
    actionContext: IterableActionContext
  ): boolean;
}
```

See also:

- [`IterableAction`](#iterableaction)
- [`IterableActionContext`](#iterableactioncontext)

## `IterableEmbeddedButton`

Payload for a button associated with an embedded message. 

```ts
interface IterableEmbeddedButton {
  id: string;
  title?: string;
  action?: IterableEmbeddedButtonAction;
}
```

See also:

- [`IterableEmbeddedButtonAction`](#iterableembeddedbuttonaction)

## `IterableEmbeddedButtonAction`

Payload for the action associated with an embedded message button.

```ts
interface IterableEmbeddedButtonAction {
  type: string;
  data?: string;
}
```

The values for `type` and `data` depend on the type of action assigned to the
campaign in Iterable:

- For **Open URL** actions, `type` is `openUrl` and `data` contains the URL.
- For **Custom action** actions, `type` is the URL, and `data` is empty.

## `IterableEmbeddedClickRequestPayload`

Data to pass to [`trackEmbeddedClick`](#trackembeddedclick).

```ts
interface IterableEmbeddedClickRequestPayload {
  messageId: string;
  buttonIdentifier: string;
  targetUrl: string;
  appPackageName: string;
}
```

## `IterableEmbeddedDefaultAction`

The default action associated with an embedded message. Invoked when a user
clicks on an embedded message, but outside of its buttons.

```ts
interface IterableEmbeddedDefaultAction {
  type: string;
  data?: string;
}
```

The values for `type` and `data` depend on the type of action assigned to the
campaign in Iterable:

- For **Open URL** actions, `type` is `openUrl` and `data` contains the URL.
- For **Custom action** actions, `type` is the URL, and `data` is empty.

## `IterableEmbeddedElements`

Content associated with an embedded message — title, body, media URL,
buttons, default action, and extra text fields.

```ts
interface IterableEmbeddedElements {
  title?: string;
  body?: string;
  mediaUrl?: string;
  buttons?: IterableEmbeddedButton[];
  text?: IterableEmbeddedText[];
  defaultAction?: IterableEmbeddedDefaultAction;
}
```

See also:

- [`