Skip to content

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. They can also be used for audience targeting, personalization, A/B testing, and analytics segmentation.

How to Use#

Set custom attribute#

To set a custom attribute, you can use the setCustomAttribute() method of the StorytellerSdk 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:

StorytellerSdk.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".

Custom attribute values must be strings. Convert non-string values to strings before setting them.

// String values only
StorytellerSdk.setCustomAttribute("location", "New York");
StorytellerSdk.setCustomAttribute("age", String(25));
StorytellerSdk.setCustomAttribute("isPremium", String(true));

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

Replace custom attributes#

To replace the full custom attribute map, use setCustomAttributes() with string keys and values:

StorytellerSdk.setCustomAttributes({
  location: "New York",
  tier: "premium",
});

Get custom attributes#

To retrieve all custom attributes, you can use the customAttributes() method. This method returns a Promise that resolves to an object containing all custom attributes:

try {
  const attributes = await StorytellerSdk.customAttributes();
  console.log(attributes); // { location: "New York", age: "25", isPremium: "true" }
} catch (error) {
  console.error("Failed to get custom attributes:", error);
}

Remove custom attribute#

To remove a custom attribute, you can use the removeCustomAttribute() method of the StorytellerSdk object. This method takes one parameter: the key of the custom attribute to remove. For example, to remove the custom attribute for the user's location, you can use the following code:

StorytellerSdk.removeCustomAttribute("location");

Best Practices#

  • Timing: Set custom attributes after SDK initialization and before loading any content views
  • Privacy: Ensure custom attributes comply with your privacy policy and relevant regulations (GDPR, CCPA, etc.)
  • Performance: Custom attributes are included with every request, so avoid setting excessive or large values

Followable 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 StorytellerSdk object. For instance, to designate a followed category attribute for the user, implement the following code:

  StorytellerSdk.addFollowedCategory('location')

or

  StorytellerSdk.addFollowedCategories(['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, utilize the removeFollowedCategory() method of the StorytellerSdk 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:

  StorytellerSdk.removeFollowedCategory('location')

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

To remove multiple followed categories at once, use removeFollowedCategories():

StorytellerSdk.removeFollowedCategories(['location', 'city']);

Check if a category is followed#

To check whether a category is currently followed, use isCategoryFollowed():

const isFollowing = StorytellerSdk.isCategoryFollowed('location');

Get followed categories#

To get a list of currently followed categories, utilize the followedCategories() method. This method returns a Promise that resolves to an array of followed category strings:

try {
  const categories = await StorytellerSdk.followedCategories();
  console.log(`Followed categories: ${categories}`);
} catch (error) {
  console.error("Failed to get followed categories:", error);
}

Get followable categories#

To fetch the backend-backed category catalog with current follow state, use getFollowableCategories(). This is useful when building your own category management UI:

import type {
  StorytellerFollowableCategories,
  StorytellerFollowableCategory,
  StorytellerFollowableCategoryPlacement,
} from '@getstoryteller/react-native-storyteller-sdk';

try {
  const { categories }: StorytellerFollowableCategories =
    await StorytellerSdk.getFollowableCategories();
  categories.forEach(category => {
    console.log(category.id, category.displayTitle ?? category.name, category.isFollowed);
  });
} catch (error) {
  console.error("Failed to get followable categories:", error);
}

Each category can include id, name, displayTitle, externalId, type, placement, thumbnailUrl, and isFollowed.

StorytellerFollowableCategory and StorytellerFollowableCategoryPlacement are exported for apps that store or render this metadata. The category string fields are optional because the native iOS and Android models have different nullability guarantees; always use id as the stable required identifier.

Get updates about followed categories#

Followed categories can be updated as a result of user actions from within the Storyteller SDK. You can listen to these event updates through the categoryFollowActionTaken event emitter:

import { useEffect } from 'react';
import StorytellerSdk from '@getstoryteller/react-native-storyteller-sdk';

function MyComponent() {
  useEffect(() => {
    const subscription = StorytellerSdk.categoryFollowActionTaken((event) => {
      console.log('Category:', event.category.name);
      console.log('Is Following:', event.isFollowing);

      // Handle the follow/unfollow action
    });

    return () => {
      subscription.remove();
    };
  }, []);

  return (/* ... */);
}

For more details, see Storyteller Event Handlers.