{"id":21569894,"url":"https://github.com/iterable/iterable-web-sdk","last_synced_at":"2025-04-10T14:11:59.799Z","repository":{"id":38184238,"uuid":"207411751","full_name":"Iterable/iterable-web-sdk","owner":"Iterable","description":"Iterable SDK for interacting with the Iterable API to implement inside JavaScript and Node projects","archived":false,"fork":false,"pushed_at":"2024-05-22T16:33:59.000Z","size":2974,"stargazers_count":9,"open_issues_count":14,"forks_count":8,"subscribers_count":16,"default_branch":"main","last_synced_at":"2024-05-22T17:18:34.777Z","etag":null,"topics":["axios","javascript","sdk","typescript"],"latest_commit_sha":null,"homepage":"https://iterable.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Iterable.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-09T21:53:34.000Z","updated_at":"2024-05-28T15:52:04.768Z","dependencies_parsed_at":"2023-11-07T00:16:55.242Z","dependency_job_id":"36851dbb-2c5e-485e-bd7c-8ac02e710afd","html_url":"https://github.com/Iterable/iterable-web-sdk","commit_stats":{"total_commits":182,"total_committers":12,"mean_commits":"15.166666666666666","dds":0.5604395604395604,"last_synced_commit":"a3397f52629a2a3627a9b5a32f7598d231fb2e1e"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iterable%2Fiterable-web-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iterable%2Fiterable-web-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iterable%2Fiterable-web-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Iterable%2Fiterable-web-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Iterable","download_url":"https://codeload.github.com/Iterable/iterable-web-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248232516,"owners_count":21069487,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["axios","javascript","sdk","typescript"],"created_at":"2024-11-24T11:10:59.567Z","updated_at":"2025-04-10T14:11:59.763Z","avatar_url":"https://github.com/Iterable.png","language":"TypeScript","readme":"![Iterable-Logo](https://user-images.githubusercontent.com/7387001/129065810-44b39e27-e319-408c-b87c-4d6b37e1f3b2.png)\n\n# Iterable's Web SDK\n\n[Iterable](https://www.iterable.com) is a growth-marketing platform that helps\nyou to create better experiences for—and deeper relationships with—your customers. \nUse it to send customized email, SMS, push notification, in-app message,\nembedded message, and web push notification campaigns to your customers.\n\nThis SDK helps you integrate your web apps with Iterable.\n\n# Table of contents\n\n- [Other documentation](#other-documentation)\n- [Installation](#installation)\n- [Functions](#functions)\n- [Classes, interfaces, types, and enums](#classes-interfaces-types-and-enums)\n- [FAQ](#faq)\n- [Link handling](#link-handling)\n- [TypeScript](#typescript)\n- [Contributing](#contributing)\n- [License](#license)\n\n# Other documentation\n\nThis document contains reference information about the Web SDK. For other\ninformation, please see:\n\n- [In-Browser Messaging Overview](https://support.iterable.com/hc/articles/4418166649748)\n- [Embedded Messaging Overview](https://support.iterable.com/hc/articles/23060529977364)\n- [Overview of Iterable's Web SDK](https://support.iterable.com/hc/articles/10359708795796)\n- [Setting up Iterable's Web SDK](https://support.iterable.com/hc/articles/4419628585364)\n- [Embedded Messages with Iterable's Web SDK](https://support.iterable.com/hc/articles/27537816889108)\n\n# Using the SDK\n\nIn general, to use the SDK, you'll need to follow these steps:\n\n1. In Iterable, [create a JWT-enabled, web API key](https://support.iterable.com/hc/articles/360043464871). \n The SDK can use this key to authenticate with Iterable's API endpoints. This\n will ensure the SDK has access to all the necessary. Save the API key and\n its associated JWT secret, since you'll need them both.\n\n2. Work with your Engineering team to create a web service the SDK can call\n to fetch a valid JWT token for the signed-in user. To learn more about how\n to do this, read [JWT-Enabled API Keys](https://support.iterable.com/hc/articles/360050801231).\n\n3. [Install](#installation) the SDK in your web app.\n\n4. Use the API key to initialize the SDK, as described in [`initialize`](#initialize) \n and [`initializeWithConfig`](#initializewithconfig). When you initialize the \n SDK, pass in a method that can call the web service (created in step 2)\n to fetch a valid JWT token for the signed-in user.\n\n5. To identify the user to the SDK, call `setEmail` or `setUserID` (returned by \n [`initialize`](#initialize) or [`initializeWithConfig`](#initializewithconfig)). \n The SDK uses the user's `email` or `userId` to fetch a valid JWT token from \n your server. \n\n6. After the SDK successfully sets the user's `email` or `userId` and the SDK\n fetches a JWT token, you can make API requests to Iterable. For example, you\n can call [`track`](#track) to track events, or [`getInAppMessages`](#getinappmessages) \n to fetch in-app messages, etc. Other methods are described [below](#functions).\n\n# Installation\n\nTo install the SDK, use Yarn, npm, or a `script` tag:\n\n- npm\n\n ```\n npm install @iterable/web-sdk\n ```\n\n- Yarn\n\n ```\n yarn add @iterable/web-sdk\n ```\n\n- `script` tag\n\n ```js\n \u003cscript src=\"https://unpkg.com/@iterable/web-sdk/index.js\"\u003e\u003c/script\u003e\n ```\n\n# Functions\n\nIterable's Web SDK exposes the following functions, which you can use in your\nwebsite code.\n\nFor information about the data the SDK sends and receives when making calls to\nIterable's API, see the [API Overview](https://support.iterable.com/hc/articles/204780579).\n\n| Method Name | Description |\n| --------------------------------------------------------------------------------- | ----------- |\n| [`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. |\n| [`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. |\n| [`getInAppMessages`](#getInAppMessages) | Fetches in-app messages by calling [`GET /api/inApp/getMessages`](https://support.iterable.com/hc/articles/204780579#get-api-inapp-getmessages). |\n| [`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)). |\n| [`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)). |\n| [`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. |\n| [`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. |\n| [`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. |\n| [`sortInAppMessages`](#sortinappmessages) | Sorts an array of in-app messages by priority, and then creation date. |\n| [`track`](#track) | Tracks a custom event by calling [`POST /api/events/track`](https://support.iterable.com/hc/articles/204780579#post-api-events-track). |\n| [`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). |\n| [`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). |\n| [`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). | |\n| [`trackInAppClick`](#trackInAppClick) | Tracks an `inAppClick` event by calling [`POST /api/events/trackInAppClick`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappclick). |\n| [`trackInAppClose`](#trackInAppClose) | Tracks an `inAppClose` event by calling [`POST /api/events/trackInAppClose`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappclose). |\n| [`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). |\n| [`trackInAppDelivery`](#trackInAppDelivery) | Tracks an `inAppDelivery` event by calling [`POST /api/events/trackInAppDelivery`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappdelivery). |\n| [`trackInAppOpen`](#trackInAppOpen) | Tracks an `inAppOpen` event by calling [`POST /api/events/trackInAppOpen`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappopen). |\n| [`trackPurchase`](#trackPurchase) | Tracks a `purchase` event by calling [`POST /api/commerce/trackPurchase`](https://support.iterable.com/hc/articles/204780579#post-api-commerce-trackpurchase). |\n| [`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). |\n| [`updateSubscriptions`](#updateSubscriptions) | Updates the user's subscriptions by calling [`POST /api/users/updateSubscriptions`](https://support.iterable.com/hc/articles/204780579#post-api-users-updatesubscriptions). |\n| [`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). |\n| [`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. |\n\nNotes:\n\n- The SDK does not track `inAppDelete` events.\n\n- :rotating_light: Due to a limitation in WebKit (which affects iOS web browsers,\n like Safari), in-app messages displayed in an iOS web browser browser can't \n automatically track `inAppClick` events or handle custom CTAs. This will impact\n analytics for all Safari and mobile iOS users.\n\n## `filterHiddenInAppMessages`\n\nFrom an array of passed-in in-app messages, filters out messages that have\nalready been read, messages that should not be displayed, and messages that only\ncontain JSON data.\n\n```ts\nconst filterHiddenInAppMessages = (\n messages: Partial\u003cInAppMessage\u003e[] = []\n): Partial\u003cInAppMessage\u003e[]\n```\n\nSee also:\n\n- [`InAppMessage`](#inappmessage)\n\n## `filterOnlyReadAndNeverTriggerMessages`\n\nFrom an array of passed-in in-app messages, filters out messages that have\nalready been read and messages that should not be displayed.\n\n```ts\nconst filterOnlyReadAndNeverTriggerMessages = (\n messages: Partial\u003cInAppMessage\u003e[] = []\n): Partial\u003cInAppMessage\u003e[]\n```\n\nSee also:\n\n- [`InAppMessage`](#inappmessage)\n\n## `getInAppMessages`\n\nFetches in-app messages by calling [`GET /api/inApp/getMessages`](https://support.iterable.com/hc/articles/204780579#get-api-inapp-getmessages).\n\n```ts\n// Returns a promise that resolves to an InAppMessageResponse, which has an\n// array of fetched in-app messages.\nfunction getInAppMessages(\n payload: InAppMessagesRequestParams\n): IterablePromise\u003cInAppMessageResponse\u003e;\n\n// Returns methods to request messages from the server, pause message display, \n// restart message display, and trigger the display of a message.\nfunction getInAppMessages(\n payload: InAppMessagesRequestParams,\n options: {\n display: DisplayOptions;\n }\n): GetInAppMessagesResponse\n\n```\n\n`payload` options (see [`InAppMessagesRequestParams`](#inappmessagesrequestparams)):\n\n| Property Name | Description | Value | Default |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | ----------- |\n| `animationDuration` | How long (in ms) it should take messages to animate in and out | `number` | `400` |\n| `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` |\n| `closeButton` | Properties that define a custom close button to display on a message. | `CloseButtonOptions` (see below) | `undefined` |\n| `displayInterval` | How long (in ms) to wait before showing the next in-app message after closing the currently open one | `number` | `30000` |\n| `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` |\n| `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` |\n| `onOpenScreenReaderMessage` | The text a screen reader should read when opening the message. | `string` | `undefined` |\n| `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` |\n| `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` |\n\n`closeButton` options (see [`CloseButton`](#closebutton)):\n\n| Property Name | Description | Value | Default |\n| --------------------------- | ---------------------------------------------------------------------------- | -------------------------- | ------------- |\n| `color` | The button's color (does not affect custom icons) | `string` | `undefined` |\n| `iconPath` | Custom pathname to an image or SVG to use (instead of the default \"X\") | `string` | `undefined` |\n| `isRequiredToDismissMessage`| If `true`, users cannot dismiss in-app messages by clicking outside of them. | `boolean` | `undefined` |\n| `position` | Where the button should display on an in-app message | `'top-right' \\| 'top-left'`| `'top-right'` |\n| `sideOffset` | How much space to leave between the button and side of the container | `string` | `'4%'` |\n| `size` | How large to set the width, height, and font-size | `string \\| number` | `24` |\n| `topOffset` | How much space to leave between the button and the top of the container | `string` | `'4%'` |\n\nExample:\n\n```ts\nimport { getInAppMessages } from '@iterable/web-sdk';\n\ngetInAppMessages({ count: 20, packageName: 'mySite1' })\n .then((resp) =\u003e {\n // This is an iframe element that can be attached to the DOM \n const messageIframe = resp.data.inAppMessages[0].content.html;\n document.body.appendChild(messageIframe);\n // Additional styling logic can be done here to render the message in a \n // custom way\n })\n .catch();\n```\n\nThis code, which doesn't include the `options` parameter, fetches in-app messages\nfrom Iterable and places the first one on the page. However, it won't be visible.\nTo render it, modify the page's CSS to display the message as necessary. You'll\nalso need to set up click handlers to handle click events, close the message,\netc.\n\nHere's some example code that shows messages automatically:\n\n```ts\nimport { getInAppMessages } from '@iterable/web-sdk';\n\nconst { request, pauseMessageStream, resumeMessageStream } = getInAppMessages(\n {\n count: 20,\n packageName: 'my-website',\n displayInterval: 5000,\n onOpenScreenReaderMessage:\n 'The screen reader will read this',\n onOpenNodeToTakeFocus: 'input',\n closeButton: {\n color: 'red',\n size: '16px',\n topOffset: '20px'\n }\n },\n { display: 'immediate' }\n);\n\nrequest().then().catch();\n```\n\nThis example uses custom sorting and filtering, and displays messages at the\napp's discretion:\n\n```ts\nimport {\n getInAppMessages,\n sortInAppMessages,\n filterHiddenInAppMessages\n} from '@iterable/web-sdk';\n\nconst {\n request,\n pauseMessageStream,\n resumeMessageStream,\n triggerDisplayMessages\n} = getInAppMessages(\n {\n count: 20,\n packageName: 'my-website',\n displayInterval: 5000,\n onOpenScreenReaderMessage: 'The screen reader will read this',\n onOpenNodeToTakeFocus: 'input',\n closeButton: {\n color: 'red',\n size: '16px',\n topOffset: '20px'\n }\n },\n { display: 'deferred' }\n);\n\nrequest()\n .then((response) =\u003e {\n // Do your own manipulation here \n const filteredMessages = yourOwnSortingAndFiltering(response.data.inAppMessages);\n\n // Or, feel free to take advantage of the sorting/filtering methods used \n // internally\n const furtherManipulatedMessages = sortInAppMessages(\n filterHiddenInAppMessages(response.data.inAppMessages)\n ) as InAppMessage[];\n\n // Then display them whenever you want\n triggerDisplayMessages(furtherManipulatedMessages);\n })\n .catch();\n```\n\n:rotating_light: With the `deferred` option, the SDK does **not** filter or sort\nthe messages. The messages come back exactly as retrieved from the API, without\nmodification. This means that you may (for example) show in-app messages marked as\n`read`, or show messages in the default order (based on `priority`), rather\nthan a custom order that you control.\n\nIn this case, to apply the SDK's default sorting and filtering, use the \n[`sortInAppMessages`](#sortinappmessages) and [`filterHiddenInAppMessages`](#filterhiddeninappmessages) \nmethods. Also, see [`filterOnlyReadAndNeverTriggerMessages`](#filteronlyreadandnevertriggermessages), \nwhich is similar to `filterHiddenInAppMessages` but does not filter out \nJSON-only messages.\n\nNotes:\n\n- :rotating_light: [v1.0.0](https://github.com/Iterable/iterable-web-sdk/releases/tag/v1.0.0) \n of this SDK removes support for `showMessagesAutomatically?: boolean`. If needed, \n please update your `getInAppMessages` requests to use `options: { display: 'deferred' | 'immediate' }`.\n\nSee also: \n\n- [`DisplayOptions`](#displayoptions)\n- [`GetInAppMessagesResponse`](#getinappmessagesresponse)\n- [`InAppMessagesRequestParams`](#inappmessagesrequestparams)\n- [`InAppMessageResponse`](#inappmessageresponse)\n- [`IterablePromise`](#iterablepromise)\n\n## `initialize`\n\nInitializes the SDK with an API key and a JWT refresh method. Returns methods\nyou can use to identify the current user, work with JWT tokens, and log the \nuser out (see [`WithJWT`](#withjwt)).\n\n```ts\nfunction initialize(\n authToken: string,\n generateJWT: (payload: GenerateJWTPayload) =\u003e Promise\u003cstring\u003e\n): WithJWT;\n```\n\n`generateJWT` should be a function that takes a `userId` or `email` and uses\nit to fetch, from your server, a valid JWT token for that user. The function\nshould return the token as a string.\n\nExample:\n\n```ts\nimport { initialize } from '@iterable/web-sdk';\n\nconst { clearRefresh, setEmail, setUserID, logout } = initialize(\n '\u003cYOUR_API_KEY\u003e',\n // email will be defined if you call setEmail \n // userID_ will be defined if you call setUserID\n ({ email, userID }) =\u003e\n yourAsyncJWTGeneratorMethod({ email, userID }).then(\n ({ jwt_token }) =\u003e jwt_token\n )\n);\n```\n\nSee also:\n\n- [`GenerateJWTPayload`](#generatejwtpayload) \n- [`WithJWT`](#withjwt)\n\n## `initializeWithConfig`\n\nSimilar to `initialize`, but also takes a set of configuration options as a \nparameter. Returns methods you can use to identify the current user, work with\nJWT tokens, and log the user out (see [`WithJWT`](#withjwt)).\n\nThe configuration options you can pass to this function are useful if you\nneed to [point the SDK to Iterable's EU API endpoints](#iterables-european-data-center-eudc) \nor [allow JavaScript execution in Safari tabs](#safari-allowing-javascript-execution-in-tabs-opened-by-in-app-message-link-clicks).\n\n```ts\nfunction initializeWithConfig(initializeParams: WithJWTParams): WithJWT;\n```\n\nExample:\n\n```ts\nimport { initializeWithConfig } from '@iterable/web-sdk';\n\nconst { clearRefresh, setEmail, setUserID, logout } = initializeWithConfig({\n authToken: '\u003cYOUR_API_KEY\u003e',\n configOptions: {\n isEuIterableService: false,\n dangerouslyAllowJsPopups: true,\n },\n \n // email will be defined if you call setEmail\n // userID will be defined if you call setUserID\n generateJWT: ({ email, userID }) =\u003e\n yourAsyncJWTGeneratorMethod({ email, userID }).then(\n ({ jwt_token }) =\u003e jwt_token\n )\n}\n);\n```\n\n`generateJWT` should be a function that takes a `userId` or `email` and uses\nit to fetch, from your server, a valid JWT token for that user. The function\nshould return the token as a string.\n\nSee also:\n\n- [`WithJWT`](#withjwt)\n- [`WithJWTParams`](#withjwtparams)\n\n## `IterableEmbeddedCard`\n\nReturns a string of the HTML for an out-of-the-box [card](https://support.iterable.com/hc/articles/23230946708244#cards) \nview for an embedded message.\n\n```ts\nconst emptyElement = {\n id: '',\n styles: ''\n};\n\nfunction IterableEmbeddedCard({\n appPackageName,\n message,\n htmlElements = {\n parent: emptyElement,\n img: emptyElement,\n title: emptyElement,\n primaryButton: emptyElement,\n secondaryButton: emptyElement,\n body: emptyElement,\n buttonsDiv: emptyElement,\n textTitle: emptyElement\n },\n errorCallback\n}: OOTB): string\n```\n\nParameters:\n\n- `appPackageName` – The package name you use to identify your website to\n Iterable's Web SDK.\n- `message` – The `IterableEmbeddedMessage` object that represents the\n message you want to display.\n- `htmlElements` – Custom styles (type [`Elements`](#elements)) for the SDK to use \n when displaying the embedded message. For details, see [Custom Styles](https://support.iterable.com/hc/articles/27537816889108#custom-styles).\n- `errorCallback` – A callback that the SDK calls if it encounters an error\n when tracking [`embeddedClick`](https://support.iterable.com/hc/articles/23061677642260#embeddedclick-events) \n events.\n\n```js\nimport { IterableEmbeddedCard } from '@iterable/web-sdk';\n\nconst card = IterableEmbeddedCard({\n packageName,\n message,\n htmlElements,\n errorCallback: (error) =\u003e console.log('handleError: ', error)\n});\n```\n\nTo display the message, set the `innerHTML` of an HTML element to the string\nreturned by `IterableEmbeddedCard`.\n\nFor more info, see:\n\n- [Out-of-the-Box Views](https://support.iterable.com/hc/articles/27537816889108#out-of-the-box-views).\n- 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)\n in the Web SDK GitHub repository. \n- To learn how to apply custom styles, see [Custom Styles](https://support.iterable.com/hc/articles/27537816889108#custom-styles).\n\nAlso see:\n\n- [`Elements`](#elements)\n- [`OOTB`](#ootb)\n\n## `IterableEmbeddedBanner`\n\nReturns a string of the HTML for an out-of-the-box [banner](https://support.iterable.com/hc/articles/23230946708244#banners) \nview for an embedded message.\n\n```ts\nfunction IterableEmbeddedBanner({\n appPackageName,\n message,\n htmlElements = {\n parent: emptyElement,\n img: emptyElement,\n title: emptyElement,\n primaryButton: emptyElement,\n secondaryButton: emptyElement,\n body: emptyElement,\n buttonsDiv: emptyElement,\n textTitle: emptyElement,\n textTitleImg: emptyElement\n },\n errorCallback\n}: OOTB): string \n```\n\nParameters:\n\n- `appPackageName` – The package name you use to identify your website to\n Iterable's Web SDK.\n- `message` – The `IterableEmbeddedMessage` object that represents the message \n you want to display.\n- `htmlElements` – Custom styles (type [`Elements`](#elements)) for the SDK to use \n when displaying the embedded message. For details, see [Custom Styles](https://support.iterable.com/hc/articles/27537816889108#custom-styles).\n- `errorCallback` – A callback that the SDK calls if it encounters an error\n when tracking [`embeddedClick`](https://support.iterable.com/hc/articles/23061677642260#embeddedclick-events) \n events.\n\nFor example:\n\n```js\nimport { IterableEmbeddedBanner } from '@iterable/web-sdk';\n\nconst banner = IterableEmbeddedBanner({\n packageName,\n message,\n htmlElements,\n errorCallback: (error) =\u003e console.log('handleError: ', error)\n});\n```\n\nTo display the message, set the `innerHTML` of an HTML element to the string\nreturned by `IterableEmbeddedBanner`.\n\nFor more info, see:\n\n- [Creating an Out-of-the-Box View](https://support.iterable.com/hc/articles/27537816889108).\n- 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)\n in the Web SDK GitHub repository. \n- To learn how to apply custom styles, see [Custom Styles](https://support.iterable.com/hc/articles/27537816889108#custom-styles).\n\nAlso see:\n\n- [`OOTB`](#ootb)\n- [`Elements`](#elements)\n\n## `IterableEmbeddedNotification`\n\nReturns a string of the HTML for an out-of-the-box [notification](https://support.iterable.com/hc/articles/23230946708244#notifications) \nview for an embedded message.\n\n```ts\nfunction IterableEmbeddedNotification({\n appPackageName,\n message,\n htmlElements = {\n parent: emptyElement,\n title: emptyElement,\n primaryButton: emptyElement,\n secondaryButton: emptyElement,\n body: emptyElement,\n buttonsDiv: emptyElement,\n textTitle: emptyElement\n },\n errorCallback\n}: OOTB): string\n```\n\nParameters:\n\n- `appPackageName` – The package name you use to identify your website to\n Iterable's Web SDK.\n- `message` – The `IterableEmbeddedMessage` object that represents the message \n you want to display.\n- `htmlElements` – Custom styles (type [`Elements`](#elements)) for the SDK to use \n when displaying the embedded message. For details, see [Custom Styles](https://support.iterable.com/hc/articles/27537816889108#custom-styles).\n- `errorCallback` – A callback that the SDK calls if it encounters an error\n when tracking [`embeddedClick`](https://support.iterable.com/hc/articles/23061677642260#embeddedclick-events) \n events.\n\n```js\nimport { IterableEmbeddedNotification } from '@iterable/web-sdk';\n\nconst notification = IterableEmbeddedNotification({\n packageName,\n message,\n htmlElements,\n errorCallback: (error) =\u003e console.log('handleError: ', error)\n});\n```\n\nTo display the message, set the `innerHTML` of an HTML element to the string\nreturned by `IterableEmbeddedNotification`.\n\nFor more info, see:\n\n- [Creating an Out-of-the-Box View](https://support.iterable.com/hc/articles/27537816889108).\n- 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)\n- To learn how to apply custom styles, see [Custom Styles](https://support.iterable.com/hc/articles/27537816889108#custom-styles).\n\nAlso see:\n\n- [`OOTB`](#ootb)\n- [`Elements`](#elements)\n\n## `sortInAppMessages`\n\nSorts an array of in-app messages by priority, and then creation date.\n\n```ts\nconst sortInAppMessages = (messages: Partial\u003cInAppMessage\u003e[] = []) =\u003e {\n return messages.sort(by(['priorityLevel', 'asc'], ['createdAt', 'asc']));\n};\n```\n\nIn-app messages can have these [priority values](https://support.iterable.com/hc/articles/7412316462996#display-priority):\n\n- Low - `priorityLevel` of 400.5\n- Medium - `priorityLevel` of 300.5\n- High - `priorityLevel` of 200.5\n- Critical - `priorityLevel` of 100.5\n- Proof - `priorityLevel` of 100.0\n\nAlso see:\n\n- [`InAppMessage`](#inappmessage)\n\n## `track`\n\nTracks a custom event by calling [`POST /api/events/track`](https://support.iterable.com/hc/articles/204780579#post-api-events-track).\n\n```ts\ntrack: (payload: InAppTrackRequestParams): IterablePromise\u003cIterableResponse\u003e\n```\n \nExample:\n\n```ts\nimport { track } from '@iterable/web-sdk';\n\ntrack({ eventName: 'my-event' }).then().catch();\n```\n\nSee also:\n\n- [`InAppTrackRequestParams`](#inapptrackrequestparams)\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n\n## `trackEmbeddedClick`\n\nTracks an [`embeddedClick`](https://support.iterable.com/hc/articles/23061677642260#embeddedclick-events) \nevent by calling [`POST /api/embedded-messaging/events/click`](https://support.iterable.com/hc/articles/204780579#post-api-embedded-messaging-events-click).\n\n```ts\nconst trackEmbeddedClick = (\n payload: IterableEmbeddedClickRequestPayload\n): IterablePromise\u003cIterableResponse\u003e\n```\n\nExample:\n\n```js\nimport { trackEmbeddedReceived } from '@iterable/web-sdk';\n\ntrackEmbeddedClick({\n messageId: message.metadata.messageId, \n buttonIdentifier: button.id,\n clickedUrl: defaultUrl,\n appPackageName: packageName\n}).then((response) =\u003e {\n if (response.status != 200) {\n console.log(\"Failure tracking embedded click\")\n }\n}).catch((error) =\u003e {\n console.log(\"Error tracking embedded click: \", error);\n});\n```\n\nSee also:\n\n- [`IterableEmbeddedClickRequestPayload`](#iterableembeddedclickrequestpayload)\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n\n## `trackEmbeddedReceived`\n\nTracks an [`embeddedReceived`](https://support.iterable.com/hc/articles/23061677642260#embeddedreceived-events) \nevent by calling [`POST /api/embedded-messaging/events/received`](https://support.iterable.com/hc/articles/204780579#post-api-embedded-messaging-events-received).\n\nGenerally, there's no need to call this method, since the SDK automatically \ntracks an `embeddedReceived` event for each message it fetches from the server.\n\n```ts\nconst trackEmbeddedReceived = (\n messageId: string,\n appPackageName: string\n): IterablePromise\u003cIterableResponse\u003e\n```\n\nExample:\n\n```ts\nimport { trackEmbeddedReceived } from '@iterable/web-sdk';\n\ntrackEmbeddedReceived(messageId, packageName)\n .then((response: any) =\u003e {\n setTrackResponse(JSON.stringify(response.data));\n setTrackingEvent(false);\n })\n .catch((error: any) =\u003e {\n setTrackResponse(JSON.stringify(error.response.data));\n setTrackingEvent(false);\n });\n```\n\nSee also:\n\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n\n## `trackEmbeddedSession`\n\nTracks an [`embeddedSession`](https://support.iterable.com/hc/articles/23061677642260#embeddedsession-events) \nevent and related [`embeddedImpression`](https://support.iterable.com/hc/articles/23061677642260#embeddedimpression-events)\nevents by calling [`POST /api/embedded-messaging/events/session`](https://support.iterable.com/hc/articles/204780579#post-api-embedded-messaging-events-session).\n\nGenerally, rather than calling this method, you'll track sessions and impresions \nusing the SDK's [`IterableEmbeddedSessionManager`](#iterableembeddedsessionmanager).\n\n```ts\nconst trackEmbeddedSession = (\n payload: IterableEmbeddedSessionRequestPayload\n): IterablePromise\u003cIterableResponse\u003e\n```\n\nExample:\n\n```ts\nimport { trackEmbeddedSession } from '@iterable/web-sdk';\n\ntrackEmbeddedSession(sessionData)\n .then((response: any) =\u003e {\n setTrackResponse(JSON.stringify(response.data));\n setTrackingEvent(false);\n })\n .catch((error: any) =\u003e {\n setTrackResponse(JSON.stringify(error.response.data));\n setTrackingEvent(false);\n });\n```\n\nSee also:\n\n- [`IterableEmbeddedSessionRequestPayload`](#iterableembeddedsessionrequestpayload)\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n\n## `trackInAppClick`\n\nTracks an `inAppClick` event by calling [`POST /api/events/trackInAppClick`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappclick).\n\n```ts\nconst trackInAppClick = (\n payload: Omit\u003cInAppEventRequestParams, 'inboxSessionId' | 'closeAction'\u003e,\n sendBeacon = false\n): IterablePromise\u003cIterableResponse\u003e\n```\n\nExample:\n\n```ts\nimport { trackInAppClick } from '@iterable/web-sdk';\n\ntrackInAppClick({\n messageId: '123',\n deviceInfo: { appPackageName: 'my-website' }\n})\n .then()\n .catch();\n```\n\nSee also:\n\n- [`InAppEventRequestParams`](#inappeventrequestparams)\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n\n## `trackInAppClose`\n\nTracks an `inAppClose` event by calling [`POST /api/events/trackInAppClose`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappclose).\n\n```ts\nconst trackInAppClose = (payload: InAppEventRequestParams): IterablePromise\u003cIterableResponse\u003e\n```\n\nExample:\n\n```ts\nimport { trackInAppClose } from '@iterable/web-sdk';\n\ntrackInAppClose({\n messageId: '123',\n deviceInfo: { appPackageName: 'my-website' }\n})\n .then()\n .catch();\n```\n\nSee also:\n\n- [`InAppEventRequestParams`](#inappeventrequestparams)\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n\n## `trackInAppConsume`\n\nDeletes an in-app message from the server by calling [`POST /api/events/trackInAppConsume`](https://support.iterable.com/hc/articles/204780579#post-api-events-inappconsume).\n\n```ts\nconst trackInAppConsume = (\n payload: Omit\u003c\n InAppEventRequestParams,\n 'clickedUrl' | 'closeAction' | 'inboxSessionId'\n \u003e\n): IterablePromise\u003cIterableResponse\u003e\n```\n\nExample:\n\n```ts\nimport { trackInAppConsume } from '@iterable/web-sdk';\n\ntrackInAppConsume({\n messageId: '123',\n deviceInfo: { appPackageName: 'my-website' }\n})\n .then()\n .catch();\n```\n\nSee also:\n\n- [`InAppEventRequestParams`](#inappeventrequestparams)\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n\n## `trackInAppDelivery`\n\nTracks an `inAppDelivery` event by calling [`POST /api/events/trackInAppDelivery`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappdelivery).\n\n```ts\nconst trackInAppDelivery = (\n payload: Omit\u003c\n InAppEventRequestParams,\n 'clickedUrl' | 'closeAction' | 'inboxSessionId'\n \u003e\n): IterablePromise\u003cIterableResponse\u003e\n```\n\nExample:\n\n```ts\nimport { trackInAppDelivery } from '@iterable/web-sdk';\n\ntrackInAppDelivery({\n messageId: '123',\n deviceInfo: { appPackageName: 'my-website' }\n})\n .then()\n .catch();\n```\n\nSee also:\n\n- [`InAppEventRequestParams`](#inappeventrequestparams)\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n\n## `trackInAppOpen`\n\nTracks an `inAppOpen` event by calling [`POST /api/events/trackInAppOpen`](https://support.iterable.com/hc/articles/204780579#post-api-events-trackinappopen).\n\n```ts\nconst trackInAppOpen = (\n payload: Omit\u003c\n InAppEventRequestParams,\n 'clickedUrl' | 'inboxSessionId' | 'closeAction'\n \u003e\n): IterablePromise\u003cIterableResponse\u003e\n```\n\nExample:\n\n```ts\nimport { trackInAppOpen } from '@iterable/web-sdk';\n\ntrackInAppOpen({\n messageId: '123',\n deviceInfo: { appPackageName: 'my-website' }\n})\n .then()\n .catch();\n```\n\nSee also:\n\n- [`InAppEventRequestParams`](#inappeventrequestparams)\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n\n## `trackPurchase`\n\nTracks a `purchase` event by calling [`POST /api/commerce/trackPurchase`](https://support.iterable.com/hc/articles/204780579#post-api-commerce-trackpurchase).\n\n```ts\nconst trackPurchase = (payload: TrackPurchaseRequestParams): IterablePromise\u003cIterableResponse\u003e\n```\n\nExample:\n\n```ts\nimport { trackPurchase } from '@iterable/web-sdk';\n\ntrackPurchase({\n items: [{ id: '123', name: 'keyboard', price: 100, quantity: 2 }],\n total: 200\n})\n .then()\n .catch();\n```\n\nSee also:\n\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n- [`TrackPurchaseRequestParams`](#trackpurchaserequestparams)\n\n## `updateCart`\n\nUpdates 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).\n\n```ts\nconst updateCart = (payload: UpdateCartRequestParams): IterablePromise\u003cIterableResponse\u003e\n```\n\nExample:\n\n```ts\nimport { updateCart } from '@iterable/web-sdk';\n\nupdateCart({\n items: [{ id: '123', price: 100, name: 'keyboard', quantity: 1 }]\n})\n .then()\n .catch();\n```\n\nSee also:\n\n- [`UpdateCartRequestParams](#updatecartrequestparams)\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n\n## `updateSubscriptions`\n\nUpdates the user's subscriptions by calling [`POST /api/users/updateSubscriptions`](https://support.iterable.com/hc/articles/204780579#post-api-users-updatesubscriptions).\n\n```ts\nconst updateSubscriptions = (\n payload: Partial\u003cUpdateSubscriptionParams\u003e = {}\n): IterablePromise\u003cIterableResponse\u003e\n```\n\nExample:\n\n```ts\nimport { updateSubscriptions } from '@iterable/web-sdk';\n\nupdateSubscriptions({ emailListIds: [1, 2, 3] })\n .then()\n .catch();\n```\n\nSee also:\n\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n- [`UpdateSubscriptionParams`](#updatesubscriptionparams)\n\n## `updateUser`\n\nUpdates 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).\n\n```ts\nconst updateUser = (payload: UpdateUserParams = {}): IterablePromise\u003cIterableResponse\u003e\n```\n\nExample:\n\n```ts\nimport { updateUser } from '@iterable/web-sdk';\n\nupdateUser({ dataFields: {} }).then().catch();\n```\n\nSee also:\n\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n- [`UpdateUserParams`](#updateuserparams)\n\n## `updateUserEmail`\n\nUpdates the current user's `email` by calling [`POST /api/users/updateEmail`](https://support.iterable.com/hc/articles/204780579#post-api-users-updateemail).\nCauses the SDK to fetch a JWT for the new email address.\n\n```ts\nupdateUserEmail: (newEmail: string): IterablePromise\u003cIterableResponse\u003e\n```\n\nExample:\n\n```ts\nimport { updateUserEmail } from '@iterable/web-sdk';\n\nupdateUserEmail('user@example.com').then().catch();\n```\n\nSee also:\n\n- [`IterablePromise`](#iterablepromise)\n- [`IterableResponse`](#iterableresponse)\n\n# Classes, interfaces, types, and enums\n\nThis section describes classes, interfaces, and enums to be aware of when working \nwith Embedded Messaging in Iterable's Web SDK.\n\n| Type | Description |\n| --------------------------------------------------------------------------------- | ----------- |\n| [`CloseButton`](#closebutton) | Specifies how the SDK should display a close button on the associated in-app message. Passed as part of [`InAppMessagesRequestParams`](#inappmessagesrequestparams). |\n| [`CloseButtonPosition`](#closebuttonposition) | Specifies the position of the close button on the associated in-app message. |\n| [`CommerceItem`](#commerceitem) | An item being purchased or added to a shopping cart. Include when calling [`trackPurchase`](#trackpurchase) or [`updateCart`](#updatecart). |\n| [`CommerceUser`](#commerceuser) | Information about the user associated with a purchase or cart update. Include when calling [`trackPurchase`](#trackpurchase) or [`updateCart`](#updatecart). |\n| [`DisplayOptions`](#displayoptions) | Display options to pass to [`getInAppMessages`](#getinappmessages) to indicate whether messages should be displayed immediately or later. |\n| [`DisplayPosition`](#displayposition) | Describes where an in-app message should be displayed. Part of [`WebInAppDisplaySettings`](#webinappdisplaysettings). |\n| [`Elements`](#elements) | Custom styles to apply to `IterableEmbeddedCard`, `IterableEmbeddedBanner`, and `IterableEmbeddedNotification` views for embedded messages. |\n| [`GenerateJWTPayload`](#generatejwtpayload) | The payload to pass to the `generateJWT` function when calling [`initialize`](#initialize) or [`initializeWithConfig`](#initializewithconfig). |\n| [`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. |\n| [`GetInAppMessagesResponse`](#getinappmessagesresponse) | Return value for [`getInAppMessages`](#getinappmessages), when it's called without the `options` parameter. |\n| [`HandleLinks`](#handlelinks) | Describes where in-app links should be opened. Part of [`InAppMessagesRequestParams`](#inappmessagesrequestparams). |\n| [`InAppMessage`](#inappmessage) | A single in-app message. |\n| [`InAppDisplaySetting`](#inappdisplaysetting) | Display settings for an in-app message, including padding percentages. |\n| [`InAppEventRequestParams`](#inappeventrequestparams) | Data to pass to [`trackInAppClick`](#trackinappclick), [`trackInAppClose`](#trackinappclose), [`trackInAppConsume`](#trackinappconsume), [`trackInAppDelivery`](#trackinappdelivery), and [`trackInAppOpen`](#trackinappopen). |\n| [`InAppMessagesRequestParams`](#inappmessagesrqeuestparams) | Data to pass to [`getInAppMessages`](#getinappmessages). |\n| [`InAppMessageResponse`](#inappmessageresponse) | Return value for [`getInAppMessages`](#getinappmessages), when it's called with the `options` parameter. |\n| [`InAppTrackRequestParams`](#inapptrackrequestparams) | Data to pass to [`track`](#track). |\n| [`IterableAction`](#iterableaction) | An action associated with a click. The type of the action, and its associated URL. |\n| [`IterableActionContext`](#iterableactioncontext) | Information about the context of an `IterableAction`. For example, the associated message type. Only used with embedded messages. |\n| [`IterableActionSource`](#iterableactionsource) | An enum of possible message types to which an `IterableAction` can be associated. Currently, only `EMBEDDED` is supported. |\n| [`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. |\n| [`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. |\n| [`IterableEmbeddedButton`](#iterableembeddedbutton) | Payload for a button associated with an embedded message. | \n| [`IterableEmbeddedButtonAction`](#iterableembeddedbuttonaction) | Payload for the action associated with an embedded message button. |\n| [`IterableEmbeddedClickRequestPayload`](#iterableembeddedclickrequestpayload) | Data to pass to [`trackEmbeddedClick`](#trackembeddedclick). | \n| [`IterableEmbeddedDefaultAction`](#iterableembeddeddefaultaction) | The default action associated with an embedded message. Invoked when a user clicks on an embedded message, but outside of its buttons. | \n| [`IterableEmbeddedElements`](#iterableembeddedelements) | Content associated with an embedded message — title, body, media URL, buttons, default action, and extra text fields. |\n| [`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. |\n| [`IterableEmbeddedManager`](#iterableembeddedmanager) | Used to fetch embedded messages from Iterable, and pass them to application code as necessary. |\n| [`IterableEmbeddedMessage`](#iterableembeddedmessage) | A single embedded message to display, including title text, body text, buttons, an image URL, click actions, text fields, and JSON data. |\n| [`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. |\n| [`IterableEmbeddedMetadata`](#iterableembeddedmetadata) | Identifying information about an embedded message. |\n| [`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. |\n| [`IterableEmbeddedSessionManager`](#iterableembeddedsessionmanager) | Used to track sessions and impressions, and to save them back to Iterable. |\n| [`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. |\n| [`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. |\n| [`IterableErrorStatus`](#iterableerrorstatus) | Errors that can come back with an [`IterableResponse`](#iterableresponse). |\n| [`IterablePromise`](#iterablepromise) | A promise. |\n| [`IterableResponse`](#iterableresponse) | A response from Iterable's API. |\n| [`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. |\n| [`OOTB`](#ootb) | A type that defines the parameters to provide when calling `IterableEmbeddedCard`, `IterableEmbeddedBanner`, and `IterableEmbeddedNotification`. |\n| [`Options`](#options) | Configuration options to pass to [`initializeWithConfig`](#initializewithconfig). |\n| [`OutOfTheBoxButton`](#outoftheboxbutton) | Custom styles to apply to buttons in an embedded message. The same as `OutOfTheBoxElement`, but with an extra `disabledStyles` string. |\n| [`OutOfTheBoxElement`](#outoftheboxelement) | The custom styles to apply to a single element of an embedded message. |\n| [`SDKInAppMessagesParams`](#sdkinappmessagesparams) | Parent interface for [`InAppMessagesRequestParams`](#inappmessagesrequestparams). |\n| [`TrackPurchaseRequestParams`](#trackpurchaserequestparams) | Parameters to pass to [`trackPurchase`](#trackpurchase). |\n| [`UpdateCartRequestParams`](#updatecartrequestparams) | Data to pass to [`updateCart`](#updatecart). |\n| [`UpdateSubscriptionParams`](#updatesubscriptionparams) | Data to pass to [`updateSubscriptions`](#updatesubscriptions). |\n| [`UpdateUserParams`](#updateuserparams) | Data to pass to [`updateUser`](#updateuser). |\n| [`WebInAppDisplaySettings`](#webinappdisplaysettings) | An object that contains information about how to display the associated in-app message. |\n| [`WithJWT`](#withjwt) | Return value from [`initialize`](#initialize) and [`initializeWithConfig`](#initializeWithConfig). |\n| [`WithJWTParams`](#withjwtparams) | Parameters to pass to [`initializeWithConfig`](#initializewithconfig). |\n\n## `CloseButton`\n\nSpecifies how the SDK should display a close button on the associated in-app message. \nPassed as part of [`InAppMessagesRequestParams`](#inappmessagesrequestparams).\n\n```ts\ntype CloseButton = {\n color?: string;\n iconPath?: string;\n // If true, prevent user from dismissing in-app message by clicking outside \n // of message\n isRequiredToDismissMessage?: boolean;\n position?: CloseButtonPosition;\n sideOffset?: string;\n size?: string | number;\n topOffset?: string;\n};\n```\n\nSee also:\n\n- [`CloseButtonPosition`](#closebuttonposition)\n\n## `CloseButtonPosition`\n\nSpecifies the position of the close button on the associated in-app message.\n\n```ts\ndeclare enum CloseButtonPosition {\n TopLeft = \"top-left\",\n TopRight = \"top-right\"\n}\n```\n\n## `CommerceItem`\n\nAn item being purchased or added to a shopping cart. Include when calling \n[`trackPurchase`](#trackpurchase) or [`updateCart`](#updatecart).\n\n```ts\ninterface CommerceItem {\n id: string;\n sku?: string;\n name: string;\n description?: string;\n categories?: string[];\n price: number;\n quantity: number;\n imageUrl?: string;\n url?: string;\n dataFields?: Record\u003cstring, any\u003e;\n}\n```\n\n## `CommerceUser`\n\nInformation about the user associated with a purchase or cart update. Include\nwhen calling [`trackPurchase`](#trackpurchase) or [`updateCart`](#updatecart).\n\n```ts\ninterface CommerceUser {\n dataFields?: Record\u003cstring, any\u003e;\n preferUserId?: boolean;\n mergeNestedObjects?: boolean;\n}\n```\n\n## `DisplayOptions`\n\nDisplay options to pass to [`getInAppMessages`](#getinappmessages) to indicate\nwhether messages should be displayed immediately or later.\n\n```ts\ndeclare enum DisplayOptions {\n Immediate = \"immediate\",\n Deferred = \"deferred\"\n}\n```\n\n## `DisplayPosition`\n\nDescribes where an in-app message should be displayed. Part of [`WebInAppDisplaySettings`](#webinappdisplaysettings).\n\n```ts\ndeclare enum DisplayPosition {\n Center = \"Center\",\n TopRight = \"TopRight\",\n BottomRight = \"BottomRight\",\n Full = \"Full\"\n}\n```\n\nSee also:\n\n- [`WebInAppDisplaySettings`](#webinappdisplaysettings)\n\n## `Elements`\n\nCustom styles to apply to `IterableEmbeddedCard`, `IterableEmbeddedBanner`, and\n`IterableEmbeddedNotification` views for embedded messages.\n\n```ts\ntype Elements = {\n // img div\n img?: OutOfTheBoxElement;\n // title div\n title?: OutOfTheBoxElement;\n // primary button div\n primaryButton?: OutOfTheBoxButton;\n // secondary button div\n secondaryButton?: OutOfTheBoxButton;\n // body button div\n body?: OutOfTheBoxElement;\n // root OOTB div\n parent?: OutOfTheBoxElement;\n // button wrapper div\n buttonsDiv?: OutOfTheBoxElement;\n // title and parent wrapper div\n textTitle?: OutOfTheBoxElement;\n // textTitleImg div\n textTitleImg?: OutOfTheBoxElement;\n};\n```\n\nSee also:\n\n- [`OutOfTheBoxElement`](#outoftheboxelement)\n- [`OutOfTheBoxButton`](#outoftheboxbutton)\n\n## `GenerateJWTPayload`\n\nThe payload to pass to the `generateJWT` function when calling [`initialize`](#initialize) \nor [`initializeWithConfig`](#initializewithconfig).\n\n```ts\ninterface GenerateJWTPayload {\n email?: string;\n userID?: string;\n}\n```\n\n## `ErrorHandler`\n\nAn error-handling function. Passed as a parameter to [`IterableEmbeddedCard`](#iterableembeddedcard), \n[`IterableEmbeddedBanner`](#iterableembeddedbanner), and [`IterableEmbeddedNotification`](#iterableembeddednotification), \nwhich use the method to handle errors when tracking `embeddedClick` events.\n\n```ts\ninterface ErrorHandler {\n (error: any): void;\n}\n```\n\n## `GetInAppMessagesResponse`\n\nReturn value for [`getInAppMessages`](#getinappmessages), when it's called without \nthe `options` parameter.\n\n```ts\ninterface GetInAppMessagesResponse {\n pauseMessageStream: () =\u003e void;\n resumeMessageStream: () =\u003e Promise\u003cHTMLIFrameElement | ''\u003e;\n request: () =\u003e IterablePromise\u003cInAppMessageResponse\u003e;\n triggerDisplayMessages: (\n messages: Partial\u003cInAppMessage\u003e[]\n ) =\u003e Promise\u003cHTMLIFrameElement | ''\u003e;\n}\n```\n\n## `HandleLinks`\n\nDescribes where in-app links should be opened. Part of [`InAppMessagesRequestParams`](#inappmessagesrequestparams).\n\n```ts\ndeclare enum HandleLinks {\n OpenAllNewTab = \"open-all-new-tab\",\n OpenAllSameTab = \"open-all-same-tab\",\n ExternalNewTab = \"external-new-tab\"\n}\n```\n\n## `InAppMessage`\n\nA single in-app message.\n\n```ts\ninterface InAppMessage {\n messageId: string;\n campaignId: number;\n createdAt: number;\n expiresAt: number;\n content: {\n payload?: Record\u003cstring, any\u003e;\n html: string | HTMLIFrameElement;\n inAppDisplaySettings: {\n top: InAppDisplaySetting;\n right: InAppDisplaySetting;\n left: InAppDisplaySetting;\n bottom: InAppDisplaySetting;\n bgColor?: {\n alpha: number;\n hex: string;\n };\n shouldAnimate?: boolean;\n };\n webInAppDisplaySettings: WebInAppDisplaySettings;\n };\n customPayload: Record\u003cstring, any\u003e;\n trigger: {\n type: string;\n };\n saveToInbox: boolean;\n inboxMetadata: {\n title: string;\n subtitle: string;\n icon: string;\n };\n priorityLevel: number;\n read: boolean;\n}\n```\n\nSee also:\n\n- [`InAppDisplaySetting`](#inappdisplaysetting)\n- [`WebInAppDisplaySettings`](#webinappdisplaysettings)\n\n## `InAppDisplaySetting`\n\nDisplay settings for an in-app message, including padding percentages.\n\n```ts\ninterface InAppDisplaySetting {\n percentage?: number;\n displayOption?: string;\n}\n```\n\n## `InAppEventRequestParams`\n\nData to pass to [`trackInAppClick`](#trackinappclick), [`trackInAppClose`](#trackinappclose),\n[`trackInAppConsume`](#trackinappconsume), [`trackInAppDelivery`](#trackinappdelivery), and\n[`trackInAppOpen`](#trackinappopen).\n\n```ts\ninterface InAppEventRequestParams {\n messageId: string;\n clickedUrl?: string;\n messageContext?: {\n saveToInbox?: boolean;\n silentInbox?: boolean;\n location?: string;\n };\n closeAction?: string;\n deviceInfo: {\n appPackageName: string; \n };\n inboxSessionId?: string;\n createdAt?: number;\n}\n```\n\n## `InAppMessagesRequestParams`\n\nData to pass to [`getInAppMessages`](#getinappmessages).\n\n```ts\ninterface InAppMessagesRequestParams extends SDKInAppMessagesParams {\n count: number;\n SDKVersion?: string;\n packageName: string;\n}\n```\n\nSee also:\n\n- [`SDKInAppMessagesParams`](#sdkinappmessagesparams)\n\n## `InAppMessageResponse`\n\nReturn value for [`getInAppMessages`](#getinappmessages), when it's called with\nthe `options` parameter.\n\n```ts\ninterface InAppMessageResponse {\n inAppMessages: Partial\u003cInAppMessage\u003e[];\n}\n```\n\nSee also:\n\n- [`InAppMessage`](#inappmessage)\n\n## `InAppTrackRequestParams`\n\nData to pass to [`track`](#track).\n\n```ts\ninterface InAppTrackRequestParams {\n eventName: string;\n id?: string;\n createdAt?: number;\n dataFields?: Record\u003cstring, any\u003e;\n campaignId?: number;\n templateId?: number;\n}\n```\n\n## `IterableAction`\n\nAn action associated with a click. The type of the action, and its associated\nURL. Only used with embedded messages.\n\n```ts\ninterface IterableAction {\n type: string;\n data: string;\n}\n```\n\nThe values for `type` and `data` depend on the type of action assigned to the\ncampaign in Iterable:\n\n- For **Open URL** actions, `type` is `openUrl` and `data` contains the URL.\n- For **Custom action** actions, `type` is the URL, and `data` is empty.\n\n## `IterableActionContext`\n\nInformation about the context of an `IterableAction`. For example, the\nassociated message type. Only used with embedded messages.\n\n```ts\ninterface IterableActionContext {\n action: IterableAction;\n source: IterableActionSource;\n}\n```\n\nSee also:\n\n- [`IterableAction`](#iterableaction)\n- [`IterableActionSource`](#iterableactionsource)\n\n## `IterableActionSource`\n\nAn enum of possible message types to which an `IterableAction` can be associated. \nCurrently, only `EMBEDDED` is supported.\n\n```ts\nenum IterableActionSource {\n EMBEDDED = 'EMBEDDED'\n}\n```\n\n## `IterableConfig`\n\nA class that can hold configuration information for the SDK. Currently, only\n`urlHandler` and `customActionHandler` are supported (static properties), and\nthese are only invoked for URLs and custom actions coming from embedded messages.\n\n```ts\nclass IterableConfig {\n public static urlHandler: IterableUrlHandler | null = null;\n public static customActionHandler: IterableCustomActionHandler | null = null;\n}\n```\n\nSee also:\n\n- [`IterableUrlHandler`](#iterableurlhandler)\n- [`IterableCustomActionHandler`](#iterablecustomactionhandler)\n\n## `IterableCustomActionHandler`\n\nAn interface that defines `handleIterableCustomAction`, which the SDK can call to \nhandle custom action URLs (`action://`) URLs that result from from clicks on \nembedded messages.\n\n```ts\ninterface IterableCustomActionHandler {\n handleIterableCustomAction(\n action: IterableAction,\n actionContext: IterableActionContext\n ): boolean;\n}\n```\n\nSee also:\n\n- [`IterableAction`](#iterableaction)\n- [`IterableActionContext`](#iterableactioncontext)\n\n## `IterableEmbeddedButton`\n\nPayload for a button associated with an embedded message. \n\n```ts\ninterface IterableEmbeddedButton {\n id: string;\n title?: string;\n action?: IterableEmbeddedButtonAction;\n}\n```\n\nSee also:\n\n- [`IterableEmbeddedButtonAction`](#iterableembeddedbuttonaction)\n\n## `IterableEmbeddedButtonAction`\n\nPayload for the action associated with an embedded message button.\n\n```ts\ninterface IterableEmbeddedButtonAction {\n type: string;\n data?: string;\n}\n```\n\nThe values for `type` and `data` depend on the type of action assigned to the\ncampaign in Iterable:\n\n- For **Open URL** actions, `type` is `openUrl` and `data` contains the URL.\n- For **Custom action** actions, `type` is the URL, and `data` is empty.\n\n## `IterableEmbeddedClickRequestPayload`\n\nData to pass to [`trackEmbeddedClick`](#trackembeddedclick).\n\n```ts\ninterface IterableEmbeddedClickRequestPayload {\n messageId: string;\n buttonIdentifier: string;\n targetUrl: string;\n appPackageName: string;\n}\n```\n\n## `IterableEmbeddedDefaultAction`\n\nThe default action associated with an embedded message. Invoked when a user\nclicks on an embedded message, but outside of its buttons.\n\n```ts\ninterface IterableEmbeddedDefaultAction {\n type: string;\n data?: string;\n}\n```\n\nThe values for `type` and `data` depend on the type of action assigned to the\ncampaign in Iterable:\n\n- For **Open URL** actions, `type` is `openUrl` and `data` contains the URL.\n- For **Custom action** actions, `type` is the URL, and `data` is empty.\n\n## `IterableEmbeddedElements`\n\nContent associated with an embedded message — title, body, media URL,\nbuttons, default action, and extra text fields.\n\n```ts\ninterface IterableEmbeddedElements {\n title?: string;\n body?: string;\n mediaUrl?: string;\n buttons?: IterableEmbeddedButton[];\n text?: IterableEmbeddedText[];\n defaultAction?: IterableEmbeddedDefaultAction;\n}\n```\n\nSee also:\n\n- [`IterableEmbeddedButton`](#iterableembeddedbutton)\n- [`IterableEmbeddedText`](#iterableembeddedtext)\n- [`IterableEmbeddedDefaultAction`](#iterableembeddeddefaultaction)\n\n## `IterableEmbeddedImpression`\n\nThe number of times a given embedded message appeared during a specific session,\nand the total duration of all those appearances. Also includes other metadata\nabout the impression.\n\n```ts\ninterface IterableEmbeddedImpression {\n messageId: string;\n displayCount: number;\n displayDuration: number;\n placementId?: number;\n}\n```\n\n## `IterableEmbeddedManager`\n\nUsed to fetch embedded messages from Iterable, and pass them to application code\nas necessary.\n\n```ts\nclass IterableEmbeddedManager {\n appPackageName: string;\n constructor(appPackageName: string);\n syncMessages(packageName: string, callback: () =\u003e void, placementIds?: number[]): Promise\u003cvoid\u003e;\n getMessages(): IterableEmbeddedMessage[];\n getMessagesForPlacement(placementId: number): IterableEmbeddedMessage[];\n addUpdateListener(updateListener: IterableEmbeddedMessageUpdateHandler): void;\n getUpdateHandlers(): IterableEmbeddedMessageUpdateHandler[];\n click(clickedUrl: string | null): void;\n}\n```\n\nDescriptions:\n\n- `appPackageName` – The package name you use to identify your website. Set\n this value by passing it to the constructror.\n\n- `syncMessages` – Fetches embedded messages for which the signed-in user is\n eligible. If `placementIds` is provided, fetches only messages for those\n placements. Calls `callback` after fetching messages.\n\n- `getMessages` – Returns all embedded messages that the SDK has already fetched.\n Does not fetch messages from the server.\n\n- `getMessagesForPlacement` – Returns all embedded messages for a given placement\n ID. Does not fetch messages from the server.\n\n- `addUpdateListener` – Registers an object that implements the\n `IterableEmbeddedMessageUpdateHandler` interface. The SDK calls the object's\n `onMessagesUpdated` and `onEmbeddedMessagingDisabled` methods as necessary\n after fetching embedded messages from the server.\n\n- `getUpdateHandlers` – Returns all objects that have been registered as update\n listeners.\n\n- `click` – Passes the provided URL (depending on its type) to the URL handler \n or custom action handler defined on `IterableConfig`. `action://` URLs are\n passed to the custom action handler, and other URLs are passed to the URL \n handler. The SDK does not currently support `iterable://` URLs for \n embedded messages.\n\nSee also:\n\n- [`IterableEmbeddedMessage`](#iterableembeddedmessage)\n- [`IterableEmbeddedMessageUpdateHandler`](#iterableembeddedmessageupdatehandler)\n- [`IterableConfig`](#iterableconfig)\n- [`IterableUrlHandler`](#iterableurlhandler)\n- [`IterableCustomActionHandler`](#iterablecustomactionhandler)\n\n## `IterableEmbeddedMessage`\n\nA single embedded message to display, including title text, body text, buttons,\nan image URL, click actions, text fields, and JSON data.\n\n```ts\ninterface IterableEmbeddedMessage {\n metadata: IterableEmbeddedMetadata;\n elements?: IterableEmbeddedElements;\n payload?: Record\u003cstring, any\u003e;\n}\n```\n\nSee also:\n\n- [`IterableEmbeddedMetadata`](#iterableembeddedmetadata)\n- [`IterableEmbeddedElements`](#iterableembeddedelements)\n\n## `IterableEmbeddedMessageUpdateHandler`\n\nAn object that defines `onMessagesUpdated` and `onEmbeddedMessagingDisabled`\nmethods. If this object is registered as an update listener for embedded messages\n(you can do this by calling `addUpdateListener` on [`IterableEmbeddedManager`](#iterableembeddedmanager)),\nthe SDK calls these methods as necessary after fetching embedded messages from \nthe server.\n\n```ts\ninterface IterableEmbeddedMessageUpdateHandler {\n onMessagesUpdated: () =\u003e void;\n onEmbeddedMessagingDisabled: () =\u003e void;\n}\n```\n\nDescriptions:\n\n- `onMessagesUpdated` – Called by the SDK after it fetches embedded messages\n from Iterable. Use this method to display messages.\n\n- `onEmbeddedMessagingDisabled` – Called by the SDK if there are errors fetching\n embedded messages from Iterable. Use this method to display an empty state\n or hide the placement.\n\n## `IterableEmbeddedMetadata`\n\nIdentifying information about an embedded message.\n\n```ts\ninterface IterableEmbeddedMetadata {\n messageId: string;\n campaignId?: number;\n isProof?: boolean;\n placementId?: number;\n}\n```\n\n## `IterableEmbeddedSession`\n\nRepresents a period of time during which a user was on a page where they could\npotentially view embedded messages. Contains an ID, a start time, and an end\ntime.\n\n```ts\ninterface IterableEmbeddedSession {\n id: string;\n start?: number;\n end?: number;\n}\n```\n\n## `IterableEmbeddedSessionManager`\n\nUsed to track sessions and impressions, and to save them back to Iterable.\n\n```ts\nclass IterableEmbeddedSessionManager {\n appPackageName: string;\n session: EmbeddedSession;\n constructor(appPackageName: string);\n startSession(): void;\n endSession(): Promise\u003cvoid\u003e;\n startImpression(messageId: string, placementId: number): void;\n pauseImpression(messageId: string): void;\n}\n```\n\nDescriptions:\n\n- `appPackageName` – The package name you use to identify your website. Set\n this value by passing it to the constructor.\n\n- `session` – The current session. Set by calling `startSession` and `endSession`.\n\n- `startSession` – Starts a new session. A session is a period of time when a \n user is on a page where embedded messages can be displayed.\n\n- `endSession` – Ends the active session, and saves data about the session and\n its associated impressions back to Iterable.\n\n- `startImpression` – Starts a new impression for a given message ID and placement\n ID. An impression captures the number of times a given messages is visible during\n a given session, and the total duration of all those appearances.\n\n- `pauseImpression` – Pauses the impression for a given message ID. Call this method\n when a message is no longer visible. If the message becomes visible again, \n call `startImpression` to resume the impression.\n\n## `IterableEmbeddedSessionRequestPayload`\n\nData to pass to [`trackEmbeddedSession`](#trackembeddedsession). You won't usually\ninteract manually with this interface, since the [`IterableEmbeddedSessionManager`](#iterableembeddedsessionmanager)\nhandles the tracking of sessions and impressions for you.\n\n```ts\ninterface IterableEmbeddedSessionRequestPayload {\n session: IterableEmbeddedSession;\n impressions?: IterableEmbeddedImpression[];\n appPackageName: string;\n}\n```\n\nSee also:\n\n- [`IterableEmbeddedSession`](#iterableembeddedsession)\n- [`IterableEmbeddedImpression`](#iterableembeddedimpression)\n\n## `IterableEmbeddedText`\n\nExtra text fields sent along with an embedded message. Like custom JSON, these\ntext fields can be used to pass data as part of an embedded message. \n\n```ts\ninterface IterableEmbeddedText {\n id: string;\n text?: string;\n}\n```\n\n## `IterableErrorStatus`\n\nErrors that can come back with an [`IterableResponse`](#iterableresponse).\n\n```ts\ntype IterableErrorStatus =\n | 'Success'\n | 'BadApiKey'\n | 'BadParams'\n | 'BadJsonBody'\n | 'QueueEmailError'\n | 'GenericError'\n | 'InvalidEmailAddressError'\n | 'DatabaseError'\n | 'EmailAlreadyExists'\n | 'Forbidden'\n | 'JwtUserIdentifiersMismatched'\n | 'InvalidJwtPayload';\n```\n\n## `IterablePromise`\n\nA promise.\n\n```ts\nIterablePromise\u003cT = any\u003e = AxiosPromise\u003cT\u003e;\n```\n\n## `IterableResponse`\n\nA response from Iterable's API.\n\n```ts\ninterface IterableResponse {\n code: IterableErrorStatus;\n msg: string;\n params?: null | Record\u003cstring, any\u003e;\n}\n```\n\n## `IterableUrlHandler`\n\nAn interface that defines `handleIterableURL`, which the SDK can call to handle\nstandard URLs (`https://`, `custom://`, but not `action://`) that result from \nfrom clicks on embedded messages.\n\n```ts\ninterface IterableUrlHandler {\n handleIterableURL(uri: string, actionContext: IterableActionContext): boolean;\n}\n```\n\nSee also:\n\n- [`IterableActionContext`](#iterableactioncontext)\n- [`IterableConfig`](#iterableconfig)\n- [`IterableEmbeddedManager`](#iterableembeddedmanager)\n\n## `OOTB`\n\nA type that defines the parameters to provide when calling\n`IterableEmbeddedCard`, `IterableEmbeddedBanner`, and\n`IterableEmbeddedNotification`.\n\n```ts\ntype OOTB = {\n appPackageName: string;\n message: IterableEmbeddedMessage;\n htmlElements?: Elements;\n // Callback method to handle button or element click errors\n errorCallback?: ErrorHandler;\n};\n```\n\nSee also:\n\n- [`Elements`](#elements)\n- [`IterableEmbeddedBanner`](#iterableembeddedcard)\n- [`IterableEmbeddedCard`](#iterableembeddedbanner)\n- [`IterableEmbeddedNotification`](#iterableembeddednotification)\n- [`IterableEmbeddedMessage`](#iterableembeddedmessage)\n- [`ErrorHandler`](#errorhandler)\n\n## `Options`\n\nConfiguration options to pass to [`initializeWithConfig`](#initializewithconfig).\n\n```ts\ntype Options = {\n logLevel: 'none' | 'verbose';\n baseURL: string;\n isEuIterableService: boolean;\n dangerouslyAllowJsPopups: boolean;\n};\n```\n\n## `OutOfTheBoxButton`\n\nCustom styles to apply to buttons in an embedded message. The same as\n`OutOfTheBoxElement`, but with an extra `disabledStyles` string.\n\n```ts\ntype OutOfTheBoxButton = OutOfTheBoxElement \u0026 {\n // Stringified CSS to be passed to element \"style\" tag. The presence of this \n // value determines whether or not the button is in disabled.\n disabledStyles?: string;\n};\n```\n\n## `OutOfTheBoxElement`\n\nThe custom styles to apply to a single element of an embedded message.\n\n```ts\ntype OutOfTheBoxElement = {\n // id of the element \n id?: string;\n // Stringified CSS to be passed to element \"style\" tag\n styles?: string;\n};\n```\n\n## `SDKInAppMessagesParams`\n\nParent interface for [`InAppMessagesRequestParams`](#inappmessagesrequestparams).\n\n```ts\ninterface SDKInAppMessagesParams {\n displayInterval?: number;\n onOpenScreenReaderMessage?: string;\n onOpenNodeToTakeFocus?: string;\n topOffset?: string;\n bottomOffset?: string;\n rightOffset?: string;\n animationDuration?: number;\n handleLinks?: HandleLinks;\n closeButton?: CloseButton;\n // messageId of the latest (i.e., most recent) message in the device's \n // local cache \n latestCachedMessageId?: string;\n}\n```\n\nSee also:\n\n- [`InAppMessaagesRequestParams`](#inappmessagesrequestparams)\n\nSee also:\n\n- [`HandleLinks`](#handlelinks)\n- [`CloseButton`](#closebutton)\n\n## `TrackPurchaseRequestParams`\n\nParameters to pass to [`trackPurchase`](#trackpurchase).\n\n```ts\ninterface TrackPurchaseRequestParams {\n id?: string;\n user?: CommerceUser;\n items: CommerceItem[];\n campaignId?: string;\n templateId?: string;\n total: number;\n createdAt?: number;\n dataFields?: Record\u003cstring, any\u003e;\n}\n```\n\nSee also:\n\n- [`CommerceUser`](#commerceuser)\n- [`CommerceItem`](#commerceitem)\n\n## `UpdateCartRequestParams`\n\nData to pass to [`updateCart`](#updatecart).\n\n```ts\ninterface UpdateCartRequestParams {\n user?: CommerceUser;\n items: CommerceItem[];\n}\n```\n\nSee also:\n\n- [`CommerceUser`](#commerceuser)\n- [`CommerceItem`](#commerceitem)\n\n## `UpdateSubscriptionParams`\n\nData to pass to [`updateSubscriptions`](#updatesubscriptions).\n\n```ts\ninterface UpdateSubscriptionParams {\n emailListIds: number[];\n unsubscribedChannelIds: number[];\n unsubscribedMessageTypeIds: number[];\n subscribedMessageTypeIds: number[];\n campaignId: number;\n templateId: number;\n}\n```\n\n## `UpdateUserParams`\n\nData to pass to `updateUser`.\n\n```ts \ninterface UpdateUserParams {\n dataFields?: Record\u003cstring, any\u003e;\n preferUserId?: boolean;\n mergeNestedObjects?: boolean;\n}\n```\n\n## `WebInAppDisplaySettings`\n\nAn object that contains information about how to display the associated in-app \nmessage.\n\n```ts\ninterface WebInAppDisplaySettings {\n position: DisplayPosition;\n}\n```\n\nSee also:\n\n- [`DisplayPosition`](#displayposition)\n\n## `WithJWT`\n\nReturn value from [`initialize`](#initialize) and [`initializeWithConfig`](#initializeWithConfig).\n\n```ts\ninterface WithJWT {\n clearRefresh: () =\u003e void;\n setEmail: (email: string) =\u003e Promise\u003cstring\u003e;\n setUserID: (userId: string) =\u003e Promise\u003cstring\u003e;\n logout: () =\u003e void;\n refreshJwtToken: (authTypes: string) =\u003e Promise\u003cstring\u003e;\n}\n```\n\nDefinitions:\n\n- `clearRefresh` – Clears the JWT refresh timer.\n- `setEmail` – Identifies the current user by `email`, and fetches a valid JWT \n token by calling the `generateJWT` function passed to [`initialize`](#initialize) \n or [`initializeWithConfig`](#initializeWithConfig).\n- `setUserID` - Identifies the current user by `userId`, and fetches a valid JWT \n token by calling the `generateJWT` function passed to [`initialize`](#initialize) \n or [`initializeWithConfig`](#initializeWithConfig).\n- `refreshJwtToken` – Manually refreshes the JWT token for the signed-in user.\n- `logout` – Signs the current user out of the SDK.\n\n## `WithJWTParams`\n\nParameters to pass to [`initializeWithConfig`](#initializewithconfig).\n\n```ts\ninterface WithJWTParams {\n authToken: string;\n configOptions: Partial\u003cOptions\u003e;\n generateJWT: (payload: GenerateJWTPayload) =\u003e Promise\u003cstring\u003e;\n}\n```\n\n`generateJWT` should be a function that takes a `userId` or `email` and uses\nit to fetch, from your server, a valid JWT token for that user. The function\nshould return the token as a string.\n\nSee also:\n\n- [`Options`](#options)\n- [`GenerateJWTPayload`](#generatejwtpayload)\n\n# FAQ\n\n## How do I use Iterable's Web SDK to fetch and display embedded messages?\n\nFor detailed instructions about how to use Iterable's Web SDK SDK to fetch and\ndisplay embedded messages, see [Embedded Messages with Iterable's Web SDK](https://support.iterable.com/hc/articles/27537816889108).\n\nFor more information about Embedded Messaging, read the [Embedded Messaging Oveview](https://support.iterable.com/hc/articles/23060529977364).\n\n## How does SDK add the user's `email` or `userId` to the requests it makes to Iterable?\n\nThe SDK uses a library called [Axios](https://github.com/axios/axios). To add\nuser information to outgoing requests, the SDK uses [Axios interceptors](https://github.com/axios/axios#interceptors).\n\n## How can I manipulate the API requests the SDK makes to Iterable?\n\nIterable's Web SDK SDK exposes the base Axios request instance, which you can \nmodify as necessary. For example:\n\n```ts\nimport { baseAxiosRequest } from '@iterable/web-sdk';\n```\n\nFor example, if you want to set an `email` query param on every outgoing\nrequest, you could do somethign like this:\n\n```ts\nimport { baseAxiosRequest } from '@iterable/web-sdk';\n\n(() =\u003e {\n baseAxiosRequest.interceptors.request.use((config) =\u003e {\n return {\n ...config,\n params: {\n ...config.params,\n email: 'user@example.com'\n }\n };\n });\n})();\n```\n\n:rotating_light: You probably won't need to do anything with the underlying\nAxios request. This is only for advanced use cases.\n\n## How do I add a delay between the display of multiple in-app messages?\n\nTo add a delay between the display of multiple in-app messages:\n\n1. In the object you pass as the first parameter to `getInAppMessages`, set\n `displayInterval` to the number of milliseconds you want to wait between\n messages.\n\n2. In the object you pass as the second parameter to `getInAppMessages`, set\n `display` to `deferred`.\n\nThen, to show messages, pause the display of messages, and resume the display of\nmessages, use the methods returned by `getInAppMessages`.\n\nFor example, this code fetches in-app messages from Iterable but doesn't display\nthem:\n\n```ts\nimport { initialize, getInAppMessages } from '@iterable/web-sdk';\n\n(() =\u003e {\n const { setUserID } = initialize('\u003cYOUR_API_KEY\u003e', ({ email, userID }) =\u003e\n yourAsyncJWTGeneratorMethod({ email, userID }).then(\n ({ jwt_token }) =\u003e jwt_token\n )\n );\n\n yourAsyncLoginMethod().then((response) =\u003e {\n setUserID(response.user_id).then(() =\u003e {\n getInAppMessages({\n count: 20,\n packageName: 'my-website'\n })\n .then()\n .catch();\n });\n });\n})();\n```\n\nThis code fetches in-app messages and displays them automatically:\n\n```ts\nimport { initialize, getInAppMessages } from '@iterable/web-sdk';\n\n(() =\u003e {\n const { setUserID } = initialize('\u003cYOUR_API_KEY\u003e', ({ email, userID }) =\u003e\n yourAsyncJWTGeneratorMethod({ email, userID }).then(\n ({ jwt_token }) =\u003e jwt_token\n )\n );\n\n yourAsyncLoginMethod().then((response) =\u003e {\n setUserID(response.user_id).then(() =\u003e {\n const { request } = getInAppMessages(\n {\n count: 20,\n packageName: 'my-website'\n },\n { display: 'immediate' }\n );\n\n // Trigger the start of message presentation\n request().then().catch();\n });\n });\n})();\n```\n\nThis code manipulates the display of in-app messages by setting more fields in\nthe object passed as the first parameter to [`getInAppmessages`](#getinappmessages):\n\n```ts\nimport { initialize, getInAppMessages } from '@iterable/web-sdk';\n\n(() =\u003e {\n const { setUserID } = initialize('\u003cYOUR_API_KEY\u003e', ({ email, userID }) =\u003e\n yourAsyncJWTGeneratorMethod({ email, userID }).then(\n ({ jwt_token }) =\u003e jwt_token\n )\n );\n\n yourAsyncLoginMethod().then((response) =\u003e {\n setUserID(response.user_id).then(() =\u003e {\n const { request } = getInAppMessages(\n {\n count: 20,\n packageName: 'my-website',\n displayInterval: 5000,\n onOpenScreenReaderMessage:\n 'hey screen reader here telling you something just popped up on your screen!',\n onOpenNodeToTakeFocus: 'input',\n topOffset: '20px',\n bottomOffset: '20px',\n rightOffset: '20px',\n animationDuration: 400,\n handleLinks: 'external-new-tab'\n },\n { display: 'immediate' }\n );\n\n // Trigger the start of message presentation\n request().then().catch();\n });\n });\n})();\n```\n\nThis code pauses the display of messages, and then resumes:\n\n```ts\nimport { initialize, getInAppMessages } from '@iterable/web-sdk';\n\n(() =\u003e {\n const { setUserID } = initialize('\u003cAPI_KEY_HERE\u003e', ({ email, userID }) =\u003e\n yourAsyncJWTGeneratorMethod({ email, userID }).then(\n ({ jwt_token }) =\u003e jwt_token\n )\n );\n\n yourAsyncLoginMethod().then((response) =\u003e {\n setUserID(response.user_id).then(() =\u003e {\n const { request, pauseMessageStream, resumeMessageStream } =\n getInAppMessages(\n {\n count: 20,\n packageName: 'my-website'\n },\n { display: 'immediate' }\n );\n\n // Trigger the start of message presentation \n request().then().catch();\n\n // Prevent any more in-app messages from appearing for a little while\n pauseMessageStream();\n\n // Pick up where you left off — show the next message in the queue, and \n // start the timer again.\n resumeMessageStream();\n });\n });\n})();\n```\n\nThis code manipulates the list of in-app messages before displaying them:\n\n```ts\nimport {\n initialize,\n getInAppMessages,\n sortInAppMessages,\n filterHiddenInAppMessages\n} from '@iterable/web-sdk';\n\n(() =\u003e {\n const { setUserID } = initialize('\u003cYOUR_API_KEY\u003e', ({ email, userID }) =\u003e\n yourAsyncJWTGeneratorMethod({ email, userID }).then(\n ({ jwt_token }) =\u003e jwt_token\n )\n );\n\n yourAsyncLoginMethod().then((response) =\u003e {\n setUserID(response.user_id).then(() =\u003e {\n const { request, pauseMessageStream, resumeMessageStream } =\n getInAppMessages(\n {\n count: 20,\n packageName: 'my-website'\n },\n { display: 'deferred' }\n );\n\n // Trigger the start of message presentation\n request()\n .then((response) =\u003e {\n // Do your own manipulation here \n const filteredMessages = doStuffToMessages(\n response.data.inAppMessages\n );\n\n // Also, feel free to take advantage of the sorting/filtering \n // methods used internally \n const furtherManipulatedMessages = sortInAppMessages(\n filterHiddenInAppMessages(response.data.inAppMessages)\n ) as InAppMessage[];\n\n // Display them whenever you want\n triggerDisplayMessages(furtherManipulatedMessages);\n })\n .catch();\n });\n });\n})();\n```\n\n## How can I make sure that in-app messages are displayed responsively?\n\nThe SDK handles this for you. In-app message presentation varies based on \nthe display type (center, full, top-right, bottom-right) you select when sending\nthe campaign:\n\n| Message Position \u0026#8594; \u003cbr\u003e\u003cbr\u003e Browser Size \u0026#8595; | Center | Full | Top-Right | Bottom-Right |\n| ------------------------------------------------------ | ------ | ---- | --------- | ------------ |\n| 0px - 850px | 100% | 100% | 100% | 100% |\n| 851px - 975px | 50% | 100% | 45% | 45% |\n| 976px - 1300px | 50% | 100% | 33% | 33% |\n| 1300px+ | 50% | 100% | 25% | 25% |\n\nFor example:\n\n- If your in-app message is positioned at the top-right of the screen and your\n browser window is at 1000px, your in-app message will take up 33% of the\n screen.\n- If your in-app is positioned in the center and your browser if at 700px, your\n in-app message will grow to take up 100% of the screen.\n\nThis chart also implies that yout in-app message is taking 100% of its container. \nYour results may vary if you add, for example, a `max-width: 200px` CSS rule to \nyour message HTML. \n\nRegardless of how you write your CSS, these rules take effect. So, when creating\nan in-app message, it is best to stick with percentage-based CSS widths.\n\n## How do I add custom callbacks to handle link clicks on in-app and embedded messages?\n\nSee [Link handling](#link-handling).\n\n## What if the user's JWT expires?\n\nThe SDK automatically handles JWT expiration and refresh. It fetches a new JWT\ntoken for the signed-in user at four different times:\n\n- When you sign a user in by calling `setEmail` or `setUserID`.\n- When the JWT is within 1 minute of expiration.\n- When a request to Iterable's API request fails with a `401` response.\n- When your application code calls `updateUserEmail`.\n\nTo fetch a new JWT, the SDK calls the `generateJWT` function passed to\n[`initialize`](#initialize) or [`initializeWithConfig`](#initializeWithConfig).\n\nIf there's a failure when requesting a new JWT, the SDK does not try again.\nAt that point, further requests to Iterable's API will fail.\n\nTo perform a manual JWT token refresh, call [`refreshJwtToken`](#refreshjwttoken).\n\n# Iterable's European data center (EDC)\n\nIf your Iterable project is hosted on Iterable's [European data center (EDC)](https://support.iterable.com/hc/articles/17572750887444), \nyou'll need to configure Iterable's Web SDK to interact with Iterable's EU-based \nAPI endpoints.\n\nTo do this:\n\n- Use [`initializeWithConfig`](#initializeWithConfig) to initialize the SDK \n (rather then [`initialize`](#initialize)).\n- Set the `isEuIterableService` configuration option to `true`. For example:\n\n ```ts\n import { initializeWithConfig } from '@iterable/web-sdk';\n \n const { clearRefresh, setEmail, logout } = initializeWithConfig({\n authToken: 'my-API-key',\n configOptions: {\n isEuIterableService: true,\n },\n generateJWT: ({ email }) =\u003e\n yourAsyncJWTGeneratorMethod({ email }).then(\n ({ jwt_token }) =\u003e jwt_token\n )\n });\n ```\n\n# Link handling\n\nThe SDK allows you to write your own callbacks to implement custom link-handling\nbehavior. However, you'll do this in different ways for embedded messages and\nin-app messages.\n\n## Embedded messaging\n\nTo learn how to handle clicks on links found in embedded messages, read\n[Embedded Messages with Iterable's Web SDK](https://support.iterable.com/hc/articles/27537816889108#step-8-2-handle-urls-and-custom-actions).\n\n## In-app messages\n\nIn-app messages render in an `iframe` element. If you choose to have the SDK \nrender messages automatically, the event handler responsible for handling link\nclicks gets hijacked by internal SDK code. To the user, this doesn't change the\nexperience — links open the link in the same browser tab unless given the\n`target=\"_blank\"` property.\n\nHowever, the `handleLinks` option that you can provide to [`getInAppMessages`](#getInAppMessages) \nallows you to specify how the SDK opens in-app message links: in the current tab, \nin a new tab, or a combination (external links in a new tab, internal links in the current tab). \nFor example, consider this code:\n\n```ts\nimport { getInAppMessages } from '@iterable/web-sdk';\n\ngetInAppMessages({\n count: 5,\n packageName: 'my-website',\n handleLinks: 'external-new-tab'\n});\n```\n\nThis example code ensures the following links open in the same tab if your \ndomain is `mydomain.com`:\n\n```\n/about\nhttps://mydomain.com\nhttps://mydomain.com/about\n```\n\nAnd that these will open in a new tab:\n\n```\nhttps://google.com\nhttps://hello.com\n```\n\n### Reserved URL schemes\n\nFor in-app messages, the SDK reserves the `iterable://` and `action://` URL \nschemes for custom purposes.\n\n1. `iterable://dismiss` - Removes an in-app message from the screen, grabs the\n next one to display, and invokes both [trackInAppClose](#trackInAppClose) and\n [trackInAppClick](#trackInAppClick). Not applicable to embedded messages.\n\n2. `action://\u003cCUSTOM_URL\u003e` - Makes a [`Window.prototype.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage)\n call with payload `{ type: 'iterable-action-link', data: '{anything}' }`, to be\n consumed by the parent website as needed. These links also dismiss the message\n and invoke [trackInAppClose](#trackInAppClose) and [trackInAppClick](#trackInAppClick).\n\nThe SDK may reserve more keywords in the future.\n\n:rotating_light: `iterable://` and `action://` links are not supported with\nWebKit (which affects iOS web browsers, Safari included). In these browsers,\nusers can close an in-app message by clicking away from the message.\n\n### Routing in single-page apps\n\nYou can add custom routing or callback functions for link clicks on in-app\nmessages.\n\nFor example, if you want to intercept a link click and use a client-side routing\nsolution to send the user to your `/about` page, you could so something like this\n(this example assumes that you're using React Router):\n\n```ts\n// This example assumes a click on this link: \n// \u003ca href=\"action://about\"\u003eGo to the about page\u003c/a\u003e\nimport { useHistory } from 'react-router-dom';\n\nconst SomeComponent = () =\u003e {\n const history = useHistory();\n React.useEffect(() =\u003e {\n global.addEventListener('message', (event) =\u003e {\n if (event.data.type \u0026\u0026 event.data.type === 'iterable-action-link') {\n // Route us to the content that comes after \"action://\" \n history.push(`/${event.data.data}`);\n }\n });\n }, []);\n\n return \u003c\u003e\u003c/\u003e;\n};\n```\n\n### Safari: Allowing JavaScript execution in tabs opened by in-app message link clicks\n\nTo display an in-app message, Iterable's Web SDK uses an `iframe` on which the\n`sandbox` attribute is set to `allow-same-origin allow-popups allow-top-navigation`. \nOn Safari, this configuration blocks JavaScript execution in tabs that open because \nof link clicks in the `iframe`.\n\nTo allow JavaScript to run in these new tabs, use [`initializeWithConfig`](#initializeWithConfig) ,\npass in the configuration options, and set `dangerouslyAllowJsPopups` to `true`.\n\nFor example:\n\n```ts\nimport { initializeWithConfig } from '@iterable/web-sdk';\n\nconst { clearRefresh, setEmail, setUserID, logout } = initializeWithConfig({\n authToken: '\u003c\u003cYOUR_API_KEY\u003e\u003e',\n configOptions: {\n isEuIterableService: false,\n dangerouslyAllowJsPopups: true,\n },\n // email will be defined if you call setEmail\n // userID will be defined if you call setUserID\n generateJWT: ({ email, userID }) =\u003e\n yourAsyncJWTGeneratorMethod({ email, userID }).then(\n ({ jwt_token }) =\u003e jwt_token\n )\n}\n);\n```\n\nHowever, use caution. Allowing JavaScript to run in new tabs opens the door to\nthe possibility of malicious code execution.\n\nSDK version support:\n\n- Versions [`1.0.11+`](https://github.com/Iterable/iterable-web-sdk/releases/tag/v1.0.10)\n of Iterable's Web SDK support the `DANGEROUSLY_ALLOW_JS_POPUP_EXECUTION`\n environment variable.\n\nFor more information, see:\n\n- [MDN docs for `allow-popups-to-escape-sandbox`](https://developer.mozilla.org/docs/Web/HTML/Element/iframe#allow-popups-to-escape-sandbox)\n- [Can I Use? `allow-popups-to-escape-sandbox`](https://caniuse.com/mdn-html_elements_iframe_sandbox_allow-popups-to-escape-sandbox)\n\n# TypeScript\n\nIterable's Web SDK includes TypeScript definitions. All SDK methods should be\ntyped for you, but if you need to import specific typings, you can parse through\neach `types.d.ts` file inside of the `./dist` directory to find what you need.\nRequest and response payloads should all be available.\n\nIf something is missing, please let us know.\n\n# Contributing\n\nLooking to contribute? Please see the [contributing instructions here](./CONTRIBUTING.md) \nfor more details.\n\n# License\n\nThis SDK is released under the MIT License. See [LICENSE](./LICENSE.md) for more\ninformation.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiterable%2Fiterable-web-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiterable%2Fiterable-web-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiterable%2Fiterable-web-sdk/lists"}