Skip to content

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. When externalId is omitted or null, the SDK manages a guest identity. With default tracking options, the native SDK persists that guest identity and reuses it on later anonymous initialization. Passing a signed-in user ID selects that user; passing null again returns to the SDK-managed guest identity. Persistence and remote read-state behavior depend on your tracking options.

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.

Initialization#

In order to supply the externalId to the Storyteller SDK, call the initialize method. This method is Promise-based and will throw an error if initialization fails.

try {
  await StorytellerSdk.initialize('api-key', 'user-guid');
  console.log('SDK initialized successfully');
} catch (error) {
  console.error('Initialization failed:', error);
}

StorytellerSdk.initialize(
  {
    apiKey: 'api-key',
    externalId: 'user-guid',
  },
  (callback: { result: Boolean; message: string }) => {
    console.log(`result: ${callback.result} message: ${callback.message}`);
  }
);

Parameters:

  • apiKey (required): Your Storyteller API key
  • externalId (optional): Your unique user identifier. If null or omitted, the SDK will use a default autogenerated externalId

Important Notes:

  • When calling StorytellerSdk.initialize with a different externalId than the previous one, per-user local state is reset (including read markers, likes, follow state and custom attributes under the default tracking configuration)
  • Call StorytellerSdk.initialize as soon as the externalId is known in your app
  • Never make simultaneous StorytellerSdk.initialize calls - this will result in unexpected behavior. Always await the completion of one initialization before calling it again
  • Await the Promise for each initialization attempt. isInitialized() is a status snapshot and is not a completion signal for a subsequent user switch.
  • Apply the new user’s custom attributes, locale and app-managed follows after reinitialization and before reloading or remounting content.

Setting the User's Locale#

You can set the user's locale to localize content within the SDK:

// Signature: setLocale(locale?: string | null): void
StorytellerSdk.setLocale('fr');

Use a supported ISO language code such as fr, rather than a regional tag such as fr-FR. iOS validates against its ISO language-code list and ignores unsupported values. Both platforms accept null or omission to clear the preference:

// ISO 639-1 (two-letter code)
StorytellerSdk.setLocale('fr');

// Clear locale preference
StorytellerSdk.setLocale(null);

Current User Information#

You can access information about the current API configuration:

// Get the current API key
const apiKey: string = StorytellerSdk.currentApiKey();
console.log('Current API key:', apiKey);

// Check if SDK is initialized
const isInitialized: boolean = StorytellerSdk.isInitialized();
console.log('SDK initialized:', isInitialized);

Changing Users#

If your app supports login/logout functionality and you need to switch between users, call initialize again with a new externalId when the user changes:

// On logout, return to the SDK-managed guest identity.
try {
  await StorytellerSdk.initialize('api-key', null);
  // Apply guest attributes, then reload or remount your Storyteller views.
} catch (error) {
  console.error('Failed to switch user:', error);
}

// On a later login, initialize with that user's stable identifier.
// await StorytellerSdk.initialize('api-key', 'new-user-guid');

Important: Under the default tracking configuration, switching identities resets per-user local state, including:

  • Read status of Clips and Stories
  • Followed categories
  • User preferences
  • Custom attributes and locale

Apply the new user’s settings after each switch. This local reset does not delete the user’s account or remotely stored activity.