Configure the Web SDK

Follow these instructions to set up Iterable's Web SDK for Unknown User Activation. For general guidance about setting up Iterable's Web SDK, see Setting up Iterable's Web SDK and Web SDK GitHub README.

# In this article

# Step 1: Import SDK methods

Import some methods you'll use to set up and use Unknown User Activation:

import {
  initializeWithConfig,
  updateUser,
  updateCart,
  track,
  trackPurchase,
} from "@iterable/web-sdk";

• initializeWithConfig allows you to initialize the SDK, and pass in some configuration options
• updateUser allows you to track user profile updates, either locally (for visitors) or in Iterable (for unknown or known users)
• updateCart allows you to track cart update events, either locally (for visitors) or in Iterable (for unknown or known users)
• track allows you to track custom events, either locally (for visitors) or in Iterable (for unknown or known users)
• trackPurchase allows you to track purchase events, either locally (for visitors) or in Iterable (for unknown or known users)

# Step 2: Initialize the SDK

Call initializeWithConfig to initialize the SDK. Destructure the various methods it returns, so you can call them as needed (clearRefresh, setEmail, setUserID, logout, refreshJwtToken, setVisitorUsageTracked).

const { clearRefresh, setEmail, setUserID, logout, refreshJwtToken, setVisitorUsageTracked } = initializeWithConfig({
  authToken: <YOUR_ITERABLE_WEB_API_KEY>,
  configOptions: {
    enableUnknownActivation: true,
    identityResolution: {
      replayOnVisitorToKnown: true,
      mergeOnUnknownToKnown: true,
    },
    eventThresholdLimit: 100,
    onUnknownUserCreated: (unknownId) => {
      // Tell your server about the unknown userId value, if necessary
    }
  },
  generateJWT: ({ email, userID }) => {
    // From your server, fetch a JWT token for your website's unknown or 
    // known user, and return it as a string. This method receives either userID 
    // or email as a parameter, as necessary.
  }
});

When calling initializeWithConfig, provide a JWT-enabled Web API key for authToken. Then, in configOptions, set the following options:

1. To enable Unknown User Activation, set enableUnknownActivation to true. This property defaults to false.

   NOTE

   The Web SDK uses enableUnknownActivation (without "User" in the name), while the iOS and Android SDKs use enableUnknownUserActivation.

2. If you need to override the default values, provide an identityResolution object. If you don't provide an identityResolution value, the SDK defaults both replayOnVisitorToKnown and mergeOnUnknownToKnown to true. Use this object to specify:

   • replayOnVisitorToKnown – When you identify a visitor by calling setEmail or setUserID, this field specifies whether the SDK should replay locally saved visitor data to their known user profile in Iterable. Defaults to true. (When an unknown user profile is first created, the SDK always replays locally saved data to that profile. This setting only controls what happens when you identify a visitor before they receive an unknown user profile.)

   • mergeOnUnknownToKnown – When you identify an unknown user by calling setEmail or setUserID, this field specifies whether the SDK should merge the unknown user profile with the identified user profile. Defaults to true. (If the identified user profile does not yet exist, a merge operation creates it. When mergeOnUnknownToKnown is false, the new user profile is not created until the SDK tracks a user update or an event. Without a merge, data on the unknown user profile is lost.)

   NOTE

   The Android and Web SDKs use mergeOnUnknownToKnown, while the iOS SDK uses mergeOnUnknownUserToKnown.

3. Specify an eventThresholdLimit to indicate how many of a visitor's most recent events the SDK should save in local storage, so that they can be synced to Iterable when the user satisfies your profile creation criteria and receives an unknown user profile.

   This value defaults to 100. If a visitor triggers more than the maximum number of events before converting to an unknown user, the earliest saved events are deleted first.

4. (Optional, but strongly recommended) Provide an onUnknownUserCreated callback for the SDK to call after it creates a userId for a new unknown user, but before it tries to fetch a JWT token for that user.

   You can use this callback to notify your server about the SDK-generated userId for the new unknown user. This lets your server create JWT tokens for that userId in future JWT requests. To do this, set up an authenticated web service that this callback can call to inform your server about the new unknown userId.

   IMPORTANT

   Since the Web SDK requires JWT-enabled API keys, your JWT server needs to know about SDK-generated unknown userId values before it can issue tokens for them. This callback is the mechanism for that — without it, your JWT server may fail to issue tokens for new unknown users.

The Web SDK refreshes profile creation criteria on each page load. Unlike the iOS and Android SDKs, this article does not document a separate enableForegroundCriteriaFetch configuration option for Web.

5. Provide a generateJWT method to fetch a JWT token (from your server) for the current unknown or known user. Since Iterable's Web SDK requires JWT-enabled API keys, this step is required.

   The method should take the passed-in userID or email and call your JWT server to fetch a valid JWT token for the signed-in user, whether unknown or known. The SDK can then use that JWT token for future API requests.

   • For unknown users, this method always receives a userID parameter (an SDK-generated UUID value).
   • For known users, this method receives either an email or a userID parameter, depending on how you've identified the user to the SDK (by calling setEmail or setUserID).

