Setting up Iterable's Web SDK

This guide describes, at a high level, how to use Iterable's web SDK with your website.

# In this article

# GitHub repository

To see the code for Iterable's web SDK, and for a detailed look at the various methods and customizations it supports, check out https://github.com/iterable/iterable-web-sdk.

# Prerequistes

Before following the instructions in this guide, be sure to add your website to Iterable.

# Step 1: On your website, install Iterable's web SDK

To install Iterable's web SDK, use npm, Yarn, or a script tag:

• npm

  npm install @iterable/web-sdk
  

• Yarn

  yarn add @iterable/web-sdk
  

• script tag:

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

# Step 2: Create a JWT-enabled API key and JWT secret

After you've installed Iterable's web SDK, you'll need to create a JWT-enabled API key it can use to authenticate with Iterable.

• Learn more about JWT-enabled API keys.

• To create a JWT-enabled API key, follow these instructions.

  IMPORTANT

  Iterable offers various kinds of API keys. Make sure to create a Web API key, since it has access to the endpoints required by the SDK (and no more), and that Require JWT authentication is checked.

# Step 3: Configure your server to generate JWT tokens

When Iterable's web SDK makes API requests, it uses your API key to authenticate. Since the web SDK only supports JWT-enabled API keys, its requests must also include a JWT token specific to the current user. This provides an extra layer of security.

Iterable can't generate these per-user JWT tokens for you. Instead, you need to generate them on your server and make them available to the web SDK via a web service. The web SDK queries a JWT token for the current user and includes it on all requests.

To learn more about how to set up your sever to generate JWT tokens, read JWT-Enabled API Keys.

# Step 4: Configure the SDK

At this point, you have everything you need to set up Iterable's web SDK on your website:

• A website integration in Iterable (with its unique identifier)
• A JWT-enabled API key and its associated secret
• An endpoint from which you can retrieve unique JWT tokens for each of your users

To set up the SDK, update the JavaScript on the page where you'd like to display in-browser messages. Here's a sample implementation:

// Import the axios HTTP library and the SDK methods you'll be calling
import axios from 'axios';
import {
  initialize,
  getInAppMessages
} from '@iterable/web-sdk';

(() => {

  const yourAsyncJWTGeneratorMethod = ({ email }) => {
    // In this method, call your server to fetch a valid JWT token for the current
    // user. Pass along the relevant userId or email, so the server can include
    // use it to generate the token. This method should return the JWT token.
  };

  // If you use userId instead of email, import setUserId instead
  const { setEmail, logout } = initialize(
    process.env.API_KEY || '',
    yourAsyncJWTGeneratorMethod
  );

  const { request, pauseMessageStream, resumeMessageStream, triggerDisplayMessages } = getInAppMessages(
    {
      // Here, configure the SDK. For more information, check out the 
      // web SDK's GitHub repository: https://github.com/iterable/iterable-web-sdk
      count: 20,
      displayInterval: 1000,
      onOpenScreenReaderMessage: '...',
      onOpenNodeToTakeFocus: 'input',
      packageName: '<Unique identifier for your website integration in Iterable>',
      rightOffset: '20px',
      topOffset: '20px',
      bottomOffset: '20px',
      handleLinks: 'external-new-tab',
      closeButton: {
        color: 'black',
        size: '16px',
        topOffset: '20px'
      }
    },
    { display: 'immediate' }
  );

  // Set the email address, and make the request to get the in-app messages 
  // that are available for that user. Display them automatically.
  setEmail('user@example.com').then(() => {
    request()
    .then()
    .catch();
  });

})();

This example includes the closeButton option, which generates an X-style close button near the top of the in-app message (an alternative to adding a close button to the template's content).

For information about closeButton and other configuration options available in the SDK, check out the GitHub repository for Iterable's web SDK.

# Step 5: If necessary, point the SDK to Iterable's EDC

If your Iterable project is hosted on Iterable's European data center (EDC), you'll need to point the SDK to the EDC's API endpoints. For more information, see Iterable's European data center (EDC) in the SDK's GitHub README.

# Next steps

Next up, learn about Sending In-Browser Messages!