Skip to content

Working with Users#

User IDs#

By default, if no externalId is specified when first initializing, the Storyteller SDK will assign one to the current user. This ID is stored in the user's browser's local storage and is used to keep track of:

  • which pages a user has read
  • which polls a user has voted in
  • which quizzes a user has answered

This behavior happens out of the box and requires no additional steps other than initializing the SDK:

Storyteller.sharedInstance.initialize(
  '[API-KEY]'
);

Note

You should replace [API-KEY] with your Storyteller SDK API key. Get in touch to request one.

Setting a User ID#

However, if you have a user account system then you may wish to set your own User IDs within the Storyteller SDK.

For example, this would be necessary in a scenario where you want the pages which a user had read to sync across devices as they log out and in from their account.

In order to supply a User ID to the Storyteller SDK, call the initialize method and pass a second parameter as follows:

Storyteller.sharedInstance.initialize(
  '[API_KEY]', {
    externalId: "a-unique-user-id"
  }
);

This method should be called as soon as the value for the externalId is known. For example, this could be on page load or when a user logs in.

Note

User IDs passed on initialization are hashed by the Storyteller SDK in order to follow VPPA compliance.

Changing Users#

If you support user accounts on your site and wish to allow users to logout and log back in as a new user (or proceed as an anonymous user), then when a user logs out you should call initialize again specifying a new externalId. If the user should be anonymous, set the new externalId to null. Note that this will reset the local store of which pages the user has viewed, as well as any user attributes.

Storyteller.sharedInstance.initialize('[API-KEY]', { externalId: 'new-user-id' });

Sample Code for User IDs#

Our Next JS Sample contains sample code showing how to manage User IDs in a simulated login/logout scenario.

Personalization and Targeted Stories#

Storyteller supports the ability to personalize rows and grids based on user attributes as well as the ability to target stories to users based on their attributes.

For more information about these features, please see the documentation about Personalization and Audience Targeting in our User Guide.

Setting User Attributes#

To set a user attribute for a user, you can use the setUserAttribute method of the Storyteller.User object. This method takes two parameters: the key of the user attribute and its value. For example, to set a custom attribute for the user's location, you can use the following code:

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

This will add a user attribute to all requests made by the user, with the key "location" and the value "New York". This can be used to personalize or target stories in the Storyteller CMS.

You can set multiple user attributes by calling setUserAttribute multiple times with different keys and values. Only string values are allowed.

Note

Setting user attributes should be done after the Storyteller SDK is initialized.

Removing User Attributes#

To remove a user attribute, you can use the removeCustomAttribute method of the Storyteller.User object. This method takes one parameter: the key of the custom attribute to remove.

For example, to remove a custom attribute for the user's location, you can use the following code:

Storyteller.User.removeUserAttribute('location');

Note

This method should be called for each attribute you have added when a user logs out.

Updating the Clips locale#

To update the Clips viewer locale, you can use the setLocale method of the Storyteller.User object which takes in the language code as a parameter. For example, to set the locale to Spanish:

Storyteller.User.setLocale('es');

Sample Code for User Attributes#

Our NextJS Sample App contains an example of how to use these User Attributes.