Control privacy and tracking#

Use Storyteller.sharedInstance.eventTrackingOptions to apply your users' privacy and consent choices. Each option turns off one kind of tracking or storage. Set the options before you call initialize, so the SDK follows them from its first request. You can assign new options at any time, for example when a user changes their consent.

JavaScriptTypeScript

Storyteller.sharedInstance.eventTrackingOptions = {
  disabledFunctionalFeatures: ['all'],
  enableAdTracking: false,
  enableFullVideoAnalytics: false,
  enableFunctionalCookies: false,
  enablePersonalization: false,
  enableRemoteViewingStore: false,
  enableStorytellerTracking: false,
  enableUserActivityTracking: false,
};

import * as Storyteller from '@getstoryteller/storyteller-sdk-javascript';
import {
  StorytellerTrackedFunctionalFeature,
  type StorytellerEventTrackingOptions,
} from '@getstoryteller/storyteller-sdk-javascript';

const eventTrackingOptions: StorytellerEventTrackingOptions = {
  disabledFunctionalFeatures: [StorytellerTrackedFunctionalFeature.all],
  enableAdTracking: false,
  enableFullVideoAnalytics: false,
  enableFunctionalCookies: false,
  enablePersonalization: false,
  enableRemoteViewingStore: false,
  enableStorytellerTracking: false,
  enableUserActivityTracking: false,
};

Storyteller.sharedInstance.eventTrackingOptions = eventTrackingOptions;

By default, disabledFunctionalFeatures is an empty array and every other option is true.

Each assignment replaces all options. An option you leave out returns to its default, so pass every option each time.

Disabled functional features#

disabledFunctionalFeatures accepts an array of the following StorytellerTrackedFunctionalFeature values. In a script tag, pass the string values, for example ['pollVotes']. The StorytellerTrackedFunctionalFeature enum is available only from the npm package.

Item name	Description
`all`	Disables all of the options below.
`clipLikes`	Disables Clip like tracking. If a user likes a Clip, the UI updates, but if they swipe away and come back to that Clip, it appears unliked again.
`clipShares`	Disables Clip share tracking. If a user shares a Clip, the UI updates, but if they swipe away and come back to that Clip, the share count returns to its value before the user shared it.
`clipViewedStatus`	Disables Clip viewed tracking, and all Clips appear as not viewed. The SDK also stops sending the IDs of recently viewed Clips with Clips requests.
`pageReadStatus`	Disables Story read tracking, and all Stories appear as unread.
`pollVotes`	Disables Poll vote tracking. If a user votes in a Poll, the UI updates, but when they go to another Page and come back, they can vote in the Poll again.
`triviaQuizAnswers`	Disables Quiz answer tracking and hides the results Page. If a user answers a Quiz question, the UI updates, but when they go to another Page and come back, they can answer it again.

Ad tracking#

Set enableAdTracking to false to:

stop sending ad events to Storyteller analytics
leave ad events out of the onUserActivityOccurred callback
leave information about the current Story or Clip out of ad requests
leave the publisherProvidedId that your getAdConfig callback returns out of ad requests

The customTargeting values that your getAdConfig callback returns are still sent. Leave them out yourself when a user opts out of ad tracking.

Full video analytics#

When enableFullVideoAnalytics is true, events sent to the onUserActivityOccurred callback include detailed video information, such as Story titles, Clip titles, Story IDs, and Clip IDs.

When it is false, the SDK sets these fields to null for Video Privacy Protection Act (VPPA) compliance:

storyId, storyTitle, storyDisplayTitle
clipId, clipTitle
pageId, pageTitle

This lets you comply with video privacy regulations and still receive engagement events. All other event data, such as user interactions, durations, and event types, is still included.

Functional cookies and local storage items#

Set enableFunctionalCookies to false to:

turn off read status tracking
stop storing user IDs
turn off Storyteller analytics, except the events listed in Storyteller tracking
stop storing non-essential items in local storage, and remove the ones the SDK stored before

The table below lists every item the SDK stores in the browser's local storage. The SDK stores items marked Always stored even when enableFunctionalCookies is false, because it needs them to work. For example, Stories run in iframes, and the Story player and Story Pages share data through these items.

