Skip to content

Working with Users and User customization#

This page describes how to customize Storyteller's behaviour on a per-user basis.

Working with Users#

User IDs can be used for reporting purposes, storing the read status of Clips and Stories, followed categories, user preferences and other features. By default, the Storyteller SDK creates an externalId for users when the SDK is first initialized. externalId is stored until the user uninstalls the app or until the SDK is initialized with a different externalId.

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 not to change over time. The SDK hashes externalId, externalId isn't stored or sent to the server in the raw form.

Setting a User ID#

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

let userInput = StorytellerUserInput(externalId: "user-id")

Task {
    do {
        try await Storyteller.shared.initialize(apiKey: <apiKey>, userInput: userInput)
    } catch {
        // handle error
    }
}

apiKey is a required parameter while userInput is optional and its default value is nil. If userInput is nil, the SDK will use a default autogenerated externalId. When calling Storyteller.shared.initialize, if the new userInput value is different from the previous one, all local data related to the previous user will be deleted.

Storyteller.shared.initialize should be called as soon as the value for the externalId is known in your app. Avoid making simultaneous Storyteller.shared.initialize calls, as it might result in unexpected behavior.

Setting the User's Locale#

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

Storyteller.shared.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.shared.user.setLocale("fr")

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

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

Storyteller.shared.user.setLocale(nil)

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 user data, for example which Pages or Clips the user has viewed.

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 and content personalization. These custom attributes are sent with every request made by the SDK.

How to Use#

Set custom attribute#

To set a custom attribute, you can use the setCustomAttribute() method of the Storyteller.shared.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.shared.user.setCustomAttribute(key: "location", value: "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. String type values are allowed.

Set custom attributes#

To set multiple custom attributes at once, use the setCustomAttributes() method with a dictionary of string keys and values. Note that this replaces all previously stored custom attributes. For example:

Storyteller.shared.user.setCustomAttributes([
    "location": "New York",
    "device_type": "mobile"
])
Remove custom attribute#

To remove custom attribute, you can use the removeCustomAttribute() method of the Storyteller.shared.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.shared.user.removeCustomAttribute(key: "location")

Followed Categories#

Storyteller provides a mechanism for managing followed categories associated with clips. Following or unfollowing a category updates the corresponding plus or tick icon in the Clips UI. The SDK supports two following models, one of which is configured in the System Admin settings for your tenant.

App-Managed Following#

Your app manages following state and handles synchronization with your systems. This gives you full control over the following logic and data storage. When interacting with Storyteller, you have the following methods at your disposal:

Update followed categories#

To add a followed category, a list of them, or to remove a followed category, call one of the below methods by passing the respective category ID(s):

Storyteller.shared.user.addFollowedCategory("location")
Storyteller.shared.user.addFollowedCategories(["location", "city", "country"])
Storyteller.shared.user.removeFollowedCategory("location")
Storyteller.shared.user.removeFollowedCategories(["location", "city"])

When using these methods, the SDK automatically updates the user attributes to reflect the changes in followed categories. This ensures consistency between the followed categories state and user attributes sent with requests.

React to followed categories changes within the SDK#

Whenever a user follows or unfollow a category from within the SDK's UI (e.g. the Clips Player), the SDK triggers the following delegate method on StorytellerDelegate.categoryFollowActionTaken method, which allows the integrating app to synchronize its state/UI.

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.shared.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.

let isFollowing: Bool = Storyteller.shared.user.isCategoryFollowed("location")
let followedCategories: [String] = Storyteller.shared.user.getFollowedCategories()