Skip to content

Working with Users#

User IDs can be used for reporting purposes, storing the read status of Clips and Stories, followed categories and user preferences. By default, the Storyteller SDK creates an externalId for users when the SDK is first initialized. Each time null value is passed to Storyteller.initialize(userInput = null) SDK will handle user management and the default externalId is stored until the user uninstalls the app.

However, if you have a user account system then you may wish to set your own user IDs within the Storyteller SDK. The externalId should be an identifier that is unique per user and does not change. Therefore, using something like the user's email address is not a good choice for an externalId as the user may change it at some point in the future. However, using a unique UUID/GUID would be a good choice as it is guaranteed to not change over time.

Note: Storyteller SDK is not storing any user IDs passed to initialize. We follow VPPA compliance and the user IDs are hashed during the App runtime

Showcase examples#

Setting a User ID#

In order to supply a externalId to the Storyteller SDK, call the following method:

    Storyteller.initialize(
      apiKey = "[APIKEY]",
      useInput = StorytellerUserInput("unique-externalId"),
      onSuccess = {
    // onSuccess action
    },
      onFailure = { error ->
    // onFailure action
    }
  )

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

Current User Information#

You can access the following information about the current user via the following properties:

Storyteller.currentUserId      // Returns the current user id
Storyteller.currentApiKey       // Returns the current api key

Changing Users#

If you use login in your app 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. Note that this will reset the local store of which Pages the user has viewed.

Setting the User's Locale#

In order to set the locale to the Storyteller SDK, call the following method:

  Storyteller.user.setLocale(locale: String?)

Ensure the locale parameter uses an ISO 639-1 two-letter if available, otherwise, use an ISO 639-2 three-letter language code for precise language specification:

    Storyteller.user.setLocale("fr")
    Storyteller.user.setLocale("ace")

To clear or reset the locale settings, simply pass null as the parameter:

    Storyteller.user.setLocale(null)

User Customization#

Custom Attributes#

One of the features of Storyteller is the ability to set custom attributes for requests. These custom attributes can be used to provide additional information about a request, such as the user's location or the device they are using. It can be also used for audience targeting.

How to Use#

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

   Storyteller.user.setCustomAttribute('location', 'New York')

This will add a custom attribute to all requests made by the user, with the key "location" and the value "New York". You can set multiple custom attributes by calling setCustomAttribute() multiple times with different keys and values. Only String values are allowed.

Setting custom attributes should be done after Storyteller SDK is initialized.

To remove custom 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.removeCustomAttribute("location")

Followed Categories#

Storyteller provides a mechanism for managing followed categories associated with clips.

How to Use#

Set followed categories#

To set a followed category, call the addFollowedCategory() function for a singular category or addFollowedCategories() for a collection. Access these methods through the Storyteller.user object. For instance, to designate a followed category attribute for the user, implement the following code:

   Storyteller.user.addFollowedCategory("location")

or

   Storyteller.user.addFollowedCategories(listOf("location", "city", "country"))

These categories are stored locally and used to decide whether the plus or tick icon is displayed in the clips UI.

Setting followable categories attributes should be done after Storyteller SDK is initialized.

Remove followable category#

To remove a followed category, use the removeFollowedCategory() method of the Storyteller.user object. This method requires a single parameter—the key of the followed category to be removed. For example, to remove a followable category related to the user's location, utilize the following code:

   Storyteller.user.removeFollowedCategory("location")

This function accepts a singular string parameter, removing the specified category from the locally stored list.

Storyteller-Managed Following#

The SDK handles following activity internally and automatically syncs with Storyteller's servers. This simplifies integration by removing the need for custom following logic in your app.

This means that all of the above methods on Storyteller.user are no-ops in this mode. Also the categoryFollowActionTaken is not called.

Common methods#

To check if a specific category is being followed, use the isCategoryFollowed() method. To retrieve a list of all currently followed categories, use the getFollowedCategories() method.

val isFollowing: Boolean = Storyteller.user.isCategoryFollowed("location")
val followedCategories: Set<String> = Storyteller.user.followedCategories