Item name	Description	User data?	Always stored?
`Storyteller.apiKey`	The API key passed to `initialize`.	No	Yes
`Storyteller.captionsEnabled`	The user's caption choice, shared by Stories and Clips.	Yes	No
`Storyteller.clipShares`	Share counts for the Clips loaded on the page, including the user's own shares.	Yes	No
`Storyteller.customInstanceHost`	A custom Storyteller API host, when your integration sets one.	No	Yes
`Storyteller.environment`	The Storyteller API environment that the SDK uses.	No	No
`Storyteller.forceShowShareButton`	A Storyteller testing flag. The SDK sets it to `false` when the user changes.	No	No
`Storyteller.hasShownInstructions`	Whether the user has seen the instructions screen.	Yes	No
`Storyteller.likes`	The Clips the user liked. Stored only when `enableRemoteViewingStore` is `false`.	Yes	No
`Storyteller.pollAnswers`	The user's Poll answers. Stored only when `enableRemoteViewingStore` is `false`.	Yes	No
`Storyteller.polls`	Poll data for the Stories loaded on the page.	No	Yes
`Storyteller.quizAnsweredCorrectlyMap`	The user's Quiz scores, used to show their results.	Yes	Yes
`Storyteller.quizzes`	Quiz data for the Stories loaded on the page.	No	Yes
`Storyteller.readPages`	The Story Pages the user has read. Stored only when `enableRemoteViewingStore` is `false`.	Yes	No
`Storyteller.recentStoryPlaybackMode`	The analytics `storyPlaybackMode` value for each recently opened Story.	Yes	No
`Storyteller.settings`	Your tenant settings for the API key.	No	Yes
`Storyteller.triviaQuizAnswers`	The user's Quiz answers. Stored only when `enableRemoteViewingStore` is `false`.	Yes	No
`Storyteller.user`	The hashed user ID. The SDK creates an anonymous ID or hashes the `externalId` passed to `initialize`. Not stored when `enableRemoteViewingStore` is `false`.	Yes	No
`Storyteller.userAttributesStorage`	The user attributes set with `setUserAttribute` and `setLocale`.	Yes	No
`Storyteller.viewedClips`	The Clips the user has viewed. Stored only when `enableRemoteViewingStore` is `false`.	Yes	No

Versions before 10.11.0 stored an unhashed user ID in Storyteller.userId. The SDK removes that item when it saves Storyteller.user.

Keys renamed in 11.0#

Version 11.0 renamed the items that hold viewing history. The SDK doesn't read the old items and doesn't remove them, even when enableFunctionalCookies is false. If your consent manager or cleanup script lists Storyteller items, add the new names. Remove the old items yourself if your consent policy requires it.

Version 10.13 item	Version 11.0 item
`Storyteller.clipLikes`	`Storyteller.likes`
`Storyteller.clipsViewed`	`Storyteller.viewedClips`
`Storyteller.pollAnswerMap`	`Storyteller.pollAnswers`
`Storyteller.quizAnswerMap`	`Storyteller.triviaQuizAnswers`
`Storyteller.storiesReadMap`	`Storyteller.readPages`

See Local storage keys changed in the migration guide.

User personalization#

By default, the SDK includes user attributes and the user ID in requests to Storyteller, so Storyteller can personalize the content it returns. Set enablePersonalization to false to turn off personalization. The SDK then removes the stored user attributes and doesn't store new ones. Viewing history still loads, because it follows the remote viewing store option.

The Storyteller Web Showcase's persistAndApplyAttributeValues helper shows how to store user attributes and apply them before they affect personalization.

Warning

Personalization is always off when enableFunctionalCookies is false, because the SDK doesn't store user IDs.

Remote viewing store#

When enableRemoteViewingStore is true (the default), Storyteller keeps the user's viewing history: read Pages, Clip likes and views, and Poll and Quiz answers. initialize loads the history for the current user ID, and the SDK doesn't keep it in local storage. See Identify and personalize users.

Loading the history also needs enableFunctionalCookies. If it is false while this option is true, the SDK doesn't load the history, and it keeps the user's viewing state in memory only until the page reloads. The history request does not depend on enablePersonalization, and it never includes user attributes.

When enableRemoteViewingStore is false, the SDK never stores user IDs or sends them to Storyteller, and it keeps all viewing activity in local storage on the device. This privacy-enhanced mode is designed to address Video Privacy Protection Act (VPPA) compliance concerns.

Storyteller tracking#

By default, the SDK records analytics events on Storyteller's servers. Set enableStorytellerTracking to false to turn off Storyteller analytics. The SDK still sends a few events that it needs to work, but Storyteller doesn't store them: openedPage, votedPoll, triviaQuizQuestionAnswered, openedClip, likedClip, and unlikedClip. The SDK doesn't send one of these events when you disable the matching functional feature, for example votedPoll when pollVotes is disabled.

When Storyteller analytics are on, initialize also sends an sdkInitialized event. It includes the page origin and path, the browser viewport size, device and operating system details, and the tracking options.

Warning

Storyteller tracking is always off when enableFunctionalCookies is false. The SDK still sends the events listed above, without a user ID.

User Activity tracking#

Set enableUserActivityTracking to false to stop calls to the onUserActivityOccurred callback. Your site uses this callback to record Storyteller events in its own analytics. See Integrate analytics.

A view's optional context value returns through this client callback when user activity tracking is enabled. The SDK excludes it from Storyteller analytics API requests. Your application owns the value and any transfer to another analytics provider. Keep credentials and personal data out of this field.