Skip to content

Identify and personalize users#

The SDK keeps a user ID in the browser to remember what each user has read, liked, voted on, and answered. This page shows how to use your own user IDs, change users, set user attributes for personalization, and set the Clips language.

User IDs#

If you don't pass an externalId the first time you call initialize, the SDK creates an anonymous user ID and stores it in the browser's local storage. With the default privacy options, the SDK uses this ID to keep track of:

  • which Pages the user has read
  • which Polls the user has voted in
  • which Quizzes the user has answered
  • which Clips the user has liked or viewed

You don't need extra code for this. Initialize the SDK:

await Storyteller.sharedInstance.initialize('demo-api-key');

Note

Replace demo-api-key with your Storyteller Web SDK API key. To request one, email hello@getstoryteller.com.

Set a user ID#

If your site has user accounts, pass your own user ID as externalId in the second initialize argument:

await Storyteller.sharedInstance.initialize('demo-api-key', {
  externalId: 'your-user-id',
});

With the default privacy options, initialize loads the viewing history that Storyteller saved for this ID: read Pages, Clip likes and views, and Poll and Quiz answers. The history follows the user to every browser and device where they sign in with the same externalId.

Use an ID that is unique to the user and never changes, such as your account ID. Avoid values that can change, such as an email address.

Call initialize as soon as you know the externalId, for example on page load or when a user signs in.

Note

The SDK hashes the externalId before it stores or sends it, to support Video Privacy Protection Act (VPPA) compliance.

Change users#

When a user signs out, or another user signs in, call initialize again with the new externalId. Pass null when the user continues anonymously. A call without externalId keeps the current user ID, so it doesn't sign a user out.

async function onSignIn(userId) {
  await Storyteller.sharedInstance.initialize('demo-api-key', {
    externalId: userId,
  });
}

async function onSignOut() {
  await Storyteller.sharedInstance.initialize('demo-api-key', {
    externalId: null,
  });
}

When the user ID changes, the SDK:

  • clears the stored user attributes
  • clears the read status, likes, and answers of the previous user
  • loads the viewing history that Storyteller saved for the new user ID; with null, the user starts with an empty history

Every initialize call also resets Storyteller.sharedInstance.theme to its defaults. Set the global theme again after the call resolves. A theme set in a view's configuration is kept.

Sample code for user IDs#

The Storyteller Web Showcase's persistUserIdAndReload helper shows how to store, clear, and apply a user ID.

Personalization and targeted Stories#

User attributes let you personalize rows and grids and target Stories to groups of users. For more information, see Personalization and Audience Targeting in the Storyteller User Guide.

Set user attributes#

To set a user attribute, call setUserAttribute on Storyteller.User with the attribute key and its value. For example, to set the user's location:

Storyteller.User.setUserAttribute('location', 'New York');

The SDK adds the attribute, with the key location and the value New York, to its requests to Storyteller. Use it to personalize or target Stories in the Storyteller CMS.

To set more attributes, call setUserAttribute once for each key. Keys and values must be non-empty strings; otherwise the method throws an error. When enablePersonalization is false, the SDK doesn't store attributes.

Note

Set user attributes after initialize resolves. A user change during initialize clears them.

Remove user attributes#

To remove a user attribute, call removeUserAttribute on Storyteller.User with the attribute key. For example, to remove the user's location:

Storyteller.User.removeUserAttribute('location');

Note

When a user signs out and you don't call initialize again, remove each attribute you set.

Update the Clips locale#

To set the language for Clips, call setLocale on Storyteller.User with a language code. For example, to set the language to Spanish:

Storyteller.User.setLocale('es');

The SDK stores the language code as the stLocale user attribute, so it follows the same rules as other user attributes.

Sample code for user attributes#

The Storyteller Web Showcase's persistAndApplyAttributeValues helper shows how to use these user attributes.