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.

Note: StorytellerUserInput(externalId:) is a failable initializer and returns nil if externalId is missing or blank.

Setting the User's Locale#

Use an ISO 639-1 two-letter language code when available, or an ISO 639-2 three-letter language code when needed:

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

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

The SDK lowercases the supplied value and validates it against Locale.isoLanguageCodes. An invalid code is ignored and leaves the previously stored locale unchanged. If your app needs a diagnostic instead of that silent no-op, validate before calling the SDK:

import Foundation
import StorytellerSDK

func applyStorytellerLocale(_ locale: String) {
    let normalizedLocale = locale.lowercased()
    guard Locale.isoLanguageCodes.contains(normalizedLocale) else {
        assertionFailure("Unsupported Storyteller locale: \(locale)")
        return
    }

    Storyteller.shared.user.setLocale(normalizedLocale)
}

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")

The Showcase app demonstrates both the UI for selecting attributes and the SDK calls that apply them: see the personalization UI in AccountView and the attribute wiring in StorytellerService.addValue and StorytellerService.removeValue.

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.

Use setFollowedCategories(_:) when you have the complete list of categories that should be followed and need the SDK's current followed category state to match that list exactly. This method is asynchronous, so you can wait for the SDK to update local followed category IDs and request personalization attributes before reloading Storyteller content.

Storyteller resolves the supplied IDs before applying the replacement. IDs that are not returned by Storyteller are omitted, while the resolved subset is applied successfully. If none of the supplied IDs resolve, the followed category state is cleared. Request or response-decoding failures still throw an error and leave the previous state unchanged.

let clipsView = StorytellerClipsViewController()

Task {
    do {
        try await Storyteller.shared.user.setFollowedCategories(["city", "country"])
        clipsView.reloadData()
    } catch {
        // handle error
    }
}
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.

See the Showcase handling of follow/unfollow callbacks in StorytellerInstanceDelegate.categoryFollowActionTaken.

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 isCategoryFollowed(_:). To retrieve a list of all currently followed categories, read followedCategories.

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

To retrieve the backend-backed list of categories the current user can follow, use Storyteller.shared.user.getFollowableCategories(). This async method returns category metadata plus SDK-derived current followed state for each category, which is useful when building a custom followable category management UI.

Each returned category includes a non-optional id, optional name, displayTitle, externalId, type, thumbnailUrl, and placement, plus SDK-derived isFollowed.

Task {
    do {
        let followableCategories = try await Storyteller.shared.user.getFollowableCategories()

        for category in followableCategories.categories {
            print("\(category.name ?? "Unnamed category"): \(category.isFollowed)")
        }
    } catch {
        // handle error
    }
}

Use Storyteller.shared.user.followedCategories and Storyteller.shared.user.isCategoryFollowed(_:) when you only need the SDK's current local followed category IDs. Use Storyteller.shared.user.getFollowableCategories() when you need renderable category data from Storyteller's backend with isFollowed derived from the SDK's local followed category state.