Skip to content

Working with Users#

Storyteller personalises content, tracking, and follow state per end user. The Flutter SDK mirrors the native capabilities exposed by the iOS and Android libraries.

Associate a user during initialisation#

Provide an externalId when calling Storyteller.initialize. This identifier usually maps to your own user record.

final result = await Storyteller.initialize(
  'YOUR_API_KEY',
  externalId: currentUser.id,
);

If you also need to configure tracking behavior for privacy compliance, pass eventTrackingOptions during initialization. See Privacy and Tracking for details.

The Showcase StorytellerService.initialize persists the API key and externalId, then reuses them on relaunch—mirror that pattern if you need automatic reconnection.

Update custom attributes#

Use key/value attributes to pass additional segmentation information into Storyteller. Attributes are persisted natively and automatically applied to subsequent sessions.

await Storyteller.setCustomAttribute('subscription-tier', 'gold');
await Storyteller.setCustomAttribute('favorite-team', 'city-fc');

final attributes = await Storyteller.customAttributes();
debugPrint('Current attributes: $attributes');

await Storyteller.removeCustomAttribute('favorite-team');

Toggle personalization controls the same way the Showcase AttributeService._addValue calls setCustomAttribute, setLocale, or addFollowedCategory depending on the attribute type.

Handle locale changes#

If your app allows users to switch language independently from the device, inform Storyteller by overriding the locale:

await Storyteller.setLocale('fr-FR');

Follow categories explicitly#

Manipulate follow state in response to profile changes, onboarding, or saved preferences:

await Storyteller.addFollowedCategories(['travel', 'music']);

final isSportsFollowed = await Storyteller.isCategoryFollowed('sports');
if (!isSportsFollowed) {
  await Storyteller.addFollowedCategory('sports');
}

await Storyteller.removeFollowedCategory('travel');
final followed = await Storyteller.followedCategories();