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

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, all local data related to the previous user will be deleted
  • 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
  • StorytellerSdk.initialize is asynchronous, so StorytellerSdk.isInitialized() will return true only after initialization completes

Setting the User's Locale#

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

StorytellerSdk.setLocale(locale?: string | null)

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

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

// ISO 639-2 (three-letter code)
StorytellerSdk.setLocale('ace');

// 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:

```typescript
// User logs out - reinitialize with null or a new user's externalId
try {
  await StorytellerSdk.initialize('api-key', null); // Anonymous user
  // or
  await StorytellerSdk.initialize('api-key', 'new-user-guid'); // New logged-in user

  console.log('Switched to new user');
} catch (error) {
  console.error('Failed to switch user:', error);
}
```

Important: Calling initialize with a different externalId will delete all local data associated with the previous user, including:

  • Read status of Clips and Stories
  • Followed categories
  • User preferences
  • Viewed pages history