# Step 3: Get user consent and track local data

Before the SDK tracks local data about the current visitor, get their consent to do so. Then, explicitly tell the SDK to start tracking local data.

// Call after you have user consent to track local data
setVisitorUsageTracked(true);

// Call to revoke user consent, if necessary
setVisitorUsageTracked(false);

// Call to track an update cart event
updateCart(data).then((response) => {
  console.log("Updated cart: ", response);
}).catch((error) => {
  console.error("Error updating cart: ", error);
});

// Call to track a purchase
trackPurchase(data).then((response) => {
  console.log("Tracked purchase: ", response);
}).catch((error) => {
  console.error("Error tracking purchase: ", error);
});

// Call to track a custom event
track(data).then((response) => {
  console.log("Tracked event: ", response);
}).catch((error) => {
  console.error("Error tracking event: ", error);
});

// Call to update user profile data
updateUser(data).then((response) => {
  console.log("Updated user: ", response);
}).catch((error) => {
  console.error("Error updating user: ", error);
});

When you have user consent, call setVisitorUsageTracked(true). When you do this:

• The SDK fetches profile creation criteria for your Iterable project (and refreshes them on each page load).
• For calls to updateCart, trackPurchase, updateUser, and track, the SDK stores data in local storage (this data isn't sent to Iterable yet — it's only stored locally).

If the user revokes consent, call setVisitorUsageTracked(false). This clears any locally saved visitor data, and it prevents local storage of visitor data until setVisitorUsageTracked(true) is called again.

To track events and user updates, call updateCart, trackPurchase, track, and updateUser, wherever needed.

# Step 4: Create an unknown user profile

If and when the website visitor satisfies your Iterable project's profile creation criteria, the SDK creates an unknown user profile for them, as described here.

1. The SDK generates a userId (a UUID) for a new unknown user profile.
2. The SDK calls the consent endpoint and logs the time of consent and user type. It then calls POST /api/unknownuser/events/session to create the unknown user profile in Iterable and adds an unknownSession event on the unknown user profile (which you can use to trigger a system webhook).
3. The SDK calls your onUnknownUserCreated callback, as described above.
4. Calls your generateJWT method, to fetch a JWT token to use for the new unknown userId.
5. The SDK replays locally saved visitor data (cart updates, purchase, user profile updates, and custom events) to the unknown user profile in Iterable, and then removes it from local storage.

# Step 5: Identify the user

When you know the current user's user ID or email (depending on your Iterable project type), identify them to the SDK by calling setUserID or setEmail.

When you identify the user:

// Call to identify the user by userId
setUserID(userId, identityResolutionOverride).then((response) => {
  console.log("Set userId: ", response);
}).catch((error) => {
  console.error("Error setting userId: ", error);
});

// Call to identify the user by email
setEmail(email, identityResolutionOverride).then((response) => {
  console.log("Set email: ", response);
}).catch((error) => {
  console.error("Error setting email: ", error);
});

If the current user is a visitor (a user who doesn't have an unknown profile in Iterable, because they haven't yet satisfied your Iterable project's profile creation criteria):

• If replayOnVisitorToKnown is set to true, the SDK:

  • Calls generateJWT to fetch a JWT token for the known user profile.
  • Sends visitor data from the browser's local storage (user profile data and events) to the known user profile in Iterable. Sending this data to Iterable creates the known user profile in Iterable if it doesn't already exist.
  • Clears visitor data from local storage.
  • Sends future user updates and events to the known user profile to Iterable (not local storage).

• If replayOnVisitorToKnown is set to false, the SDK:

  • Calls generateJWT to fetch a JWT token for the known user profile.
  • Clears visitor data from local storage, without sending it to Iterable.
  • Sends future user updates and events to the known user profile in Iterable (not to local storage). If the known user profile doesn't yet exist in your Iterable project, these updates create it.

If the current user is unknown (has been given an unknown user profile in Iterable):

• If mergeOnUnknownToKnown is set to true, the SDK:

  • Calls generateJWT to fetch a JWT token for the known user profile.
  • Calls the User Merge API to merge the unknown user profile with the known user profile (including all data).
  • If the known profile doesn't yet exist, this API call creates it.
  • Then, the API deletes the unknown profile.
  • It can take a few minutes for all of the data from the unknown user profile to appear on the known user profile.
  • Sends future user updates and events to the known user profile in Iterable (not to the unknown user profile).

• If mergeOnUnknownToKnown is set to false, the SDK:

  • Calls generateJWT to fetch a JWT token for the known user profile.
  • Does not call the User Merge API.
  • Sends future user updates and events to Iterable, to the known user profile (not to the unknown user profile). The unknown user profile remains in Iterable.