Use the Storyteller Web SDK to show Stories and Clips on your website. These guides are for web developers: install the SDK, show your first Story row, then add the views and integrations you need.
Show your first Story row Next step: initialize the SDK and show a row of Stories on your page.
StoriesShow Story tiles in a row or grid. Selecting a tile opens the Story player.
Add a Story row Add a Story grid ClipsShow Clip tiles in a row or grid, or play Clips in a player on your page.
Add a Clips row Add a Clips player to a page"},{"location":"#st-install","title":"Install the SDK","text":"Install with a script tag Load a fixed SDK version from the Storyteller CDN. No build step. Install from npm Import the package and its stylesheet in a bundled app. Use React or Next.js Initialize the SDK in the browser and destroy views on unmount.Before you install, check what you need. Code examples link to the private Storyteller Web Showcase: get access to the Showcase source.
"},{"location":"#st-content","title":"Choose what to show","text":"Choose a view"},{"location":"#st-keep-building","title":"More guides","text":"Appearance and contentThemes, views, users, and privacyThe Storyteller Web SDK docs are also published as plain-text files for AI coding assistants, such as GitHub Copilot, Claude, Codex, ChatGPT, and Cursor. Give your assistant these files so that its answers use the Web SDK API as documented.
"},{"location":"AI/#why-use-ai-assistants-with-documentation","title":"Why use the docs with an AI assistant","text":"An assistant that has the Storyteller docs in context can:
Check important answers against the docs pages.
"},{"location":"AI/#copy-one-page","title":"Copy one page","text":"Every page except the documentation home has a Copy for AI button next to its title. The button copies the page's AI file: a summary of the page, followed by the full page in Markdown. Paste it into your assistant's chat. On this page, the button copies the whole bundle described in the next section.
The button's menu also has Copy as Markdown, which copies only the page's Markdown.
"},{"location":"AI/#adding-documentation-to-your-editor","title":"Add the whole bundle to your project","text":"Download the documentation bundle from https://docs.getstoryteller.com/web/ai/llms.txt. It contains a summary of every page in navigation order. Each summary starts with a <PAGE: slug> marker.
To use the bundle in your project:
.ai/ directory in your project..ai/storyteller-web-sdk-docs.md.In an editor assistant, such as Cursor, Zed, or GitHub Copilot, attach or reference the saved file in the chat. In a web-based assistant, upload the file, or paste its contents at the start of a new chat. Long pastes may be truncated.
"},{"location":"AI/#when-to-use-per-page-files","title":"Use per-page files","text":"When you need one topic, give your assistant that page's file. It contains the page summary and the full page. Each page's file is at:
https://docs.getstoryteller.com/web/ai/llms-<slug>.txt\nThe <slug> is the same slug as in the bundle's <PAGE: slug> marker. To work it out from a page's URL, take the path after https://docs.getstoryteller.com/web/ and remove the trailing slash. Replace each / with -, add a hyphen before each capital letter inside a word, and use lowercase letters. For a section overview page whose URL ends in a folder name, add -index.
Themes/ themes llms-themes.txt StorytellerRowView/ storyteller-row-view llms-storyteller-row-view.txt getting-started/npm/ getting-started-npm llms-getting-started-npm.txt getting-started/ getting-started-index llms-getting-started-index.txt"},{"location":"AI/#release-notes","title":"Release notes","text":"The bundle doesn't include the release notes. Download them separately from https://docs.getstoryteller.com/web/ai/llms-changelog.txt, or copy them from the Release notes page.
An assistant that can fetch URLs can use the docs search index to find the right page: https://docs.getstoryteller.com/web/search/search_index.json. It lists the title, location, and text of each page and section. Check important answers against the pages it finds.
StorytellerStoriesRowView integration and how to reload its data.\"UiTheme with our brand colors for light and dark mode.\"getAdConfig for Google Ad Manager with Story and Clip Category targeting.\"This page lists the properties and methods of Storyteller.sharedInstance, the SDK object you initialize and use to open players, count content, and read SDK state. For methods on a view, such as reloadData and destroy, see Configure views. The API reference lists every public member, including theme, currentTheme, currentApiKey, and customInstanceHost.
Examples that use await must run inside an async function or a JavaScript module.
Storyteller.sharedInstance.delegate = {\n // Your callbacks here\n};\nLearn more
To set the global delegate, see Handle global callbacks.
"},{"location":"AdditionalMethods/#instance-properties","title":"Instance properties","text":""},{"location":"AdditionalMethods/#isinitialized","title":"isInitialized","text":"readonly isInitialized: boolean\ntrue after an initialize call succeeds.
const initialized = Storyteller.sharedInstance.isInitialized;\nreadonly isPlayerVisible: boolean\ntrue while a Story or Clips player is open, and false after it is dismissed.
const isStoryPlayerVisible = Storyteller.sharedInstance.isPlayerVisible;\nversion: string\nThe SDK version.
const storytellerVersion = Storyteller.sharedInstance.version;\neventTrackingOptions","text":"The privacy and tracking options. Each assignment replaces every option: options you leave out return to their defaults. See Control privacy and tracking.
"},{"location":"AdditionalMethods/#instance-methods","title":"Instance methods","text":""},{"location":"AdditionalMethods/#initialize","title":"initialize","text":"initialize(apiKey: string, userInput?: { externalId?: string | null }): Promise<void>\nInitializes the SDK with your API key and, optionally, your ID for the current user. Call it before you use other methods, and wait for the promise.
apiKey: your Storyteller API keyuserInput.externalId: your ID for the signed-in user, or null for an anonymous user. See Setting a user ID.try {\n await Storyteller.sharedInstance.initialize('demo-api-key', {\n externalId: 'your-user-id',\n });\n} catch (error) {\n console.error('Storyteller could not initialize.', error);\n}\nexternalId made while an earlier call is still running share that call's promise. React Strict Mode's repeated effects therefore initialize the SDK once.initialize also loads the user's viewing history from Storyteller, and rejects if that request fails.Storyteller.sharedInstance.theme to its defaults. Set the global theme after the promise resolves.Error whose message starts with the error type, such as InvalidApiKeyError, NetworkError, or NetworkTimeoutError. A call with no API key rejects with a string. See Handle initialization errors.dismissPlayer(animated: boolean): void\nCloses the open Story or Clips player. If no player is open, it does nothing. It doesn't close a StorytellerEmbeddedClipsPlayerView.
animated: true plays the close animation.Storyteller.sharedInstance.dismissPlayer(true);\ndisablePlayback(): void\nPauses the open Story player and the current Clip in every Clips player on the page. Stories and Clips that open while playback is disabled stay paused until you call enablePlayback. Use it when your page shows something over Storyteller content, such as your own video or a dialog.
Storyteller.sharedInstance.disablePlayback();\nenablePlayback(): void\nAllows playback again after disablePlayback, and resumes the open Story and the current Clip. Playback is enabled by default.
Storyteller.sharedInstance.enablePlayback();\nenableLogging(): void\nTurns on the SDK's info, warning, and log messages in the browser console. The SDK always logs errors. Use it for debugging and monitoring, and call it before initialize to see initialization logs.
Storyteller.sharedInstance.enableLogging();\nThe Storyteller Web Showcase turns on logging in its debug mode with this enableLogging call.
getStoriesCount(categoryIds: string[]): Promise<number>\nReturns the total number of available Stories in the given Category IDs. The SDK sends one small count request for each Category and adds the results. An empty array returns 0 without a request.
The SDK sends the count requests only after initialize succeeds. A count call made before or during initialization waits for it. If initialization never starts or fails, the promise stays pending until a later initialize call succeeds. A failed count request rejects the promise.
Use the count method for an optional row that should appear only when it has content. Load a primary row directly, without a count, to avoid an extra request.
await Storyteller.sharedInstance.initialize('demo-api-key');\n\nconst count = await Storyteller.sharedInstance.getStoriesCount(['category-id']);\n\nif (count > 0) {\n // Show the row only when the Category has Stories\n new Storyteller.StorytellerStoriesRowView('stories-row-id', ['category-id']);\n}\ngetClipsCount(collectionId: string): Promise<number>\nReturns the number of available Clips in the collection. It waits for initialization and handles errors in the same way as getStoriesCount. Use it before you create an optional Clips view.
const clipsCount = await Storyteller.sharedInstance.getClipsCount('collection-id');\nopenStory(id: string): Promise<void>\nOpens the Story with this ID. The promise rejects if the SDK can't open the Story, for example because it can't be found. See Open a player programmatically.
await Storyteller.sharedInstance.openStory('story-id');\nopenStoryByExternalId(externalId: string): Promise<void>\nOpens the Story with this external ID. The promise rejects if the SDK can't open the Story, for example because it can't be found.
await Storyteller.sharedInstance.openStoryByExternalId('story-external-id');\nopenPage(pageId: string): Promise<void>\nOpens the Story that contains this Page, starting at the Page. The promise rejects if the SDK can't open the Page, for example because it can't be found.
await Storyteller.sharedInstance.openPage('page-id');\nopenCategory(categoryId: string, storyId?: string): Promise<void>\nOpens the Story player for the Category, at the Story with the ID storyId. If you leave out storyId, or it isn't in the Category, the first Story in the Category opens. The promise rejects if the SDK can't open the Category, for example because it can't be found.
await Storyteller.sharedInstance.openCategory('category-id', 'story-id');\nopenCollection(\n collectionId: string,\n destination?: { categoryId?: string; clipId?: string },\n openedReason?: OpenedReason.deepLink\n): Promise<void>\nOpens the Clips player for the collection. It accepts the following parameters:
collectionId: the ID of the collection to open.destination: the clipId or categoryId to show when the collection opens. If you leave it out, or the Clip or Category isn't in the collection, the first Clip in the collection opens.openedReason: the reason reported in analytics events. It accepts only Storyteller.OpenedReason.deepLink: pass it when the user arrived through a deep link. If you leave it out, the SDK sets the reason.The promise rejects if the SDK can't open the collection, for example because it can't be found.
await Storyteller.sharedInstance.openCollection(\n 'collection-id',\n { clipId: 'clip-id' },\n Storyteller.OpenedReason.deepLink\n);\nopenClipByExternalId(collectionId: string, externalId: string): Promise<void>\nOpens the Clips player for the collection, at the Clip with this external ID. The promise rejects if the SDK can't open the Clip, for example because the collection has no Clip with that external ID.
await Storyteller.sharedInstance.openClipByExternalId(\n 'collection-id',\n 'clip-external-id'\n);\nThese members still work in version 11, but don't use them in new code:
Member Use insteadopenClip(id, onError?) openCollection or openClipByExternalId enableEventTracking() eventTrackingOptions disableEventTracking() eventTrackingOptions currentUserId None. It always returns an empty string."},{"location":"Ads/","title":"Integrate ads","text":"Storyteller can show ads in Stories and Clips from two sources:
getAdConfig callback to tell the SDK which ad unit to request and which targeting to send.Storyteller sets which ad source your tenant uses. To change it, contact the Storyteller Delivery Team.
"},{"location":"Ads/#storyteller-first-party-ads","title":"Storyteller First Party Ads","text":"If your tenant uses Storyteller First Party Ads, you manage them in the Storyteller CMS and don't change your integration code. The SDK loads and shows these ads itself.
"},{"location":"Ads/#storyteller-ad-manager-integration","title":"Google Ad Manager integration","text":"The SDK requests these ads from Google Ad Manager. For other ad servers, contact the Storyteller Delivery Team.
Implement the getAdConfig callback on the global delegate (IStorytellerDelegate, see StorytellerDelegate). The SDK calls it each time it needs an ad, and only when your tenant uses Google Ad Manager ads.
Assigning Storyteller.sharedInstance.delegate replaces every global callback. The samples below spread the current delegate to keep your other callbacks.
Storyteller.sharedInstance.delegate = {\n ...Storyteller.sharedInstance.delegate,\n getAdConfig: (adRequestInfo) => {\n // Only Story ad requests have `story`. Clips ad requests have `clip`.\n const customTargeting = adRequestInfo.story\n ? {\n storytellerStoryCategories: adRequestInfo.story.categories.map(({ name }) => name),\n }\n : {\n storytellerClipCategories: adRequestInfo.clip.categories.map(({ name }) => name),\n storytellerNextClipCategories:\n adRequestInfo.nextClip?.categories.map(({ name }) => name) || [],\n };\n\n return {\n slot: '/30497361/your_ad_unit',\n publisherProvidedId: 'your-publisher-provided-id',\n customTargeting,\n };\n },\n};\nimport * as Storyteller from '@getstoryteller/storyteller-sdk-javascript';\nimport type {\n StorytellerAdRequestInfo,\n StorytellerStoriesAdRequestInfo,\n} from '@getstoryteller/storyteller-sdk-javascript';\n\nfunction isStoryAd(\n adRequestInfo: StorytellerAdRequestInfo\n): adRequestInfo is StorytellerStoriesAdRequestInfo {\n return 'story' in adRequestInfo;\n}\n\nStoryteller.sharedInstance.delegate = {\n ...Storyteller.sharedInstance.delegate,\n getAdConfig: (adRequestInfo) => {\n const customTargeting: Record<string, string[]> = isStoryAd(adRequestInfo)\n ? {\n storytellerStoryCategories: adRequestInfo.story.categories.map(({ name }) => name),\n }\n : {\n storytellerClipCategories: adRequestInfo.clip.categories.map(({ name }) => name),\n storytellerNextClipCategories:\n adRequestInfo.nextClip?.categories.map(({ name }) => name) || [],\n };\n\n return {\n slot: '/30497361/your_ad_unit',\n publisherProvidedId: 'your-publisher-provided-id',\n customTargeting,\n };\n },\n};\nThe Storyteller Web Showcase builds the getAdConfig result in buildAdConfig with the ad slot and custom targeting values.
getAdConfig returns an object with the fields below, or null to request no ad. An object without slot also requests no ad. Return the object directly: the SDK doesn't wait for a promise. For the full type, see getAdConfig in the callback reference.
slot Required. The ID of your GAM ad unit, in the form /[NETWORK_CODE]/[UNIT_CODE]. The ad unit must serve 1x1 ads. For details, see Google's guides to custom ad creative and programmatic ad creative. publisherProvidedId Optional Publisher Provided ID (PPID) for Google Ad Manager. This value is sent as GAM's PPID field, not as a custom targeting KVP. The SDK trims whitespace, omits empty values, and omits this value when ad tracking is disabled. customTargeting Optional key-value pairs (KVPs) that the SDK sends to GAM for ad targeting. The SDK adds the default targeting values, and a key you return replaces the default key with the same name. The SDK doesn't copy KVPs that the rest of your page sets. Values such as ddid, isLoggedIn, gdpr, us_privacy, gpp, gpp_sid, and other app-owned ad/privacy KVPs should be supplied through customTargeting. PPID should be supplied through publisherProvidedId.
customTargeting values can be strings or arrays of strings. Use arrays for multi-value GAM KVPs so each value is passed as a distinct targeting value.
When ad tracking is off (enableAdTracking: false), the SDK omits the default targeting and publisherProvidedId. It still sends the customTargeting you return.
By default, the Storyteller SDK sets the following customTargeting values:
stCurrentCategory string The external ID of the current Story Category. \"top-stories\" stPlacement string The placement code of the current Story Category. web-top-stories stCategories string[] External IDs of the current Story Categories. [\"top-stories\", \"web-stories\"]"},{"location":"Ads/#clips-default-targeting","title":"Clips","text":"Property Name Property Type Description Example value stCollection string The ID of the current Clip Collection. live-clips stClipCategories string[] External IDs of the current Clip Categories. [\"top-clips\", \"web-clips\"] stNextClipCategories string[] External IDs of the next Clip Categories. [\"top-clips\", \"web-clips\"]"},{"location":"Ads/#adrequestinfo","title":"AdRequestInfo","text":"The StorytellerAdRequestInfo object passed to this callback can be one of two types, depending on whether the user is viewing Stories or Clips:
export type StorytellerStoriesAdRequestInfo = {\n placement: string;\n categories: string[];\n story: {\n categories: CategoryDetail[];\n };\n};\n\nexport type StorytellerClipsAdRequestInfo = {\n collection: string;\n clip: {\n categories: ClipCategory[];\n };\n nextClip?: {\n categories: ClipCategory[];\n };\n};\nThis object contains details about the Story or Clip the user is viewing. Pass them to your ad server to target the ad. Only Story ad requests have story, so check for it before you read it, as the samples above do.
Story ad requests contain:
Property Descriptionplacement: string A string which uniquely identifies the placement in which the Story is being shown categories: string[] A list of Category String IDs which have been assigned to the Stories list. Note that every Category in this list will appear on every Story in the list. This list can be useful to know in which context the user is currently viewing Stories. story: ItemInfo Metadata about the Story after which the requested Ad will be placed The ItemInfo object has the following properties:
categories: CategoryDetail[] An array of Categories which have been assigned to the Story The CategoryDetail object has the following properties:
name: string A human readable name for the Category externalId: string The external ID of the Category, set in the Storyteller CMS"},{"location":"Ads/#clips-adrequestinfo","title":"Clips","text":"Clips ad requests contain:
Property Descriptioncollection: string A string which uniquely identifies the Collection that the Clips are assigned to clip: ItemInfo Metadata about the Clip after which the requested Ad will be placed nextClip: ItemInfo Optional. Metadata about the Clip that follows the Ad, when there is one The ItemInfo object has the following properties:
categories: ClipCategory[] An array of Categories which have been assigned to the Clip. The ClipCategory object has the following properties:
name: string A human readable name for the Category externalId: string The string ID for the Category"},{"location":"Analytics/","title":"Integrate analytics","text":"The SDK reports what users do in Stories, Clips, Polls, Quizzes, and ads through the onUserActivityOccurred callback. This page shows how to receive these events and forward them to your analytics tool, what the startup event contains, and how to add placement context. The event pages list every event and its fields.
Add an onUserActivityOccurred callback to Storyteller.sharedInstance.delegate before you call initialize, so you also receive the startup event. The callback receives the event type and an object with the event's fields.
Storyteller.sharedInstance.delegate = {\n onUserActivityOccurred: (type, data) => {\n analytics.track(type, data);\n },\n};\n\nawait Storyteller.sharedInstance.initialize('demo-api-key');\nReplace analytics.track with the call your analytics tool uses. To handle one event type, compare type with a Storyteller.ActivityType value, for example Storyteller.ActivityType.openedStory. In TypeScript, the delegate type is IStorytellerDelegate.
Assigning Storyteller.sharedInstance.delegate replaces all four global callbacks: onUserActivityOccurred, onShareButtonTapped, getAdConfig, and userNavigatedToApp. Define all your callbacks in one object, or spread the current delegate:
Storyteller.sharedInstance.delegate = {\n ...Storyteller.sharedInstance.delegate,\n onUserActivityOccurred: (type, data) => {\n analytics.track(type, data);\n },\n};\nThe SDK calls onUserActivityOccurred only when enableUserActivityTracking is true, which is the default. Ad events also need enableAdTracking. When enableFullVideoAnalytics is false, content IDs and titles are null. See Control privacy and tracking for these options.
The Storyteller Web Showcase handles these events in onUserActivityOccurred. Handle global callbacks describes the other callbacks on the delegate.
The SDK sends these kinds of events:
Each event page lists:
The SDK sends sdkInitialized (Storyteller.ActivityType.sdkInitialized) when an initialize call gets the result of the settings request for your tenant:
initializationSucceeded is true when the settings load. Later initialize calls after a successful one don't send the event again.initializationSucceeded is false when the settings request fails. The initialize promise then rejects.initialize rejects without sending sdkInitialized when the API key is missing, when the SDK can't save the user ID, or when the request for the user's viewing history fails. With the default privacy options, the SDK waits for the viewing history before the settings, so an invalid API key or a network outage usually fails that request first. Handle startup failures in the catch block of initialize, not with this event.
Set the delegate before you call initialize to receive this event.
Storyteller.sharedInstance.delegate = {\n onUserActivityOccurred: (type, data) => {\n if (type === Storyteller.ActivityType.sdkInitialized) {\n console.log(data.initializationSucceeded);\n }\n },\n};\nThe event contains the following properties:
Property ValueinitializationSucceeded true or false. enableAdTracking, enableFullVideoAnalytics, enablePersonalization, enableRemoteViewingStore, enableStorytellerTracking, enableUserActivityTracking The tracking options in effect. enablePersonalization and enableStorytellerTracking are false when enableFunctionalCookies is false. The event doesn't include enableFunctionalCookies or disabledFunctionalFeatures. appId The page origin and path, for example https://www.example.com/news, without the query string or hash. null during server rendering. deviceType Phone, Tablet, TV, or Desktop. deviceBrand, deviceModel Detected from the browser's user agent. 'none' when unknown. operatingSystem, osVersion Detected from the browser's user agent. 'none' when unknown. screenResolution The browser viewport size as <width>x<height> in CSS pixels. null during server rendering. The callback runs when enableUserActivityTracking is enabled. Storyteller server delivery also follows enableFunctionalCookies and enableStorytellerTracking. See Control privacy and tracking for these settings.
Use context to record where on your site an event came from, such as the page and module. context?: unknown contains host-defined attribution data. The SDK does not prescribe its shape. It returns the configured value in UserActivityData.context for events that it can attribute to the view and to content opened from that view.
You can provide context through the configuration for:
StorytellerStoriesRowViewStorytellerStoriesGridViewStorytellerClipsRowViewStorytellerClipsGridViewStorytellerClipsPlayerViewStorytellerEmbeddedClipsPlayerViewconst storiesRow = new Storyteller.StorytellerStoriesRowView('stories-row');\nconst analyticsContext = {\n location: 'home',\n module: 'top-stories',\n sortOrder: 10,\n};\n\nstoriesRow.configuration = {\n context: analyticsContext,\n};\n\nStoryteller.sharedInstance.delegate = {\n onUserActivityOccurred: (type, data) => {\n console.log(type, data.context);\n },\n};\nYou can replace the value while the view is mounted. Reassign the configuration object with the new value:
storiesRow.configuration = {\n context: {\n location: 'sports',\n module: 'latest-stories',\n },\n};\nThe callback is delivered only when enableUserActivityTracking is enabled. It omits context when the configured value is undefined. Explicit values such as null, false, 0, and an empty string remain in the callback.
If a Story or Clip opens related content from an SDK action, the related player events keep the source placement context. This applies to child Stories, Story categories, Clips, and Clip collections. A direct hash URL or deep link has no source placement, so the SDK uses the destination view's configured context or omits the field.
The SDK returns context only to the delegate in the same browser client. It does not add context to Storyteller analytics API requests. Your application owns the value, its storage, and its transfer to any analytics provider. Keep credentials and personal data out of this field.
"},{"location":"Analytics/#event-data","title":"Event data","text":""},{"location":"Analytics/#openedreason","title":"OpenedReason","text":"The action which the user took to open the Story:
Value DescriptionstoryListTap The user tapped the Story in the list deepLink The user navigated directly to a Story URL swipe The user swiped left or right to change the Story automaticPlayback The previous Page finished, and the player moved on to the next one tap The user tapped to navigate or Clip:
Value DescriptionclipListTap The user tapped the Clip in the list categoryListTap The user tapped a Clip Category label categoryBackTap The user tapped the back button in a Clip Category deepLink The user navigated directly to a Clip URL swipe The user swiped to the next or previous Clip"},{"location":"Analytics/#dismissedreason","title":"DismissedReason","text":"The reason the Story or Clip was dismissed:
Value DescriptionbackgroundTapped The user tapped the background to dismiss the Story (on desktop) closeButtonTapped The user tapped close to dismiss the Story swipedDown The user swiped down to dismiss the Story swipedFinalStory The user swiped the final Story to dismiss it swipedFirstStory The user swiped the first Story to dismiss it skippedFinalPage The user tapped to skip the final Page of the final Story backTapped The user tapped the browser back button to dismiss the Story view backButtonTapped The user tapped the back button to dismiss the Clips player completedFinalPage The user completed the final Page of the final Story instanceMethod The player was dismissed programmatically using the dismissPlayer method escapeKeyPressed The user pressed the Esc key to dismiss the Story windowUnload The user navigated away by closing the page or entering a new URL in the browser bar"},{"location":"Changelog/","title":"Changelog","text":"Links in these release notes go to the current guides, which describe the latest version.
"},{"location":"Changelog/#1101-20260930","title":"11.0.1 - 2026.09.30","text":""},{"location":"Changelog/#bug-fixes","title":"Bug Fixes","text":"openedStory as it opens. Since 10.13.13, the event could arrive only when the player closed, or not at all. The first openedPage after a row tap reports storyListTap again.Version 11.0.0 changes where the SDK keeps viewing history, how the script build loads its code, and how the npm package declares its files and dependencies. Read Migrate from version 10 to 11 before you update.
"},{"location":"Changelog/#breaking-changes","title":"Breaking Changes","text":"initialize loads the user's read Pages, Clip likes and views, and Poll and Quiz answers, and waits for them. History for an externalId follows the user across browsers and devices. Read state that 10.13 recorded carries over with the default privacy options. See Remote viewing store.initialize rejects with InvalidApiKeyError, NetworkError, or NetworkTimeoutError when the viewing-history request fails. No sdkInitialized event is sent in that case. See Handle initialization errors.Storyteller.likes, Storyteller.viewedClips, Storyteller.pollAnswers, Storyteller.triviaQuizAnswers, and Storyteller.readPages replace Storyteller.clipLikes, Storyteller.clipsViewed, Storyteller.pollAnswerMap, Storyteller.quizAnswerMap, and Storyteller.storiesReadMap. The SDK does not read or remove the earlier keys. With enableRemoteViewingStore: false, history saved by 10.13 does not carry over. See local storage items.storyteller.min.js. If you host the SDK files yourself, deploy every file in the version's dist directory and keep the file names. Your Content Security Policy must allow scripts from that directory. See Host the SDK files.@types/react (>=17 <20) and @types/react-router-dom (^5.1.7) as peer dependencies, because its TypeScript declarations import them. npm 7 and later installs them. See TypeScript declarations.import and require entry points and publishes its declarations at dist/index.npm.d.ts. It no longer ships index.js, types/*.d.ts, or SDK source files. Import only the package root and dist/storyteller.min.css.reflect-metadata polyfill on the page's global Reflect object. If your code uses Reflect.getMetadata, import reflect-metadata in your application.ActivityType has a new sdkInitialized member. Update exhaustive switch statements over ActivityType.Story has new pinnedChipText and customLiveChipText properties for custom chip text. Update typed test data.QuizRenderer.clearQuizData() method.destroy() to every view. Call it before your application removes or replaces the view's container.sdkInitialized activity event. onUserActivityOccurred receives it when enableUserActivityTracking is on. initializationSucceeded is true when Settings load and false when the Settings request fails. Other startup failures reject initialize without this event.onDataLoadComplete reports only the first page.liveChip theme for round and rectangular tiles adds unreadBackgroundGradient, readBorderColor, and unreadBorderColor. See Story tile chips.clipsActionButtonCompactSize, the buttons change when you update.showLikeCount and showShareCount. If your remote theme already sets them, the counts change when you update.categoryDetails. Clip events already included it, and Clip ad events have no Category fields. See the Story, Poll, Quiz, and Ad events.initialize calls with the same API key and externalId, made while an earlier call is still running, share its startup work.20260925.1. The Story ad, Story swipe, and next Story button fixes below come from this update.#171A25 background. In 10.13 they were 18 px text, a 22 px line height, and a #000000 background.playAllStories is off, the Story player moves from read pinned or Live Stories to the next unread Story instead of closing.history.replaceState error.externalId.StorytellerEmbeddedClipsPlayerView no longer locks page scrolling when it first renders.openedStory as it opens. Since 10.13.13, the event could arrive only when the player closed, or not at all. The first openedPage after a row tap reports storyListTap again.configuration.context to the onUserActivityOccurred callback data. The selected view supplies the context when views share a player and when an SDK action opens related content. Context changes apply while a view remains mounted. The value stays outside Storyteller activity API requests.getStoriesCount and getClipsCount methods to the shared SDK instance. Integrations can check for content before they create an optional list view.playerStories, which restarted the player and re-showed the active Story on its read-state initial page (the page after the one on screen). The same re-run also switched the swiped-to Story to single-Story playback mode, reset its view start time, and registered a duplicate read-state listener on every refresh. Story switches now leave the running player alone and a refreshed Story only re-shows when its active page no longer exists.20260910.1, which keeps Story video-ad audio controls available when the ad capability signal and media setup complete in either order.20260817.1, fixing captions-state synchronization and quiz result-page enablement during AMP page initialization while preserving useful errors for invalid page references.instructions.iconHighlightColor and instructions.iconColor theme properties for independently styling the highlight and foreground colours of built-in Story instruction icons. iconHighlightColor falls back to colors.primary, while iconColor falls back to the effective instructions.headingColor. Existing custom instructions.icons URL overrides remain unchanged, so colour-only branding does not require custom icon assets.customInstanceHost values cannot control iframe requests. Story Pages now use trusted server metadata when present and otherwise retain the existing environment-based API defaults.clipPlayer.showFeedTitle, clipPlayer.showClipTitle, and clipPlayer.showNavigationCategories theme properties so Clips player integrations can hide feed-title, clip-title, and navigation-category chrome independently.StorytellerEmbeddedClipsPlayerView as a first-class iframe-free embedded Clips player API with the same collection, clipId, and externalId source contract as StorytellerClipsPlayerView. See the embedded Clips player docs for initialization, sizing, configuration, and list configuration.20260626.1.StorytellerClipsPlayerView, allowing embedded Clips players to initialize from either clipId or externalId while preserving the existing collection-based constructor.topLevelBackButtonEnabled and onTopLevelBackTapped support for embedded StorytellerClipsPlayerView instances so host apps can render and handle a top-level back button.theme.player.icons.back support for customizing the Clips player back/close icon.publisherProvidedId support to Google Ad Manager ad configuration so integrations can send PPID separately from custom targeting KVPs.recordActivity payloads so activity externalId is still included when personalization tracking is disabled.20260518.1.20260428.1 to include story audio and story ad playback fixes.base HTML elements if provided)stNextClipCategories KVP to integrating app custom targetingrow.startPadding and row.endPadding theme properties to add padding to a row that should be flush with the container on scrolltheme.storyTiles.title.show property in favour of a value that can be set in the CMS. Starting from this version, this Theme property has no effect. Default value for the CMS property is true.collection was renamed to stCollection, clipCategories was renamed to stClipCategories, and so on)showScrollIndicator theme property to hide/show scroll arrows in Stories/Clips rows.d.ts filesstoryTiles.title.show was set to falsebetweenStoriesAndPages and betweenClips ads strategies, that will be the index after which the first ad will appear. Can be configured in the CMS.clipShares as a supported disabledFunctionalFeatures value in tracking preferences. For details, see the Privacy and Tracking documentationdisabledFunctionalFeatures option in tracking preferences. For details, see the Privacy and Tracking documentationnull is now supportedenableRemoteViewingStore option in tracking preferences. For details, see the Privacy and Tracking documentationrecentStoryPlaybackMode is now only saved to local storage if needed for analyticsenablePersonalization tracking preference is set to falsesettingsSavedDate local storage itemImprovements:
Breaking changes:
Storyteller.currentUserId method as part of privacy enhancements.enableFullVideoAnalytics property to eventTrackingOptions for granular video analytics control. See Privacy and Tracking for details.Improvements:
sheet actions in Clips.Improvements:
dependencies to devDependenciesFeatures:
enableAdTracking property to eventTrackingOptionsImprovements:
Improvements:
storyTiles.rectangularTile.showGradient to false)Improvements:
Bug Fixes:
New Features:
#stories/[STORY_ID], #clips/[COLLECTION_ID], and #clips/[COLLECTION_ID]/[CLIP_ID] routeseventTrackingOptions property can be used for customising the analytics and tracking behaviorImprovements:
open* methods now match the native SDKs:openStory is now asyncopenStoryByExternalId is now supportedopenPage is now asyncopenCategory is now asyncopenClip is now deprecated (please use openCollection instead)openCollection is now async and accepts a destination argument with either a Clip ID or Category IDopenClipByExternalId is now supportedBug Fixes:
player.playAllStories theme property was set to falsedata-base-url was setNew Features:
userNavigatedToApp method to the Storyteller delegateImprovements:
Improvements:
Improvements:
Bug Fixes:
New Features:
enableViewedOrdering in a Clips collectionImprovements:
Bug Fixes:
OpenedStory, SkippedStory, DismissedStory, and DismissedClips events to not get recorded in some casesImprovements:
Bug Fixes:
New Features:
player.disableUrls and clipPlayer.disableUrls theme propertiesImprovements:
New Features:
Improvements:
Bug Fixes:
Bug Fixes:
Improvements:
onShareButtonTapped function returns null or isn't a PromiseImprovements:
clipActionText and clipActionUrl properties are now recorded for Clip eventsBug Fixes:
completedStory event not to be recorded if a Story was already readImprovements:
Improvements:
Bug Fixes:
Bug Fixes:
Bug Fixes:
Improvements:
liveChip.textColor theme property with liveChip.readTextColor and liveChip.unreadTextColorstoryTiles.liveChip theme properties with storyTiles.rectangularTile.liveChip and storyTiles.circularTile.liveChipBug Fixes:
Improvements:
Bug Fixes:
Improvements:
Bug Fixes:
Improvements:
Bug Fixes:
Improvements:
Bug Fixes:
New Features:
Improvements:
Bug Fixes:
Bug Fixes:
New Features:
openCategory method to Story viewsStoryteller.User.setLocaleImprovements:
Bug Fixes:
Bug Fixes:
Bug Fixes:
Improvements:
lists.row.scrollIndicatorInlineAlignment theme property is set to outside and the row doesn't have enough items for the scroll indicators to be visible, the empty space where the indicator would normally sit has been removedNew Features:
configuration.preload property at the list level)StorytellerClipsPlayerView)lists.row.scrollIndicatorInlineAlignment theme propertystoryTiles.circularTile.scrollIndicatorBlockAlignment theme propertystoryTiles.circularTile.unreadStrokeWidth and storyTiles.circularTile.readStrokeWidth theme propertiesImprovements:
Esc buttonOpenedReason now has additional possible values: tap and automaticPlaybackDismissedReason now has additional possible values: backgroundTapped, skippedFinalPage, completedFinalPage, and backTappedAlignment, ButtonAlignment, and TextCaseIListConfiguration type is now exposed and can be used to set a list's configurationIStorytellerDelegate to make the onUserActivityOccurred callback optionalIStorytellerDelegate to make customTargeting optional in getAdConfigplayAllStories is set to false and the next Story will be skipped, the next Story button is greyed outBug Fixes:
OpenedPage event not to get triggeredOpenedReason to be recorded when opening a Story or PageBug Fixes:
Bug Fixes:
Bug Fixes:
Bug Fixes:
navigator being undefinedNew Features:
configuration object for list viewsImprovements:
instanceMethod and escapeKeyPressed in the analytics events' DismissedReason propertytap and automaticPlayback in the analytics events' OpenedReason propertyisInitialized and isPlayerVisible properties to the global Storyteller instancedismissPlayer method to the global Storyteller instanceenableEventTracking and disableEventTracking methods to the global Storyteller instanceenableLogging method to the global Storyteller instanceIListViewDelegate type exportopenPage and openStory methods from the list views to the global Storyteller instanceonShareButtonClicked callback to onShareButtonTapped and moved it to the global Storyteller delegateonStoriesDataLoadStarted callback to onDataLoadStartedonStoriesDataLoadComplete callback to onDataLoadCompleteonStoryDismissed callback to onPlayerDismissedgetAdConfig method to the global Storyteller delegateonUserActivityOccurred callback to the global Storyteller delegatetileBecameVisible callbackonError callbackBug Fixes:
OpenedPage event did not fire on Stories with a single PageSkippedStory event did not fire when the final Page of a Story was skippedImprovements:
lists.backgroundColor theme property to set the placeholder stylesImprovements:
title.show theme property to show/hide Story titles on all tilescircularTile.title.hide theme propertyBug Fixes:
Bug Fixes:
Bug Fixes:
package.jsonBug Fixes:
Bug Fixes:
Bug Fixes:
Improvements:
Improvements:
Bug Fixes:
Improvements:
externalIdBug Fixes:
CurrentCategory no longer reports \"Home\"Improvements:
externalId for Categories for Ads TargetingNew Features:
Improvements:
title attribute in iframesNew Features:
Improvements:
SkippedPage Analytics EventCompletedPage Analytics EventPage Title to all eventsalt attributesImprovements:
Bug Fixes:
Improvements:
AdConfig before passing it to Story ViewBug Fixes:
Bug Fixes:
New Features:
useGoogleWebStoryUrls parameter to StorytellerStoriesGridViewImprovements:
Bug Fixes:
New Features:
Bug Fixes:
OpenedStory and OpenedPage events might not fire. This is now fixed.New Features:
theme on an individual StorytellerStoriesRowView or StorytellerStoriesGridViewImprovements:
Bug Fixes:
New Features:
Improvements:
Improvements:
New Features:
customInstanceHostImprovements:
New Features:
useGoogleWebStoryUrls parameter to StorytellerListViewBug Fixes:
Improvements:
Bug Fixes:
Bug Fixes:
Bug Fixes:
Bug Fixes:
Bug Fixes:
Bug Fixes:
font theme propertyinstructions.icons theme propertyImprovements:
showWebStoriesIcon theme propertyBug Fixes:
Improvements:
displayLimit to rows and gridscontentLength in user activity delegate callbackBug Fixes:
Improvements:
Bug Fixes:
Bug Fixes:
Bug Fixes:
Improvements:
New Features:
openStory and openPage methodsNew Features:
Bug Fixes:
Bug Fixes:
externalApp swipe ups are recorded correctlyImprovements:
Bug Fixes:
Improvements:
Bug Fixes:
Deprecation and Changes:
showStoryTitle theme propertyshowStoryIcon theme propertyImprovements:
Bug Fixes:
Bug Fixes:
Bug Fixes:
Bug Fixes:
Improvements:
New Features:
New Features:
New Features:
Improvements:
Improvements:
navigator.shareexternalId optionalImprovements:
pollAnswerId in analytics eventsBug Fixes:
Improvements:
New Features:
Improvements:
Bug Fixes:
New Features:
New Features:
playAllStories option to the theme which will not exit the Story player when the user reaches the end of their unread Stories - but rather keep them in the Stories experience until they see every Story in the rowBug Fixes:
Improvements:
Bug Fixes:
New Features:
Bug Fixes:
Improvements:
Bug Fixes:
storyReadStatus in analytic eventsImprovements:
VotedPoll event to the docsBug Fixes:
Improvements:
Bug Fixes:
Improvements:
Bug Fixes:
Bug Fixes:
Improvements:
onShareButtonClicked() delegated methodBug Fixes:
Bug Fixes:
New Features:
Improvements:
navigator.share doesn't existonShareButtonClick callback is definedBug Fixes:
Bug Fixes:
New Features:
tileLoading state to tilesNew Features:
Bug Fixes:
Deprecations and Changes:
Bug Fixes:
Open a Story or Clips player from your own button, link, or route instead of a tile. These methods are on Storyteller.sharedInstance. Each one returns a promise that rejects when the SDK can't open the content. Call them after initialize resolves.
const openFeaturedStory = async () => {\n try {\n await Storyteller.sharedInstance.openStory('story-id');\n } catch (error) {\n console.error('The Story could not be opened.', error);\n }\n};\n\ndocument\n .getElementById('featured-story-button')\n ?.addEventListener('click', openFeaturedStory);\nThe SDK first looks for the content in the views on your page and opens it in that view's player. It uses only views whose player URLs are turned on, which means the disableUrls theme setting is false. If no view on the page has the content, the SDK loads it from Storyteller and opens it in a default player. Either way, the SDK opens the player by setting the page's hash URL, such as #stories/story-id, and the promise resolves at that point. See basename for the URL format.
Opens a Story by its ID.
await Storyteller.sharedInstance.openStory('story-id');\nFull signature: openStory.
Opens a Story by its external ID.
await Storyteller.sharedInstance.openStoryByExternalId('story-external-id');\nFull signature: openStoryByExternalId.
Opens the Story that contains a Page, starting at that Page.
await Storyteller.sharedInstance.openPage('page-id');\nFull signature: openPage.
Opens the Story player for a Category. Pass a Story ID as the second argument to start at that Story; otherwise, the first Story in the Category opens.
await Storyteller.sharedInstance.openCategory('category-id', 'story-id');\nFull signature: openCategory.
Opens the Clips player for a collection. Pass a destination to start at a Clip, or at the first Clip in a Clip Category. Otherwise, the first Clip in the collection opens.
await Storyteller.sharedInstance.openCollection('collection-id');\n\nawait Storyteller.sharedInstance.openCollection('collection-id', {\n clipId: 'clip-id',\n});\n\nawait Storyteller.sharedInstance.openCollection('collection-id', {\n categoryId: 'clip-category-id',\n});\nWhen the user arrived through a deep link, pass Storyteller.OpenedReason.deepLink as the third argument so analytics events report deepLink as the reason:
await Storyteller.sharedInstance.openCollection(\n 'collection-id',\n { clipId: 'clip-id' },\n Storyteller.OpenedReason.deepLink\n);\nFull signature: openCollection.
Opens the Clips player for a collection, at the Clip with this external ID.
await Storyteller.sharedInstance.openClipByExternalId(\n 'collection-id',\n 'clip-external-id'\n);\nFull signature: openClipByExternalId.
Call dismissPlayer to close the open Story or Clips player, for example when your application navigates away. Pass true to play the close animation. If no player is open, the call does nothing. It doesn't close a StorytellerEmbeddedClipsPlayerView.
if (Storyteller.sharedInstance.isPlayerVisible) {\n Storyteller.sharedInstance.dismissPlayer(true);\n}\nFull signature: dismissPlayer.
Wrap each call in try/catch, or add .catch(), so that a rejected promise doesn't go unhandled. The rejection value can be an Error or a string.
openStory, openStoryByExternalId Rejects when the Story request fails, or with a string when no Story has the ID. openPage Rejects when the SDK can't load a Story that contains the Page. openCategory Rejects when the SDK can't load the Category, or the Category has no Stories. If storyId isn't in the Category, the first Story opens instead. openCollection Rejects when the SDK can't load the collection, or the collection has no Clips. If the destination Clip or Category isn't in the collection, the first Clip opens instead. openClipByExternalId Rejects when the SDK can't load the collection, or with a string when the collection has no Clip with the external ID. When the SDK opens the first Story or Clip instead of the one you asked for, it logs a message. Call enableLogging to see it in the browser console.
basenameUse 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.
Storyteller.sharedInstance.eventTrackingOptions = {\n disabledFunctionalFeatures: ['all'],\n enableAdTracking: false,\n enableFullVideoAnalytics: false,\n enableFunctionalCookies: false,\n enablePersonalization: false,\n enableRemoteViewingStore: false,\n enableStorytellerTracking: false,\n enableUserActivityTracking: false,\n};\nimport * as Storyteller from '@getstoryteller/storyteller-sdk-javascript';\nimport {\n StorytellerTrackedFunctionalFeature,\n type StorytellerEventTrackingOptions,\n} from '@getstoryteller/storyteller-sdk-javascript';\n\nconst eventTrackingOptions: StorytellerEventTrackingOptions = {\n disabledFunctionalFeatures: [StorytellerTrackedFunctionalFeature.all],\n enableAdTracking: false,\n enableFullVideoAnalytics: false,\n enableFunctionalCookies: false,\n enablePersonalization: false,\n enableRemoteViewingStore: false,\n enableStorytellerTracking: false,\n enableUserActivityTracking: false,\n};\n\nStoryteller.sharedInstance.eventTrackingOptions = eventTrackingOptions;\nBy 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.
"},{"location":"PrivacyAndTracking/#disabled-functional-features","title":"Disabled functional features","text":"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.
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."},{"location":"PrivacyAndTracking/#ad-tracking","title":"Ad tracking","text":"Set enableAdTracking to false to:
onUserActivityOccurred callbackpublisherProvidedId that your getAdConfig callback returns out of ad requestsThe customTargeting values that your getAdConfig callback returns are still sent. Leave them out yourself when a user opts out of ad tracking.
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, storyDisplayTitleclipId, clipTitlepageId, pageTitleThis 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.
"},{"location":"PrivacyAndTracking/#functional-cookies-and-local-storage-items","title":"Functional cookies and local storage items","text":"Set enableFunctionalCookies to false to:
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.
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.
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.
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.
"},{"location":"PrivacyAndTracking/#user-personalization","title":"User personalization","text":"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.
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.
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.
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.
This quickstart shows one row of published Stories on a web page. You add a container, initialize the SDK, create the row, and check that Stories loaded. Before you start lists what you need.
"},{"location":"Quickstart/#install-the-sdk","title":"Install the SDK","text":"
Install the SDK with one of these guides, then return to this page:
storyteller.min.js from the Storyteller CDNimport or a CommonJS requireThe steps below use the SDK as Storyteller. The samples use await, which works only in JavaScript modules and inside async functions. In a classic <script>, wrap the code in an async function, as shown in Handle initialization errors.
<div id=\"storyteller-stories-row\" style=\"height: 200px\"></div>\nThe row sizes its tiles to the container's height, so set a height on the container. If the container has no height, the SDK uses a default tile height (160 px for square tiles, 120 px or 140 px for round tiles). When logging is enabled, it also logs a warning.
Warning
The container ID must be unique on the page and follow best practices for HTML IDs. Use only ASCII letters, numbers, dashes (-), and underscores (_).
Call initialize with your API key, and wait for it to resolve before you create a view:
await Storyteller.sharedInstance.initialize('demo-api-key');\nReplace demo-api-key with your API key. If the user is signed in, pass your user ID as externalId. With the default privacy options, the user's viewing history then follows them across browsers and devices:
await Storyteller.sharedInstance.initialize('demo-api-key', {\n externalId: 'your-user-id',\n});\nIdentify and personalize users explains user IDs and how to change the user.
"},{"location":"Quickstart/#create-the-row","title":"Create the row","text":"const storyRow = new Storyteller.StorytellerStoriesRowView(\n 'storyteller-stories-row'\n);\nThe constructor takes the container ID and an optional list of Category IDs: StorytellerStoriesRowView(containerId: string, categories?: string[]). To show Stories from specific Categories only, pass their IDs:
const filteredStoryRow = new Storyteller.StorytellerStoriesRowView(\n 'storyteller-stories-row',\n ['category-id']\n);\nChoose a view lists the grid and Clips views. The Storyteller Web Showcase creates a row with the same StorytellerStoriesRowView constructor.
initialize returns a promise that rejects when the SDK can't start. Catch the error and show a fallback in your page. Without top-level await, use an async function:
async function initializeStoryteller() {\n try {\n await Storyteller.sharedInstance.initialize('demo-api-key');\n // Create Storyteller views here.\n } catch (error) {\n console.error('Storyteller could not start.', error);\n }\n}\n\ninitializeStoryteller();\nYou can also handle the promise directly:
Storyteller.sharedInstance\n .initialize('demo-api-key')\n .then(() => {\n // Create Storyteller views here.\n })\n .catch((error) => {\n console.error('Storyteller could not start.', error);\n });\nThe promise rejects with an Error whose message starts with the error type, for example InvalidApiKeyError - The API Key provided was invalid. The SDK doesn't export these error classes, and error.name is always \"Error\", so check the start of the message, for example error.message.startsWith('InvalidApiKeyError'):
InvalidApiKeyError: Storyteller rejected the API key (HTTP 401 or 404)NetworkTimeoutError: a request timed outNetworkError: a request failed, or returned an empty or malformed responseThese errors come from the settings request. With the default privacy options, initialize also requests the user's viewing history (GET /api/UserActivity/{userId}) and waits for it. If that request fails, initialize rejects with one of the same errors.
If you call initialize without an API key, the promise rejects with a text message instead of an Error.
Earlier guides also listed InitializationError and JsonParseError. The SDK reports those cases as NetworkError.
A horizontal row of Story tiles appears. Selecting a tile opens the Story player.
To see whether the row loaded, set a delegate on the row with an onDataLoadComplete callback:
storyRow.delegate = {\n onDataLoadComplete: (success, error, dataCount) => {\n if (success) {\n console.log(`Loaded ${dataCount} Stories.`);\n } else {\n console.error('Stories could not load.', error?.message);\n }\n },\n};\nsuccess is false when the request fails or returns no Stories. When no Stories are returned, error.message starts with EmptyResponseError.
initialize rejects Check the API key and the error message. See Handle initialization errors. success is false and error.message starts with EmptyResponseError The request worked but returned no Stories. Check the Category IDs, and check that the Stories are published in the same tenant as the API key. success is false with another error Find the failed request in the browser Network panel, and check its HTTP status. success is true, but no tiles show Check the container's height and width, and check for page CSS that hides it. Troubleshoot an integration covers more problems.
"},{"location":"Quickstart/#next-steps","title":"Next steps","text":"
Set Storyteller.sharedInstance.delegate to handle events from every Storyteller view and player: analytics events, share taps, ad requests, and in-app action links. The delegate is an object typed IStorytellerDelegate. For loading and dismissal events from one row, grid, or Clips player, see Handle view callbacks.
Assign an object with the callbacks you need to Storyteller.sharedInstance.delegate. Set it before you call initialize, so that it receives the sdkInitialized event.
Storyteller.sharedInstance.delegate = {\n onUserActivityOccurred: (type, data) => {\n console.log(type, data.context);\n },\n};\nWarning
Assigning delegate replaces all four global callbacks. A callback you leave out of the new object stops being called, even if an earlier assignment set it. Define every callback in one object, or spread the current delegate into the new one.
const getAdConfig = (adRequestInfo) => {\n // Return { slot, customTargeting, publisherProvidedId }, or null for no ad.\n // See Integrate ads.\n return null;\n};\n\nStoryteller.sharedInstance.delegate = {\n ...Storyteller.sharedInstance.delegate,\n getAdConfig,\n};\nAll callbacks are optional.
"},{"location":"StorytellerDelegate/#onuseractivityoccurred","title":"onUserActivityOccurred","text":"onUserActivityOccurred?: (type: ActivityType, data: UserActivityData) => void;\nCalled when an analytics event occurs in a Story or Clips player. A view with a context returns that value in data.context. See Analytics context for the supported views, inheritance rules, and data boundary. The SDK calls this callback only while enableUserActivityTracking is on, and sends ad events only while enableAdTracking is also on. See Integrate analytics for the event types.
The Storyteller Web Showcase has an onUserActivityOccurred handler.
onShareButtonTapped?: (text: string, title: string, url: string) => Promise<void>;\nCalled when the user taps the share button in a Story or a Clip. Use it to replace the default share behavior. The SDK passes the text, title, and URL it would otherwise share, and pauses the Story or Clip. When your promise resolves, the SDK records a shareSuccess event. When the promise resolves or rejects, the Story or Clip plays again.
If you don't implement this callback, the SDK opens the browser's share sheet with navigator.share. The share button appears only in browsers that support navigator.share, even when you implement this callback. Story Pages that share their media file download it instead and don't call this callback.
The Storyteller Web Showcase shows an onShareButtonTapped override.
getAdConfig?: (adRequestInfo: StorytellerAdRequestInfo) => AdConfig | null;\nCalled when a Story or Clips player needs an ad and your tenant uses Google Ad Manager ads. Return an object with these fields, or null for no ad:
slot: the ad unit path to requestcustomTargeting (optional): key-value pairs for ad targetingpublisherProvidedId (optional): your publisher provided IDStory ad requests include story. Clips ad requests include clip, nextClip, and collection, and have no story field. The SDK doesn't export the AdConfig type. See Integrate ads for the full request and response details.
The Storyteller Web Showcase's buildAdConfig shows how to return slots and custom targeting values.
userNavigatedToApp?: (url: string) => void;\nCalled when a user taps an action button in a Story or Clip that links into your app (an inApp action). Route the user to url in your app. If you don't implement this callback, inApp actions open like regular URLs.
interface IStorytellerDelegate {\n onUserActivityOccurred?: (type: ActivityType, data: UserActivityData) => void;\n\n onShareButtonTapped?: (\n text: string,\n title: string,\n url: string\n ) => Promise<void>;\n\n getAdConfig?: (adRequestInfo: StorytellerAdRequestInfo) => AdConfig | null;\n\n userNavigatedToApp?: (url: string) => void;\n}\nFor a full implementation that wires every callback, see the Storyteller Web Showcase's attachStorytellerDelegate.
Use a Clips player view to play Clips in an element on your page, instead of opening the Clips player from a row or grid. The Web SDK has two Clips player views. Both render into your container, fill it, and accept the same content sources, configuration, and delegate.
"},{"location":"StorytellerEmbeddedClipsPlayerView/#choose-a-clips-player-view","title":"Choose a Clips player view","text":"View Use it for BehaviorStorytellerEmbeddedClipsPlayerView Clips inside other page content, such as a live blog or match center Shows one Clip at a time. The rest of the page keeps scrolling. Storyteller.sharedInstance.dismissPlayer doesn't close it. StorytellerClipsPlayerView An area of the page set aside for Clips Uses the full Clips player layout, which can show neighboring Clips on wide screens. Locks page scrolling while it's shown. dismissPlayer dismisses it. The rest of this page uses StorytellerEmbeddedClipsPlayerView. The same steps apply to StorytellerClipsPlayerView.
StorytellerEmbeddedClipsPlayerView accepts the same content sources as StorytellerClipsPlayerView: a collection ID, { clipId }, or { externalId }.
const embeddedCollectionPlayer =\n new Storyteller.StorytellerEmbeddedClipsPlayerView(\n 'embedded-clips-player-id',\n 'clip-collection-id'\n );\n\nconst embeddedSingleClipPlayer =\n new Storyteller.StorytellerEmbeddedClipsPlayerView(\n 'embedded-clips-player-id',\n { clipId: 'clip-id' }\n );\n\nconst embeddedSingleClipPlayerByExternalId =\n new Storyteller.StorytellerEmbeddedClipsPlayerView(\n 'embedded-clips-player-id',\n { externalId: 'clip-external-id' }\n );\nProvide exactly one source. With a collection ID, the player keeps collection behavior: users can move between the collection's Clips when the collection supports it. With { clipId } or { externalId }, the player shows only that Clip. The constructor throws an Error if you pass no source or more than one.
Set the player's size with CSS on the container. The constructor has no width or height options.
For portrait Clips, set the container width and use a 9 / 16 aspect ratio so the browser works out the height:
<div\n id=\"embedded-clips-player-id\"\n style=\"width: 430px; max-width: 100%; aspect-ratio: 9 / 16;\"\n></div>\nconst embeddedSingleClipPlayer =\n new Storyteller.StorytellerEmbeddedClipsPlayerView(\n 'embedded-clips-player-id',\n { externalId: 'clip-external-id' }\n );\nThe embedded Clips player uses the same configuration fields as StorytellerClipsPlayerView. See Configure views for every field. The TypeScript example assumes import * as Storyteller from '@getstoryteller/storyteller-sdk-javascript'; and imports the IStorytellerEmbeddedClipsPlayerConfiguration type.
const customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst embeddedClipPlayer = new Storyteller.StorytellerEmbeddedClipsPlayerView(\n 'embedded-clips-player-id',\n { externalId: 'clip-external-id' }\n);\nconst embeddedClipPlayerConfiguration: IStorytellerEmbeddedClipsPlayerConfiguration =\n {\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n };\n\nembeddedClipPlayer.configuration = embeddedClipPlayerConfiguration;\nYou can also change the source through configuration. Provide exactly one of collection, clipId, or externalId. An update with an invalid source logs an error and keeps the current source.
embeddedClipPlayer.configuration = {\n externalId: 'new-clip-external-id',\n};\nStorytellerEmbeddedClipsPlayerView uses the Clips player delegate (IStorytellerClipsPlayerDelegate) through the same delegate property as StorytellerClipsPlayerView. See Handle view callbacks for every callback.
const embeddedClipPlayer = new Storyteller.StorytellerEmbeddedClipsPlayerView(\n 'embedded-clips-player-id',\n { externalId: 'clip-external-id' }\n);\n\nembeddedClipPlayer.topLevelBackButtonEnabled = true;\nembeddedClipPlayer.delegate = {\n onTopLevelBackTapped: () => {\n window.history.back();\n },\n};\nonPlayerDismissed means that the player was dismissed, so the back button doesn't call it. The button calls onTopLevelBackTapped if you define it; otherwise, it calls window.history.back().
When topLevelBackButtonEnabled is false or not set, the player doesn't show the back button and doesn't call onTopLevelBackTapped from it.
Use StorytellerClipsPlayerView when an area of your page, such as a Clips section or a Clips page, is set aside for the player. It takes the same arguments, configuration, and delegate as StorytellerEmbeddedClipsPlayerView:
const clipPlayer = new Storyteller.StorytellerClipsPlayerView(\n 'clips-player-id',\n 'clip-collection-id'\n);\n\nclipPlayer.topLevelBackButtonEnabled = true;\nclipPlayer.delegate = {\n onTopLevelBackTapped: () => {\n window.history.back();\n },\n};\nStorytellerClipsPlayerView differs from the embedded player in three ways:
Storyteller.sharedInstance.dismissPlayer dismisses it and calls its onPlayerDismissed callback.For its constructor and configuration, see Clips player initialization and Clips player configuration.
"},{"location":"StorytellerGridView/","title":"Add a Story or Clips grid","text":"A grid shows Story or Clip tiles in columns. Use StorytellerStoriesGridView for Stories and StorytellerClipsGridView for Clips. Set the number of columns with the lists.grid.columns theme property. To show a grid only when it has content, check getStoriesCount or getClipsCount first.
Create the grid with the ID of an existing element on your page. Grids take the same arguments as the other views in Configure views:
"},{"location":"StorytellerGridView/#stories-initialization","title":"Stories initialization","text":"const storyGrid = new Storyteller.StorytellerStoriesGridView('stories-grid-id'); // All Categories\nconst storyGridWithCategories = new Storyteller.StorytellerStoriesGridView(\n 'stories-grid-id',\n ['category-1', 'category-2']\n);\nconst clipsGrid = new Storyteller.StorytellerClipsGridView(\n 'clips-grid-id',\n 'clip-collection-id'\n);\nGrids accept every setting in Configure views. Grids don't use cellType. TypeScript examples assume import * as Storyteller from '@getstoryteller/storyteller-sdk-javascript'; and import type { IListConfiguration } from '@getstoryteller/storyteller-sdk-javascript';.
const customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst storyGrid = new Storyteller.StorytellerStoriesGridView('stories-grid-id');\nstoryGrid.configuration = {\n categories: ['category1', 'category2', 'category3'], // Stories only\n displayLimit: 10,\n preload: true, // Stories only\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nconst customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst storyGrid = new Storyteller.StorytellerStoriesGridView('stories-grid-id');\nconst storyGridConfiguration: IListConfiguration<'StorytellerStoriesGridView'> =\n {\n categories: ['category1', 'category2', 'category3'], // Stories only\n displayLimit: 10,\n preload: true, // Stories only\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n };\nstoryGrid.configuration = storyGridConfiguration;\nFor a live example, review the Storyteller Web Showcase's StorytellerStoriesGridView, which sets basename, displayLimit, and custom themes.
const customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst clipsGrid = new Storyteller.StorytellerClipsGridView(\n 'clips-grid-id',\n 'collection-id'\n);\nclipsGrid.configuration = {\n displayLimit: 10,\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nconst customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst clipsGrid = new Storyteller.StorytellerClipsGridView(\n 'clips-grid-id',\n 'collection-id'\n);\nconst clipsGridConfiguration: IListConfiguration<'StorytellerClipsGridView'> = {\n displayLimit: 10,\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nclipsGrid.configuration = clipsGridConfiguration;\nFor Clips, the Storyteller Web Showcase's StorytellerClipsGridView sets the collection ID and display limit with the same configuration object.
This page covers the settings and methods shared by every Storyteller view: Story and Clips rows and grids, and the two Clips player views. For the settings that only rows or only grids use, see Add a Story or Clips row and Add a Story or Clips grid.
Note
Most examples use StorytellerStoriesRowView. The same settings apply to StorytellerStoriesGridView, StorytellerClipsRowView, and StorytellerClipsGridView. Where StorytellerClipsPlayerView or StorytellerEmbeddedClipsPlayerView works differently, the section says so.
Create each view with the ID of an existing element on your page, followed by its content source.
"},{"location":"StorytellerListView/#stories-initialization","title":"Stories initialization","text":"const storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id'); // All Categories\nconst storyRowWithCategories = new Storyteller.StorytellerStoriesRowView(\n 'stories-row-id',\n ['category-1', 'category-2']\n);\nconst clipsRow = new Storyteller.StorytellerClipsRowView(\n 'clips-row-id',\n 'clip-collection-id'\n);\nStorytellerClipsPlayerView shows the Clips player in your container instead of opening it from a row or grid. Pass a collection ID to play the collection, or { clipId } or { externalId } to play one Clip. For a player inside other page content, such as a live blog, use StorytellerEmbeddedClipsPlayerView. Add a Clips player to a page compares the two views.
const collectionPlayer = new Storyteller.StorytellerClipsPlayerView(\n 'clips-player-id',\n 'clip-collection-id'\n);\n\nconst singleClipPlayer = new Storyteller.StorytellerClipsPlayerView(\n 'clips-player-id',\n { clipId: 'clip-id' }\n);\n\nconst singleClipPlayerByExternalId = new Storyteller.StorytellerClipsPlayerView(\n 'clips-player-id',\n { externalId: 'clip-external-id' }\n);\nThe constructor throws an Error if you pass no source or more than one source.
The Storyteller Web Showcase picks a Stories row or grid for each feed module from its layout with isGridLikeLayout.
Rows and grids can order Stories by what the user has already read. Storyteller sets the ordering for your content in the Stories API response; you don't set it in code. With the default read ordering, unread Stories come before read Stories. With started-aware ordering, Stories appear in three groups: not opened, started, and finished. Pinned Stories stay first, and Live Stories stay ahead of the other Stories. Within each group, Stories keep the order set in the Storyteller CMS.
"},{"location":"StorytellerListView/#clips-paging","title":"Clips paging","text":"Clips rows, grids, and players that show a collection load more Clips when the user reaches the last loaded Clip, including inside a Clip Category. The SDK skips Clips it has already shown and stops when the collection has no more Clips. You don't need to change your code.
reloadData loads the first page again.onDataLoadComplete callback reports the first page only. Later pages load without delegate callbacks.{ clipId } or { externalId }, doesn't load more Clips.The Clips player shows a Clip's long description when the Clip has one. The title, description, and Categories show a short preview, and one control expands or collapses them. Long details scroll inside the player. A Clip without a description shows its title and Categories. To hide the title, see the Clips player theme settings.
"},{"location":"StorytellerListView/#rtl-support","title":"Right-to-left (RTL) pages","text":"The Web SDK supports right-to-left host pages for Stories rows, Clips rows, and the Story player.
"},{"location":"StorytellerListView/#host-page-setup","title":"Host page setup","text":"Set dir=\"rtl\" on the page or on the closest container that wraps the SDK view:
<section dir=\"rtl\">\n <div id=\"stories-row-id\"></div>\n</section>\nconst storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id');\nThe SDK reads the text direction from the view's container and its ancestors, so one page can mix directions. For example, a left-to-right page can show one Storyteller row inside a right-to-left section.
"},{"location":"StorytellerListView/#supported-surfaces","title":"Supported surfaces","text":"RTL support applies to:
StorytellerStoriesRowViewStorytellerClipsRowViewIn a right-to-left row, the scroll controls, edge fades, and disabled states follow the right-to-left scroll direction.
When a Story opens from an RTL page, the Story player uses right-to-left text and controls.
"},{"location":"StorytellerListView/#configuration","title":"Configuration","text":"Set a view's options by assigning an object to its configuration property. Assigning a partial object updates only the fields it contains. In TypeScript, type the object with IListConfiguration<'StorytellerStoriesRowView'> (use the view's class name), IStorytellerClipsPlayerConfiguration, or IStorytellerEmbeddedClipsPlayerConfiguration.
TypeScript examples
The TypeScript examples in these guides assume import * as Storyteller from '@getstoryteller/storyteller-sdk-javascript'; and import the configuration types they use, for example import type { IListConfiguration } from '@getstoryteller/storyteller-sdk-javascript';.
const customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id');\nstoryRow.configuration = {\n basename: 'top-stories', // Needed if there are multiple lists on the same page\n categories: ['category1', 'category2', 'category3'], // Stories only\n cellType: Storyteller.CellType.round, // StorytellerStoriesRowView only\n context: {\n source: 'homepage-stories',\n campaign: 'summer-league'\n },\n displayLimit: 10,\n preload: true, // Stories only\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nconst customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id');\nconst storyRowConfiguration: IListConfiguration<'StorytellerStoriesRowView'> = {\n basename: 'top-stories', // Needed if there are multiple lists on the same page\n categories: ['category1', 'category2', 'category3'], // Stories only\n cellType: Storyteller.CellType.round, // StorytellerStoriesRowView only\n context: {\n source: 'homepage-stories',\n campaign: 'summer-league'\n },\n displayLimit: 10,\n preload: true, // Stories only\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nstoryRow.configuration = storyRowConfiguration;\nconst customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst clipsRow = new Storyteller.StorytellerClipsRowView(\n 'clips-row-id',\n 'collection-id'\n);\nclipsRow.configuration = {\n basename: 'top-clips', // Needed if there are multiple lists with the same collection on the same page\n context: {\n source: 'homepage-clips',\n campaign: 'summer-league'\n },\n displayLimit: 10,\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nconst customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst clipsRow = new Storyteller.StorytellerClipsRowView(\n 'clips-row-id',\n 'collection-id'\n);\nconst clipsRowConfiguration: IListConfiguration<'StorytellerClipsRowView'> = {\n basename: 'top-clips', // Needed if there are multiple lists with the same collection on the same page\n context: {\n source: 'homepage-clips',\n campaign: 'summer-league'\n },\n displayLimit: 10,\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nclipsRow.configuration = clipsRowConfiguration;\nconst customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst clipPlayer = new Storyteller.StorytellerClipsPlayerView(\n 'clips-player-id',\n { externalId: 'clip-external-id' }\n);\nclipPlayer.configuration = {\n basename: 'highlight-player',\n context: {\n source: 'homepage-highlight',\n campaign: 'google-highlights'\n },\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nclipPlayer.topLevelBackButtonEnabled = true;\nclipPlayer.delegate = {\n onTopLevelBackTapped: () => {\n window.history.back();\n },\n};\nconst customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst clipPlayer = new Storyteller.StorytellerClipsPlayerView(\n 'clips-player-id',\n { externalId: 'clip-external-id' }\n);\nconst clipPlayerConfiguration: IStorytellerClipsPlayerConfiguration = {\n basename: 'highlight-player',\n context: {\n source: 'homepage-highlight',\n campaign: 'google-highlights'\n },\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nclipPlayer.configuration = clipPlayerConfiguration;\nclipPlayer.topLevelBackButtonEnabled = true;\nclipPlayer.delegate = {\n onTopLevelBackTapped: () => {\n window.history.back();\n },\n};\nStorytellerEmbeddedClipsPlayerView uses the same configuration fields as StorytellerClipsPlayerView:
const customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst embeddedClipPlayer =\n new Storyteller.StorytellerEmbeddedClipsPlayerView(\n 'embedded-clips-player-id',\n { externalId: 'clip-external-id' }\n );\nembeddedClipPlayer.configuration = {\n basename: 'live-blog-highlight-player',\n context: {\n location: 'live-blog',\n module: 'highlight-player',\n },\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nembeddedClipPlayer.topLevelBackButtonEnabled = true;\nembeddedClipPlayer.delegate = {\n onTopLevelBackTapped: () => {\n window.history.back();\n },\n};\nconst customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst embeddedClipPlayer =\n new Storyteller.StorytellerEmbeddedClipsPlayerView(\n 'embedded-clips-player-id',\n { externalId: 'clip-external-id' }\n );\nconst embeddedClipPlayerConfiguration: IStorytellerEmbeddedClipsPlayerConfiguration = {\n basename: 'live-blog-highlight-player',\n context: {\n location: 'live-blog',\n module: 'highlight-player',\n },\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nembeddedClipPlayer.configuration = embeddedClipPlayerConfiguration;\nembeddedClipPlayer.topLevelBackButtonEnabled = true;\nembeddedClipPlayer.delegate = {\n onTopLevelBackTapped: () => {\n window.history.back();\n },\n};\nLearn more
See Add a Story or Clips row and Add a Story or Clips grid for the settings specific to rows and grids.
"},{"location":"StorytellerListView/#basename","title":"basename","text":"Each Stories or Clips view has a basename, which is the first segment of the player's hash URL. For example:
https://www.getstoryteller.com/#basename/story-id\nhttps://www.getstoryteller.com/#basename/collection-id/clip-id\nBy default, the basename is stories for Stories views and clips for Clips views. To change it, set basename in configuration:
storyRow.configuration = {\n basename: 'top-stories',\n};\nIf a page has only one Stories or Clips view, basename is optional. Opening a Story then goes to #stories/story-id, and opening a Clip goes to #clips/collection-id/clip-id.
If a page has several views, the SDK derives each view's basename from its Categories or collection. If two views have the same Categories or collection, set a different basename on each so that every view has a unique basename. Views with different Categories don't need one, but you can set it to make the player URL easier to read.
Note
The SDK removes every character from a basename except ASCII letters, numbers, dashes (-), and underscores (_).
Set categories to show only Stories from those Categories. Without categories, the view shows the Stories in your Home list.
To change the Categories of a Storyteller row, assign new ones in configuration:
storyRow.configuration = {\n categories: ['new-category-id-1', 'new-category-id-2'],\n};\nCopy Category IDs from the Storyteller CMS.
Learn more
See Categories for more information about managing Categories in the CMS.
"},{"location":"StorytellerListView/#collection-clips-only","title":"collection (Clips only)","text":"A Clips view needs a collection ID when you create it:
const clipsRow = new Storyteller.StorytellerClipsRowView(\n 'clips-row-id',\n 'clip-collection-id'\n);\nTo change the collection later, set collection in configuration:
clipsRow.configuration = {\n collection: 'new-clip-collection-id',\n};\nCopy the collection ID from the Storyteller CMS.
Learn more
See Creating Collections for more information about managing collections in the CMS.
"},{"location":"StorytellerListView/#clipid-externalid-clips-player-only","title":"clipId / externalId (Clips player only)","text":"To play a single Clip in StorytellerClipsPlayerView or StorytellerEmbeddedClipsPlayerView, pass an object with either clipId or externalId:
const clipPlayerById = new Storyteller.StorytellerClipsPlayerView(\n 'clips-player-id',\n { clipId: 'clip-id' }\n);\n\nconst clipPlayerByExternalId = new Storyteller.StorytellerClipsPlayerView(\n 'clips-player-id',\n { externalId: 'clip-external-id' }\n);\n\nconst embeddedClipPlayerByExternalId =\n new Storyteller.StorytellerEmbeddedClipsPlayerView(\n 'embedded-clips-player-id',\n { externalId: 'clip-external-id' }\n );\nTo switch the player to a different Clip later, assign the new identifier in configuration:
clipPlayerById.configuration = {\n clipId: 'new-clip-id',\n};\n\nclipPlayerByExternalId.configuration = {\n externalId: 'new-clip-external-id',\n};\nSet exactly one source on a Clips player: collection, clipId, or externalId. The constructor throws an Error if you pass no source or more than one. A later configuration update with an invalid source logs an error and keeps the current source.
The IStorytellerClipsPlayerConfiguration and IStorytellerEmbeddedClipsPlayerConfiguration types include the same source fields.
Set topLevelBackButtonEnabled on the player itself, not in configuration. It shows a back button at the top of a StorytellerClipsPlayerView or StorytellerEmbeddedClipsPlayerView:
const clipPlayer = new Storyteller.StorytellerClipsPlayerView(\n 'clips-player-id',\n { externalId: 'clip-external-id' }\n);\n\nclipPlayer.topLevelBackButtonEnabled = true;\nclipPlayer.delegate = {\n onTopLevelBackTapped: () => {\n window.history.back();\n },\n};\nWhen the user taps the back button:
clipPlayer.delegate.onTopLevelBackTapped is defined, the SDK calls it and your code decides what happens next.window.history.back().topLevelBackButtonEnabled defaults to false, which hides the button. While the button is hidden, the SDK doesn't call onTopLevelBackTapped.
Use context to identify the placement that produced an analytics event. The SDK returns its value in UserActivityData.context for each onUserActivityOccurred callback from the view.
clipsRow.configuration = {\n context: {\n location: 'home',\n module: 'featured-clips',\n sortOrder: 20,\n },\n};\nThe field accepts any value. An undefined value omits context from the callback. Explicit values such as null, false, 0, and an empty string stay in the callback. Reassign configuration to replace the value while the view is on the page.
When a user opens related Story or Clip content through an SDK action, the related player keeps the source view's context. If two matching placements share a player, events use the context from the placement that the user chose. The configured value returns after the player is dismissed.
The SDK adds context to the browser callback only. It doesn't add the field to Storyteller analytics API requests. The callback runs only while enableUserActivityTracking is on. Don't put credentials or personal data in context. See Analytics for the supported views, deep-link behavior, tracking controls, and data handling guidance.
displayLimit is the maximum number of tiles the view shows. It's optional.
Each Stories row or grid starts a low-priority download of the AMP player script before the user opens a Story. Set preload to true to also prepare the Story player in advance. The first Story then opens sooner if that work finishes in time, but users who never open a Story download more code. preload defaults to false. Keep the default when the first page load matters most.
Set theme to a UiTheme to style one view. It overrides the global theme (Storyteller.sharedInstance.theme) for that view only: the properties you set replace the global values, and the rest come from the global theme. A theme set in configuration stays in place when initialize runs again. See Customize themes.
const customTheme = new Storyteller.UiTheme({\n light: {\n lists: {\n row: {\n startInset: 0,\n endInset: 0,\n },\n },\n },\n});\n\nstoryRow.configuration = {\n theme: customTheme,\n};\nuiStyle sets whether the view uses the light theme, the dark theme, or follows the system setting. It takes a Storyteller.UiStyle value. JavaScript can also pass the strings 'auto', 'light', and 'dark'.
Storyteller.UiStyle.auto (default): the view follows the system light or dark modeStoryteller.UiStyle.light: the view always uses the light themeStoryteller.UiStyle.dark: the view always uses the dark themeYou can also set uiStyle on the container div with the data-ui-style attribute:
<div id=\"storyteller-row\" data-ui-style=\"dark\"></div>\nreloadData(): Promise<void>\nreloadData loads the view's Stories or Clips from the API again. When the request finishes, the view updates its tiles, starts prefetching content, and updates the read status of its Stories or Clips. The view calls onDataLoadStarted and then onDataLoadComplete on its delegate, with the result of the request. Clips views load the first page again. The promise resolves when loading finishes.
const storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id');\nstoryRow.reloadData();\ndestroy(): void\nCall destroy before you remove or replace the view's container, for example when a single-page application changes route. The view removes what it rendered, removes its player container when no other view uses it, stops loading content and calling its delegate, and stops following theme changes. Calling destroy again does nothing. To show content in the same element again, create a new view. destroy is available on every view from version 11.0.0.
storyRow.destroy();\nFor React and Next.js, see Use React or Next.js.
"},{"location":"StorytellerListView/#openstory-openstorybyexternalid-openpage-opencollection-openclipbyexternalid","title":"openStory, openStoryByExternalId, openPage, openCollection, openClipByExternalId","text":"These methods, and openCategory, are on Storyteller.sharedInstance, not on views.
Learn more
See Open a player programmatically for examples, and Use additional SDK methods for the full signatures.
"},{"location":"StorytellerListViewDelegate/","title":"Handle view callbacks","text":"Each view has its own delegate for events from that view: loading its content and closing its player. StorytellerStoriesRowView, StorytellerStoriesGridView, StorytellerClipsRowView, and StorytellerClipsGridView use the list view delegate, typed IListViewDelegate. For events from every player, such as analytics, see Handle global callbacks.
StorytellerClipsPlayerView and StorytellerEmbeddedClipsPlayerView use the Clips player delegate, typed IStorytellerClipsPlayerDelegate, through the same delegate property. It adds a callback for the back button.
Set the delegate property on the view you want to observe. Assigning a new object replaces the view's previous delegate.
const storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id');\nstoryRow.delegate = {\n // Add the callbacks you need, for example:\n onDataLoadComplete: (success, error, dataCount) => {\n if (!success) {\n console.error('Stories could not load.', error);\n }\n },\n};\nconst clipPlayer = new Storyteller.StorytellerClipsPlayerView(\n 'clips-player-id',\n { externalId: 'clip-external-id' }\n);\nclipPlayer.topLevelBackButtonEnabled = true;\nclipPlayer.delegate = {\n onTopLevelBackTapped: () => {\n window.history.back();\n },\n};\nFor the Clips player views' initialization, sizing, and back button, see Add a Clips player to a page.
"},{"location":"StorytellerListViewDelegate/#delegate-methods","title":"Delegate callbacks","text":"All callbacks are optional.
"},{"location":"StorytellerListViewDelegate/#ondataloadstarted","title":"onDataLoadStarted","text":"onDataLoadStarted?: () => void;\nCalled when the view starts loading its Stories or Clips.
"},{"location":"StorytellerListViewDelegate/#ondataloadcomplete","title":"onDataLoadComplete","text":"onDataLoadComplete?: (success: boolean, error: Error | null, dataCount: number) => void;\nCalled when the view finishes loading its content:
success: true when content loaded. false when the request failed or returned no Stories or Clips.error: an Error when success is false, otherwise null. The SDK doesn't export its error classes, so check error.message.dataCount: the number of Stories loaded, or the number of Clips in the first page. Later Clips pages load without calling onDataLoadStarted or onDataLoadComplete. A Clips player that shows one Clip reports 1.onPlayerDismissed?: () => void;\nCalled when a Story or Clips player opened from this view is dismissed.
"},{"location":"StorytellerListViewDelegate/#clips-player-delegate","title":"Clips player delegate","text":"IStorytellerClipsPlayerDelegate has the same callbacks as IListViewDelegate, and adds onTopLevelBackTapped.
onTopLevelBackTapped?: () => void;\nCalled when the user taps the back button at the top of a StorytellerClipsPlayerView or StorytellerEmbeddedClipsPlayerView whose topLevelBackButtonEnabled is true.
The back button doesn't call onPlayerDismissed. If you don't define onTopLevelBackTapped, the button calls window.history.back(). When topLevelBackButtonEnabled is false or not set, the button stays hidden and doesn't call onTopLevelBackTapped.
interface IListViewDelegate {\n onDataLoadStarted?: () => void;\n\n onDataLoadComplete?: (\n success: boolean,\n error: Error | null,\n dataCount: number\n ) => void;\n\n onPlayerDismissed?: () => void;\n}\n\ninterface IStorytellerClipsPlayerDelegate extends IListViewDelegate {\n onTopLevelBackTapped?: () => void;\n}\nThe Storyteller Web Showcase hides a feed module when onDataLoadComplete reports a failure or no content, in handleDataLoadComplete.
A row shows Story or Clip tiles in one horizontal line that users can scroll. Use StorytellerStoriesRowView for Stories and StorytellerClipsRowView for Clips. To show a row only when it has content, check getStoriesCount or getClipsCount first.
Create the row with the ID of an existing element on your page. Rows take the same arguments as the other views in Configure views:
"},{"location":"StorytellerRowView/#stories-initialization","title":"Stories initialization","text":"const storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id'); // All Categories\nconst storyRowWithCategories = new Storyteller.StorytellerStoriesRowView(\n 'stories-row-id',\n ['category-1', 'category-2']\n);\nconst clipsRow = new Storyteller.StorytellerClipsRowView(\n 'clips-row-id',\n 'clip-collection-id'\n);\nNote
The row sizes its tiles to the height of its container. Set a height on the container, for example <div id=\"stories-row-id\" style=\"height: 200px\"></div>. If the container has no height, the SDK uses a default tile height (160 px for square tiles, and 120 px or 140 px for round tiles, depending on whether titles show). When logging is enabled, the SDK also logs a warning.
Set a row's options with its configuration object. TypeScript examples assume import * as Storyteller from '@getstoryteller/storyteller-sdk-javascript'; and import type { IListConfiguration } from '@getstoryteller/storyteller-sdk-javascript';.
const customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id');\nstoryRow.configuration = {\n categories: ['category1', 'category2', 'category3'], // Stories only\n cellType: Storyteller.CellType.round, // StorytellerStoriesRowView only\n displayLimit: 10,\n preload: true, // Stories only\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nconst customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id');\nconst storyRowConfiguration: IListConfiguration<'StorytellerStoriesRowView'> = {\n categories: ['category1', 'category2', 'category3'], // Stories only\n cellType: Storyteller.CellType.round, // StorytellerStoriesRowView only\n displayLimit: 10,\n preload: true, // Stories only\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nstoryRow.configuration = storyRowConfiguration;\nFor a working React component that applies these options, see the Storyteller Web Showcase's StorytellerStoriesRowView.
const customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst clipsRow = new Storyteller.StorytellerClipsRowView(\n 'clips-row-id',\n 'collection-id'\n);\nclipsRow.configuration = {\n displayLimit: 10,\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nclipsRow.cellType = Storyteller.CellType.round; // Clips rows set cellType on the view\nconst customTheme = new Storyteller.UiTheme(); // See Customize themes\nconst clipsRow = new Storyteller.StorytellerClipsRowView(\n 'clips-row-id',\n 'collection-id'\n);\nconst clipsRowConfiguration: IListConfiguration<'StorytellerClipsRowView'> = {\n displayLimit: 10,\n theme: customTheme,\n uiStyle: Storyteller.UiStyle.dark,\n};\nclipsRow.configuration = clipsRowConfiguration;\nclipsRow.cellType = Storyteller.CellType.round; // Clips rows set cellType on the view\nFor Clips, the Storyteller Web Showcase's StorytellerClipsRowView builds the row configuration with the collection ID, display limit, and theme.
Rows accept every setting in Configure views, plus the following:
"},{"location":"StorytellerRowView/#celltype","title":"cellType","text":"cellType sets the tile shape: Storyteller.CellType.square (default) or Storyteller.CellType.round.
configuration.clipsRow.cellType. configuration doesn't accept cellType for Clips rows.data-cell-type=\"round\" to the container.A theme sets the colors, font, spacing, and controls of Storyteller views and players. You can set a theme in two places:
Storyteller.sharedInstance.theme, applies to every view and player on the page.theme in that view's configuration, changes one view and the player it opens.Both take a UiTheme object. Storyteller also applies a remote theme: theme settings that Storyteller configures for your tenant or for a feed. The remote theme controls captions, compact Clip action buttons, and Clip like and share counts. You can't change these settings with UiTheme.
Set the global theme after initialize resolves:
Storyteller.sharedInstance.initialize('demo-api-key').then(() => {\n const myTheme = new Storyteller.UiTheme();\n myTheme.light.colors.primary = '#FF2D00';\n myTheme.dark.colors.primary = '#FF2D00';\n\n Storyteller.sharedInstance.theme = myTheme;\n});\nThe SDK applies the theme when you assign it, and views that already exist update. If you change a property later, assign the theme again.
"},{"location":"Themes/#set-a-views-theme","title":"Set a view's theme","text":"To style one view differently, set theme in its configuration:
const storiesRow = new Storyteller.StorytellerStoriesRowView(\n 'storyteller-stories-row',\n ['category-id']\n);\n\nconst rowTheme = new Storyteller.UiTheme();\nrowTheme.light.lists.row.tileSpacing = 4;\nrowTheme.dark.lists.row.tileSpacing = 4;\n\nstoriesRow.configuration = { theme: rowTheme };\nLearn more
For all view configuration options, see Configure views.
The Storyteller Web Showcase builds a static theme in buildBasicTheme.
For each UiTheme property, the SDK uses the first value it finds:
configuration.themeStoryteller.sharedInstance.themeThe view's theme is merged over the global theme. A view theme value that equals the default doesn't override the global value.
initialize resets the global theme. Each initialize call, including a call after the user changes, sets Storyteller.sharedInstance.theme back to the defaults. Set the global theme after initialize resolves, and set it again after any later initialize call. A theme in a view's configuration is kept.
The remote theme is separate from UiTheme, and UiTheme values don't override it:
false.true.A UiTheme has two properties:
light: the Theme used in light modedark: the Theme used in dark modeThe view's uiStyle selects which one applies: light, dark, or auto. With auto, the view follows the browser's prefers-color-scheme setting. Set a property in both light and dark when it should not change with the color scheme.
The Theme object contains every property you can customize.
Some properties take their default value from others. For example, setting colors.primary to #FF0000 also colors the unread indicator on rectangular tiles red. The tables mark these properties with \"inherits\".
Future SDK versions may use a property for more elements.
"},{"location":"Themes/#colors","title":"Colors","text":"The colors property sets the base colors that the SDK uses.
primary #1C62EB string - CSS color property The default accent color used throughout the UI. In general, this should be the primary brand color. success #3BB327 string - CSS color property Used to indicate correct answers in Quizzes. alert #E21219 string - CSS color property Used to indicate incorrect answers in Quizzes. white.primary #FFFFFF string - CSS color property Used for white text white.secondary white.primary at 85% opacity string - CSS color property Used for light text white.tertiary white.primary at 70% opacity string - CSS color property Used for gray text black.primary #1A1A1A string - CSS color property Used for black text black.secondary black.primary at 85% opacity string - CSS color property Used for light black text black.tertiary black.primary at 70% opacity string - CSS color property Used for gray text focusIndicator colors.primary string - CSS color property Used for the focus outlines of interactive elements"},{"location":"Themes/#font","title":"Font","text":"Set font to a CSS font-family value to use a custom font throughout the SDK. The default value is inherit.
The primitives object contains base values that the SDK uses throughout.
cornerRadius 4 number The corner radius in pixels used for rectangular tiles, buttons, and Poll/Quiz answers"},{"location":"Themes/#lists","title":"Lists","text":"The lists property sets the layout of rows and grids.
lists.backgroundColor inherits colors.white.primary for light, colors.black.primary for dark string - CSS color property Used for the outline on the Live chip and the fade at the sides of a row. lists.row.tileSpacing 8 number The (external) space between each Story Tile in a row lists.row.startInset 12 number The (external) space before the first Story Tile in a row lists.row.endInset 12 number The (external) space after the last Story Tile in a row lists.row.startPadding 0 number The (internal) space before the first Story Tile in a row lists.row.endPadding 0 number The (internal) space after the last Story Tile in a row lists.row.showScrollIndicator true boolean Whether the scroll indicator should be visible on non-touch screens (it's always hidden on touch screens) lists.row.scrollIndicatorBackgroundColor white string - CSS color property The background color of the scroll indicator lists.row.scrollIndicatorColor rgba(26, 26, 26, 0.7) string - CSS color property The color of the scroll indicator icon. Ignored if scrollIndicatorIcon is set lists.row.scrollIndicatorIcon undefined string - image URL URL of a custom scroll indicator icon. HTML strings are not supported. lists.row.scrollIndicatorFade true boolean Used to show/hide the fade overlay on the edges of the Story row lists.row.scrollIndicatorInlineAlignment inside inside, outside Whether the scroll arrows should appear on top of the row (inside) or next to it (outside). lists.grid.tileSpacing 8 number The space between each Story Tile in a grid, both vertically and horizontally lists.grid.columns 2 number The number of columns in a grid lists.grid.topInset 12 number The space before the first row in a grid lists.grid.bottomInset 12 number The space after the last row in a grid lists.grid.startInset 16 number The space on the left side of a grid lists.grid.endInset 16 number The space on the right side of a grid"},{"location":"Themes/#story-tiles","title":"Story tiles","text":"The storyTiles property sets the appearance of Story tiles.
chip.textSize 11 number Text size for the New Indicator and Live Indicator chip.show true boolean Used to show/hide the new/live chip title.textSize 11 number Size of the Story Title on a Tile title.lineHeight 13 number The line height of the Story Title on a Tile title.alignment center Alignment (Storyteller.Alignment.start, .center, .end) The alignment of the Story Title on a Tile. Possible values are start, center and end title.fontWeight 700 number The font weight (CSS font-weight) of the Story Title on a Tile circularTile.liveChip.readImage null string - <img> src property Image to be used in place of default read Live Indicator for circular tiles circularTile.liveChip.unreadImage null string - <img> src property Image to be used in place of default unread Live Indicator for circular tiles circularTile.liveChip.readBackgroundColor inherits colors.black.tertiary string - CSS color property Background color of the circular tiles Live Indicator when all Pages have been read circularTile.liveChip.unreadBackgroundColor inherits colors.alert string - CSS color property Background color of the circular tiles Live Indicator when the Story contains unread Pages circularTile.liveChip.unreadBackgroundGradient null string - CSS gradient Background of unread Live and pinned chips on circular tiles. When set, it replaces unreadBackgroundColor. See Live chip gradient and borders circularTile.liveChip.readTextColor inherits colors.white.primary string - CSS color property Text color of the circular tiles Live Indicator when all Pages have been read circularTile.liveChip.unreadTextColor inherits colors.white.primary string - CSS color property Text color of the circular tiles Live Indicator when the Story contains unread Pages circularTile.liveChip.readBorderColor null string - CSS color property Color of the one-pixel inner border on read Live and pinned chips on circular tiles circularTile.liveChip.unreadBorderColor null string - CSS color property Color of the one-pixel inner border on unread Live and pinned chips on circular tiles circularTile.title.unreadTextColor inherits colors.black.primary for light, colors.white.primary for dark string - CSS color property The text color of the Story Title for a circular tile when the Story is unread circularTile.title.readTextColor inherits colors.black.tertiary for light, colors.white.tertiary for dark string - CSS color property The text color of the Story Title for a circular tile when the Story is read circularTile.unreadIndicatorColor inherits colors.primary string - CSS color property or linear-gradient The color of the ring around a circular tile when the Story is unread circularTile.readIndicatorColor #C5C5C5 string - CSS color property or linear-gradient The color of the ring around a circular tile when the Story is read circularTile.unreadStrokeWidth 2 number (in px) The thickness of the ring around a circular tile when the Story is unread circularTile.readStrokeWidth 1 number (in px) The thickness of the ring around a circular tile when the Story is read circularTile.scrollIndicatorBlockAlignment cell cell, thumbnail Whether the scroll arrows should be centered with the whole cell (including the titles), or with the thumbnail. rectangularTile.liveChip.readImage null string - <img> src property Image to be used in place of default read Live Indicator for rectangular tiles rectangularTile.liveChip.unreadImage null string - <img> src property Image to be used in place of default unread Live Indicator for rectangular tiles rectangularTile.liveChip.readBackgroundColor inherits colors.black.tertiary string - CSS color property Background color of the rectangular tiles Live Indicator when all Story Pages have been read or the Clip has been viewed rectangularTile.liveChip.unreadBackgroundColor inherits colors.alert string - CSS color property Background color of the rectangular tiles Live Indicator when the Story contains unread Pages or the Clip has not been viewed rectangularTile.liveChip.unreadBackgroundGradient null string - CSS gradient Background of unread Live and pinned chips on rectangular tiles. When set, it replaces unreadBackgroundColor. See Live chip gradient and borders rectangularTile.liveChip.readTextColor inherits colors.white.primary string - CSS color property Text color of the rectangular tiles Live Indicator when all Story Pages have been read or the Clip has been viewed rectangularTile.liveChip.unreadTextColor inherits colors.white.primary string - CSS color property Text color of the rectangular tiles Live Indicator when the Story contains unread Pages or the Clip has not been viewed rectangularTile.liveChip.readBorderColor null string - CSS color property Color of the one-pixel inner border on read Live and pinned chips on rectangular tiles rectangularTile.liveChip.unreadBorderColor null string - CSS color property Color of the one-pixel inner border on unread Live and pinned chips on rectangular tiles rectangularTile.title.textColor inherits colors.white.primary string - CSS color property The text color of the Story Title for a rectangular tile rectangularTile.padding 8 number The internal padding for a rectangular Story tile rectangularTile.chip.alignment end Alignment (Storyteller.Alignment.start, .center, .end) Alignment of the New Indicator and Live Indicator in Rectangular Tiles, can be start, center or end. rectangularTile.unreadIndicator.image null string - <img> src property An image which can be used in place of the default unread indicator for a rectangular tile rectangularTile.unreadIndicator.backgroundColor inherits colors.primary string - CSS color property The background color of the unread indicator for a rectangular tile rectangularTile.unreadIndicator.textColor inherits colors.white.primary string - CSS color property The text color of the unread indicator for a rectangular tile rectangularTile.showWebStoriesIcon false boolean Set this to true to show a Story icon on rectangular thumbnails rectangularTile.showGradient true boolean Set this to false to hide the gradient behind the Story title on rectangular cells"},{"location":"Themes/#live-chip-gradient-and-borders","title":"Live chip gradient and borders","text":"The Stories API can supply customLiveChipText for a Live Story or pinnedChipText for a pinned Story. The SDK uses that text in the Story tile chip. These fields come from Story content; they are separate from UiTheme. Use the chip theme properties below to style their background and border on round or rectangular tiles.
Both circularTile.liveChip and rectangularTile.liveChip accept these extra properties:
unreadBackgroundGradient: A CSS gradient string. Its default is null. A set value replaces unreadBackgroundColor on unread Live or pinned chips.readBorderColor: A CSS color for the one-pixel inner border on a read Live or pinned chip. Its default is null.unreadBorderColor: A CSS color for the one-pixel inner border on an unread Live or pinned chip. Its default is null.The player property sets options for the Story player.
disableUrls false boolean Disable the hash URLs when opening a Story. Note that this will also disable sharing. showStoryIcon true boolean Shows the Story icon in the Player showShareButton true boolean Shows the share button in the Player. Setting this to false entirely disables sharing in Storyteller actionButton.icon null string - image URL URL of a 20 \u00d7 20 px custom icon to display in the action buttons. HTML strings are not supported. actionButton.showOnMobile true boolean Shows the action button on top of the player on small screens. If set to false, the action button will only be shown if there is sufficient space to display it underneath the player. actionButton.alignment center ButtonAlignment (Storyteller.ButtonAlignment.left, .center, .right) Sets the alignment of the action button on small screens. Possible values are left, center and right. If there is enough space for the button to sit underneath the player, it will always be centered. icons.back null string - image URL or data string An image to be used in place of the default Clips player back/close icon icons.share null string - image URL or data string Not used by the Web SDK. An image to be used in place of the default share icon playAllStories false boolean Set this to true to stop the player from closing after all unread Stories have been viewed "},{"location":"Themes/#clip-player","title":"Clips player","text":"The clipPlayer property sets options for the Clips player.
To change the back or close icon at the top left of the Clips player, use player.icons.back.
disableUrls false boolean Disable the hash URLs when opening a Clip. Note that this will also disable sharing. showShareButton true boolean Shows the share button in the Player. Setting this to false entirely disables sharing. showLikeButton true boolean Shows the like button in the Player. showFeedTitle true boolean Shows the feed title or feed title image in the Clips player header. showClipTitle true boolean Shows the active Clip title in the Clips player metadata. showNavigationCategories true boolean Shows Clip navigation categories and the active category title in the Clips player header. The remote theme sets whether the Clips player shows like and share counts. A feed's showLikeCount or showShareCount value overrides the tenant value for that feed. If the feed doesn't set a field, the tenant value applies, and then the default, true. UiTheme doesn't include these fields. Before version 11.0, the SDK ignored them, so tenants whose remote theme already sets them see the change after the update.
showClipTitle: false hides the Clip title. A long description supplied with the Clip remains available in the expandable details.
The remote theme field behavior.player.clipsActionButtonCompactSize sets the size of Clip action buttons. When it is true, the Clips player shows smaller action buttons in the Clip details area. When it is false, the buttons span the width below the Clip. If the remote theme doesn't set it, the value is false.
To change it, ask Storyteller to set it for the feed. Before version 11.0, the SDK ignored this field, so feeds that already set it show compact buttons after the update. UiTheme still sets the button styles through player.actionButton and buttons.
Captions stay off until Storyteller turns them on for Stories, Clips, or both. The CC button then appears on Clips and on supported Story Pages, even when the content has no caption track. It stays available while a track loads and after an empty or failed response. A missing or unavailable track does not interrupt playback. Ads and Poll or Quiz Pages hide the CC button.
Caption text appears when a Clip or Story Page has a WebVTT track with an active cue. Clip captions appear after the Clip starts playing and stay visible while it is paused. Clips that are preloaded or not in view keep their captions hidden. Live Clips show the CC button but no caption text.
The user's caption choice applies to both Clips and Stories. When functional cookies are allowed (enableFunctionalCookies, see Control privacy and tracking), the SDK stores the choice in the browser. Otherwise, the choice lasts until the page reloads.
Story captions appear near the top of each supported Page. Poll and Quiz Pages hide both the caption text and the CC button. The CC button sits 16 px from the lower-right corner of the Story. On a Page with an action button, it moves up to 72 px from the bottom. Caption text changes as soon as the next cue starts.
Caption styling comes from the remote theme, not from UiTheme. Each valid caption field in the feed's remote theme overrides the same field in the tenant's remote theme. A missing or invalid feed field uses the tenant value, then the default in the table below. The horizontal and vertical padding follow this rule separately.
Version 11.0 changed this behavior. Earlier versions used the feed's caption settings as one object whenever the feed had them, and their defaults were 18 px text, a 22 px line height, and a #000000 background. If your captions relied on those defaults, check them after you update.
Captions align to the start edge of the surrounding text direction: left for LTR and right for RTL. Each rendered line has its own background, including lines created by wrapping. The background height includes the text line height and vertical padding. A 2 px gap separates consecutive backgrounds.
lineHeight controls the text area. The SDK adds padding and the gap when it places the next line. Padding and corner radius accept zero.
font System font stack Caption font family, with system-font fallback textSize 16 Font size in pixels lineHeight Natural font height Line height in pixels textColor #FFFFFF Caption text color backgroundColor #171A25 Caption background color backgroundOpacity 0.65 Background opacity from 0 to 1 padding.horizontal 10 Left and right padding in pixels padding.vertical 4 Top and bottom padding in pixels cornerRadius 8 Background corner radius in pixels"},{"location":"Themes/#buttons","title":"Buttons","text":"The buttons property sets the style of buttons throughout the SDK.
backgroundColor inherits colors.white.primary string - CSS color property The background color of buttons throughout the SDK textColor inherits colors.black.primary string - CSS color property The text color of buttons throughout the SDK textCase default TextCase (Storyteller.TextCase.upper, .lower, .default) Sets the text case for buttons throughout the SDK. Possible values are upper, lower and default cornerRadius inherits primitives.cornerRadius number The corner radius for all buttons throughout the SDK"},{"location":"Themes/#instructions","title":"Instructions","text":"The instructions property sets the appearance of the instructions screen.
show true boolean Determines whether the Instructions Screen is shown the first time a user opens the Story player. Set to false to completely disable the instructions screen. headingColor inherits colors.black.primary for light, colors.white.primary for dark string - CSS color property The color of the heading text on the Instructions Screen iconColor inherits headingColor string - CSS color property The foreground color of the built-in instruction icons iconHighlightColor inherits colors.primary string - CSS color property The highlight color of the built-in instruction icons subHeadingColor inherits colors.black.secondary for light, colors.white.secondary for dark string - CSS color property The color of the subheading text on the Instructions Screen backgroundColor inherits colors.white.primary for light, colors.black.primary for dark string - CSS color property The color of the background of the Instructions Screen icons {} object with optional forward, back, swipe, pause image URLs A set of custom icons to be used for each instruction on the Instructions Screen button.backgroundColor inherits colors.black.primary for light, colors.white.primary for dark string - CSS color property The background color of the button used on the Instructions Screen button.textColor inherits colors.white.primary for light, colors.black.primary for dark string - CSS color property The text color of the button used on the Instructions Screen iconColor and iconHighlightColor recolor every built-in instruction icon. This includes the pointer icons on non-touch devices and the touch and swipe icons on touch devices. By default, the icon color follows headingColor and the highlight follows colors.primary. These properties don't change the heading or subheading text colors.
const theme = new Storyteller.UiTheme();\n\ntheme.light.colors.primary = '#ff2d00'; // Built-in icon highlights inherit this\ntheme.light.instructions.iconColor = '#2b2929';\ntheme.dark.instructions.iconColor = '#f5f2f2';\n\nStoryteller.sharedInstance.theme = theme;\nUse icons to replace the image for any instruction. A custom image replaces the built-in icon and its theme colors for that instruction. Built-in icons without a custom image still follow the theme colors. Use 48 \u00d7 48 px PNG images:
const theme = new Storyteller.UiTheme();\nconst customIcons = {\n forward: './icon-forward-custom.png',\n pause: './icon-pause-custom.png',\n back: './icon-back-custom.png',\n swipe: './icon-swipe-custom.png',\n};\n\ntheme.light.instructions.icons = customIcons;\ntheme.dark.instructions.icons = customIcons;\n\nStoryteller.sharedInstance.theme = theme;\nengagementUnits)","text":"The engagementUnits property sets the style of Polls and Quizzes.
poll.answerTextColor inherits colors.black.primary string - CSS color property The text color used for Poll Answers poll.percentBarColor #CDD0DC string - CSS color property The background color of the percentage bar in Poll Answers poll.selectedAnswerBorderColor inherits colors.white.tertiary string - CSS color property The border color applied to the selected Poll Answer poll.answeredMessageTextColor inherits colors.white.tertiary string - CSS color property The color of the vote count shown to users after they select a Poll Answer poll.selectedAnswerBorderImage null string or null Not used by the Web SDK. A border image for the selected Poll Answer. The Web SDK uses selectedAnswerBorderColor poll.showVoteCount true boolean Shows the approximate number of Poll Answers after a user selects an answer. If this is set to false, the message \"Thanks for voting!\" is displayed instead poll.showPercentBarBackground false boolean Not used by the Web SDK. Adds a striped background under the percentage bar in Poll Answers triviaQuiz.correctColor inherits colors.success string - CSS color property The color used to show correct answers in Quizzes triviaQuiz.incorrectColor inherits colors.alert string - CSS color property The color used to show incorrect answers in Quizzes "},{"location":"Themes/#example","title":"Example","text":"const theme = new Storyteller.UiTheme({\n light: {\n colors: {\n primary: 'blue',\n success: 'green',\n },\n },\n});\n\n// Setting theme by direct property access\ntheme.light.colors.primary = 'red';\n\n// Applying light/dark mode specific values\ntheme.light.instructions.headingColor = 'black';\ntheme.dark.instructions.headingColor = 'white';\n\nStoryteller.sharedInstance.theme = theme;\nThe SDK keeps a user ID in the browser to remember what each user has read, liked, voted on, and answered. This page shows how to use your own user IDs, change users, set user attributes for personalization, and set the Clips language.
"},{"location":"Users/#user-ids","title":"User IDs","text":"If you don't pass an externalId the first time you call initialize, the SDK creates an anonymous user ID and stores it in the browser's local storage. With the default privacy options, the SDK uses this ID to keep track of:
You don't need extra code for this. Initialize the SDK:
await Storyteller.sharedInstance.initialize('demo-api-key');\nNote
Replace demo-api-key with your Storyteller Web SDK API key. To request one, email hello@getstoryteller.com.
If your site has user accounts, pass your own user ID as externalId in the second initialize argument:
await Storyteller.sharedInstance.initialize('demo-api-key', {\n externalId: 'your-user-id',\n});\nWith the default privacy options, initialize loads the viewing history that Storyteller saved for this ID: read Pages, Clip likes and views, and Poll and Quiz answers. The history follows the user to every browser and device where they sign in with the same externalId.
Use an ID that is unique to the user and never changes, such as your account ID. Avoid values that can change, such as an email address.
Call initialize as soon as you know the externalId, for example on page load or when a user signs in.
Note
The SDK hashes the externalId before it stores or sends it, to support Video Privacy Protection Act (VPPA) compliance.
When a user signs out, or another user signs in, call initialize again with the new externalId. Pass null when the user continues anonymously. A call without externalId keeps the current user ID, so it doesn't sign a user out.
async function onSignIn(userId) {\n await Storyteller.sharedInstance.initialize('demo-api-key', {\n externalId: userId,\n });\n}\n\nasync function onSignOut() {\n await Storyteller.sharedInstance.initialize('demo-api-key', {\n externalId: null,\n });\n}\nWhen the user ID changes, the SDK:
null, the user starts with an empty historyEvery initialize call also resets Storyteller.sharedInstance.theme to its defaults. Set the global theme again after the call resolves. A theme set in a view's configuration is kept.
The Storyteller Web Showcase's persistUserIdAndReload helper shows how to store, clear, and apply a user ID.
User attributes let you personalize rows and grids and target Stories to groups of users. For more information, see Personalization and Audience Targeting in the Storyteller User Guide.
"},{"location":"Users/#setting-user-attributes","title":"Set user attributes","text":"To set a user attribute, call setUserAttribute on Storyteller.User with the attribute key and its value. For example, to set the user's location:
Storyteller.User.setUserAttribute('location', 'New York');\nThe SDK adds the attribute, with the key location and the value New York, to its requests to Storyteller. Use it to personalize or target Stories in the Storyteller CMS.
To set more attributes, call setUserAttribute once for each key. Keys and values must be non-empty strings; otherwise the method throws an error. When enablePersonalization is false, the SDK doesn't store attributes.
Note
Set user attributes after initialize resolves. A user change during initialize clears them.
To remove a user attribute, call removeUserAttribute on Storyteller.User with the attribute key. For example, to remove the user's location:
Storyteller.User.removeUserAttribute('location');\nNote
When a user signs out and you don't call initialize again, remove each attribute you set.
To set the language for Clips, call setLocale on Storyteller.User with a language code. For example, to set the language to Spanish:
Storyteller.User.setLocale('es');\nThe SDK stores the language code as the stLocale user attribute, so it follows the same rules as other user attributes.
The Storyteller Web Showcase's persistAndApplyAttributeValues helper shows how to use these user attributes.
This page lists the ad events that the SDK sends to onUserActivityOccurred, when each one is recorded, and its properties. The Storyteller Web Showcase handles these events in its onUserActivityOccurred handler.
The tables list the properties of ads shown in Stories. Ads shown in Clips include collection, clipHasAction, clipActionText, and clipActionUrl instead of categories, categoryDetails, currentCategory, pageHasAction, pageActionText, and pageActionUrl. For those ads, adType is clips and adPlacement is betweenClips.
openedAd)","text":"The openedAd event is recorded when:
This event contains the following properties:
Event Property Property Name Description Sample values Ad IDadId The ID of the Ad for which the event occurred. be772f10-177e-4754-ac09-f91cb547316f Ad Placement adPlacement The placement of the ad which is being presented to the user. betweenClips, betweenPages, betweenStories, betweenStoriesAndPages Ad Strategy adStrategy The placement of the ad as a display label. Between Clips, Between Pages, Between Stories, Between Stories and Pages Ad Type adType Whether the ad appeared in Stories or Clips. stories, clips Advertiser Name advertiserName The advertiser name of the Ad for which the event occurred. If no name is supplied, the advertiser URL will be used. Disney+, Hulu, https://nike.com, \u2026 Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the ad event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Content Length contentLength In milliseconds, the total duration of the Page content. 15000, 41000, 32000 Opened Reason openedReason The action which the user took to open the ad. OpenedReason Page Type pageType The type of Page associated with the event. image, video Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page Action Text pageActionText If the ad associated with the event has an action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the ad associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/AdEvents/#dismissed-ad-dismissedad","title":"Dismissed Ad (dismissedAd)","text":"The dismissedAd event is recorded when:
This event contains the following properties:
Event Property Property Name Description Sample values Ad IDadId The ID of the Ad for which the event occurred. be772f10-177e-4754-ac09-f91cb547316f Ad Placement adPlacement The placement of the ad which is being presented to the user. betweenClips, betweenPages, betweenStories, betweenStoriesAndPages Ad Strategy adStrategy The placement of the ad as a display label. Between Clips, Between Pages, Between Stories, Between Stories and Pages Ad Type adType Whether the ad appeared in Stories or Clips. stories, clips Advertiser Name advertiserName The advertiser name of the Ad for which the event occurred. If no name is supplied, the advertiser URL will be used. Disney+, Hulu, https://nike.com, \u2026 Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the ad event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Content Length contentLength In milliseconds, the total duration of the Page content. 15000, 41000, 32000 Dismissed Reason dismissedReason The reason the ad was dismissed. DismissedReason Page Type pageType The type of Page associated with the event. image, video Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page Action Text pageActionText If the ad associated with the event has an action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the ad associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/AdEvents/#paused-ad-page-pausedadpage","title":"Paused Ad Page (pausedAdPage)","text":"The pausedAdPage event is recorded when a user pauses a Page within an Ad by pressing and holding on the Page, or by using the Story playback controls.
This event contains the following properties:
Event Property Property Name Description Sample values Ad IDadId The ID of the Ad for which the event occurred. be772f10-177e-4754-ac09-f91cb547316f Ad Placement adPlacement The placement of the ad which is being presented to the user. betweenClips, betweenPages, betweenStories, betweenStoriesAndPages Ad Strategy adStrategy The placement of the ad as a display label. Between Clips, Between Pages, Between Stories, Between Stories and Pages Ad Type adType Whether the ad appeared in Stories or Clips. stories, clips Advertiser Name advertiserName The advertiser name of the Ad for which the event occurred. If no name is supplied, the advertiser URL will be used. Disney+, Hulu, https://nike.com, \u2026 Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the ad event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Type pageType The type of Page associated with the event. image, video Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page Action Text pageActionText If the ad associated with the event has an action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the ad associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/AdEvents/#resumed-ad-page-resumedadpage","title":"Resumed Ad Page (resumedAdPage)","text":"The resumedAdPage event is recorded when a user resumes playing a Page within an Ad by releasing their long press which paused the Ad, or by using the Story playback controls.
This event contains the following properties:
Event Property Property Name Description Sample values Ad IDadId The ID of the Ad for which the event occurred. be772f10-177e-4754-ac09-f91cb547316f Ad Placement adPlacement The placement of the ad which is being presented to the user. betweenClips, betweenPages, betweenStories, betweenStoriesAndPages Ad Strategy adStrategy The placement of the ad as a display label. Between Clips, Between Pages, Between Stories, Between Stories and Pages Ad Type adType Whether the ad appeared in Stories or Clips. stories, clips Advertiser Name advertiserName The advertiser name of the Ad for which the event occurred. If no name is supplied, the advertiser URL will be used. Disney+, Hulu, https://nike.com, \u2026 Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the ad event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Type pageType The type of Page associated with the event. image, video Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page Action Text pageActionText If the ad associated with the event has an action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the ad associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/AdEvents/#finished-ad-finishedad","title":"Finished Ad (finishedAd)","text":"The finishedAd event is recorded at the same time as dismissedAd, skippedAd, and viewedAdPageComplete, and gives an easier way to determine when an ad finishes for any reason. In the Clips player, it is also recorded when a user swipes away from an Ad.
This event contains the following properties:
Event Property Property Name Description Sample values Ad IDadId The ID of the Ad for which the event occurred. be772f10-177e-4754-ac09-f91cb547316f Ad Placement adPlacement The placement of the ad which is being presented to the user. betweenClips, betweenPages, betweenStories, betweenStoriesAndPages Ad Strategy adStrategy The placement of the ad as a display label. Between Clips, Between Pages, Between Stories, Between Stories and Pages Ad Type adType Whether the ad appeared in Stories or Clips. stories, clips Advertiser Name advertiserName The advertiser name of the Ad for which the event occurred. If no name is supplied, the advertiser URL will be used. Disney+, Hulu, https://nike.com, \u2026 Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the ad event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Type pageType The type of Page associated with the event. image, video Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page Action Text pageActionText If the ad associated with the event has an action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the ad associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/AdEvents/#skipped-ad-skippedad","title":"Skipped Ad (skippedAd)","text":"The skippedAd event is recorded when:
This event contains the following properties:
Event Property Property Name Description Sample values Ad IDadId The ID of the Ad for which the event occurred. be772f10-177e-4754-ac09-f91cb547316f Ad Placement adPlacement The placement of the ad which is being presented to the user. betweenClips, betweenPages, betweenStories, betweenStoriesAndPages Ad Strategy adStrategy The placement of the ad as a display label. Between Clips, Between Pages, Between Stories, Between Stories and Pages Ad Type adType Whether the ad appeared in Stories or Clips. stories, clips Advertiser Name advertiserName The advertiser name of the Ad for which the event occurred. If no name is supplied, the advertiser URL will be used. Disney+, Hulu, https://nike.com, \u2026 Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the ad event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Type pageType The type of Page associated with the event. image, video Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page Action Text pageActionText If the ad associated with the event has an action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the ad associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/AdEvents/#ad-action-button-tapped-adactionbuttontapped","title":"Ad Action Button Tapped (adActionButtonTapped)","text":"The adActionButtonTapped event is recorded when:
This event contains the following properties:
Event Property Property Name Description Sample values Ad IDadId The ID of the Ad for which the event occurred. be772f10-177e-4754-ac09-f91cb547316f Ad Placement adPlacement The placement of the ad which is being presented to the user. betweenClips, betweenPages, betweenStories, betweenStoriesAndPages Ad Strategy adStrategy The placement of the ad as a display label. Between Clips, Between Pages, Between Stories, Between Stories and Pages Ad Type adType Whether the ad appeared in Stories or Clips. stories, clips Advertiser Name advertiserName The advertiser name of the Ad for which the event occurred. If no name is supplied, the advertiser URL will be used. Disney+, Hulu, https://nike.com, \u2026 Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the ad event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Type pageType The type of Page associated with the event. image, video Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page Action Text pageActionText If the ad associated with the event has an action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the ad associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/AdEvents/#viewed-ad-page-first-quartile-viewedadpagefirstquartile","title":"Viewed Ad Page First Quartile (viewedAdPageFirstQuartile)","text":"The viewedAdPageFirstQuartile event is recorded when a user reaches 1/4 of the way through the duration of an Ad Page.
This event contains the following properties:
Event Property Property Name Description Sample values Ad IDadId The ID of the Ad for which the event occurred. be772f10-177e-4754-ac09-f91cb547316f Ad Placement adPlacement The placement of the ad which is being presented to the user. betweenClips, betweenPages, betweenStories, betweenStoriesAndPages Ad Strategy adStrategy The placement of the ad as a display label. Between Clips, Between Pages, Between Stories, Between Stories and Pages Ad Type adType Whether the ad appeared in Stories or Clips. stories, clips Advertiser Name advertiserName The advertiser name of the Ad for which the event occurred. If no name is supplied, the advertiser URL will be used. Disney+, Hulu, https://nike.com, \u2026 Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the ad event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Type pageType The type of Page associated with the event. image, video Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page Action Text pageActionText If the ad associated with the event has an action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the ad associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/AdEvents/#viewed-ad-page-midpoint-viewedadpagemidpoint","title":"Viewed Ad Page Midpoint (viewedAdPageMidpoint)","text":"The viewedAdPageMidpoint event is recorded when a user reaches halfway through the duration of an Ad Page.
This event contains the following properties:
Event Property Property Name Description Sample values Ad IDadId The ID of the Ad for which the event occurred. be772f10-177e-4754-ac09-f91cb547316f Ad Placement adPlacement The placement of the ad which is being presented to the user. betweenClips, betweenPages, betweenStories, betweenStoriesAndPages Ad Strategy adStrategy The placement of the ad as a display label. Between Clips, Between Pages, Between Stories, Between Stories and Pages Ad Type adType Whether the ad appeared in Stories or Clips. stories, clips Advertiser Name advertiserName The advertiser name of the Ad for which the event occurred. If no name is supplied, the advertiser URL will be used. Disney+, Hulu, https://nike.com, \u2026 Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the ad event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Type pageType The type of Page associated with the event. image, video Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page Action Text pageActionText If the ad associated with the event has an action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the ad associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/AdEvents/#viewed-ad-page-third-quartile-viewedadpagethirdquartile","title":"Viewed Ad Page Third Quartile (viewedAdPageThirdQuartile)","text":"The viewedAdPageThirdQuartile event is recorded when a user reaches 3/4 of the way through the duration of an Ad Page.
This event contains the following properties:
Event Property Property Name Description Sample values Ad IDadId The ID of the Ad for which the event occurred. be772f10-177e-4754-ac09-f91cb547316f Ad Placement adPlacement The placement of the ad which is being presented to the user. betweenClips, betweenPages, betweenStories, betweenStoriesAndPages Ad Strategy adStrategy The placement of the ad as a display label. Between Clips, Between Pages, Between Stories, Between Stories and Pages Ad Type adType Whether the ad appeared in Stories or Clips. stories, clips Advertiser Name advertiserName The advertiser name of the Ad for which the event occurred. If no name is supplied, the advertiser URL will be used. Disney+, Hulu, https://nike.com, \u2026 Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the ad event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Type pageType The type of Page associated with the event. image, video Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page Action Text pageActionText If the ad associated with the event has an action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the ad associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/AdEvents/#viewed-ad-page-complete-viewedadpagecomplete","title":"Viewed Ad Page Complete (viewedAdPageComplete)","text":"The viewedAdPageComplete event is recorded when a user reaches the end of the duration of an Ad Page.
This event contains the following properties:
Event Property Property Name Description Sample values Ad IDadId The ID of the Ad for which the event occurred. be772f10-177e-4754-ac09-f91cb547316f Ad Placement adPlacement The placement of the ad which is being presented to the user. betweenClips, betweenPages, betweenStories, betweenStoriesAndPages Ad Strategy adStrategy The placement of the ad as a display label. Between Clips, Between Pages, Between Stories, Between Stories and Pages Ad Type adType Whether the ad appeared in Stories or Clips. stories, clips Advertiser Name advertiserName The advertiser name of the Ad for which the event occurred. If no name is supplied, the advertiser URL will be used. Disney+, Hulu, https://nike.com, \u2026 Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the ad event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Type pageType The type of Page associated with the event. image, video Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page Action Text pageActionText If the ad associated with the event has an action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the ad associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/ClipEvents/","title":"Clip Events","text":"This page lists the Clip events that the SDK sends to onUserActivityOccurred, when each one is recorded, and its properties. The Storyteller Web Showcase handles these events in its onUserActivityOccurred handler.
In openedClip, dismissedClip, and finishedClip, categories holds the names of the Clip's categories. In the other Clip events, it holds the categories' external IDs. Use categoryDetails when you need both.
Clip activity callbacks include a captionsEnabled boolean with the caption choice at the time of the event. Stories and Clips share that choice. The SDK saves it in the browser when functional storage is allowed. With functional storage disabled, the choice lasts until the page reloads.
The player also records an event when the user changes that choice:
enabledClipCaptions when the user turns captions ondisabledClipCaptions when the user turns captions offBoth events contain the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions are enabled after the interaction. true, false Categories categories A list of the external IDs of the categories assigned to the Clip. [\"game-0012200025\", \"recap\"] Category Details categoryDetails A list of Category Detail objects. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The Clip's one-based index in the active feed. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip contains an Action. true, false Clip Action Text clipActionText The Clip's Call To Action text, when present. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl The URL associated with the Clip's Action, when present. https://example.com/action"},{"location":"analytics/ClipEvents/#opened-clip-openedclip","title":"Opened Clip (openedClip)","text":"The openedClip event is recorded when:
openCollectionThe event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Clip for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Clip. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Content Length contentLength In seconds, the total duration of the Clip. 15, 21, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action Opened Reason openedReason The action which the user took to open the Clip. OpenedReason"},{"location":"analytics/ClipEvents/#dismissed-clip-dismissedclip","title":"Dismissed Clip (dismissedClip)","text":"The dismissedClip event is recorded when a user taps on the back button in the top left to exit the Clips player (and is at the top of the stack of Clip Categories).
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Clip for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Clip. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action Dismissed Reason dismissedReason The reason the Clip was dismissed. DismissedReason Clips Viewed clipsViewed The total number of Clips a user has viewed since the most recent openedClip event with an openedReason of clipListTap or deepLink. 1, 2, 3, \u2026 Duration Viewed durationViewed In milliseconds, the duration the user viewed the Clips player for, measured from the most recent openedClip event with an openedReason of clipListTap or deepLink. 1200, \u2026 Loops Viewed loopsViewed The total number of loops (plays of an individual Clip) a user has viewed since the most recent openedClip event with an openedReason of clipListTap or deepLink. 1, 2, 3, \u2026"},{"location":"analytics/ClipEvents/#finished-clip-finishedclip","title":"Finished Clip (finishedClip)","text":"The finishedClip event is recorded at the same time as openedCategory, dismissedClip, nextClip, or previousClip.
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Clip for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Clip. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Content Length contentLength In seconds, the total duration of the Clip. 15, 21, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action Duration Viewed durationViewed In milliseconds, the duration the user viewed the Clips player for, measured from the most recent openedClip event with an openedReason of swipe. 1200, \u2026 Loops Viewed loopsViewed The total number of loops (plays of an individual Clip) a user has viewed since the most recent openedClip event with an openedReason of swipe. 1, 2, 3, \u2026"},{"location":"analytics/ClipEvents/#next-clip-nextclip","title":"Next Clip (nextClip)","text":"The nextClip event is recorded when a user swipes up to go to the next Clip.
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the external IDs of the categories assigned to the Clip for which the event occurred. [\"game-0012200025\", \"recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Clip. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/ClipEvents/#previous-clip-previousclip","title":"Previous Clip (previousClip)","text":"The previousClip event is recorded when a user swipes down to go to the previous Clip.
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the external IDs of the categories assigned to the Clip for which the event occurred. [\"game-0012200025\", \"recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Clip. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/ClipEvents/#completed-loop-completedloop","title":"Completed Loop (completedLoop)","text":"The completedLoop event is recorded when a user completes a loop of a Clip. It is never recorded for live Clips.
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the external IDs of the categories assigned to the Clip for which the event occurred. [\"game-0012200025\", \"recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Clip. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/ClipEvents/#action-button-tapped-actionbuttontapped","title":"Action Button Tapped (actionButtonTapped)","text":"The actionButtonTapped event is recorded when a user taps the action button at the bottom of a Clip.
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the external IDs of the categories assigned to the Clip for which the event occurred. [\"game-0012200025\", \"recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Clip. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/ClipEvents/#share-button-tapped-sharebuttontapped","title":"Share Button Tapped (shareButtonTapped)","text":"The shareButtonTapped event is recorded when a user taps the share button on a Clip.
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the external IDs of the categories assigned to the Clip for which the event occurred. [\"game-0012200025\", \"recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Clip. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/ClipEvents/#share-success-sharesuccess","title":"Share Success (shareSuccess)","text":"The shareSuccess event is recorded when a user successfully shares a Clip.
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the external IDs of the categories assigned to the Clip for which the event occurred. [\"game-0012200025\", \"recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Clip. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action Share Method shareMethod Always an empty string for Clips. ''"},{"location":"analytics/ClipEvents/#paused-clip-pausedclip","title":"Paused Clip (pausedClip)","text":"The pausedClip event is recorded when a user taps on the screen while a Clip is playing to pause the Clip. It is not recorded when a Clip pauses automatically because the user shares it or follows an action. It is never recorded for live Clips, because live Clips cannot be paused or resumed.
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the external IDs of the categories assigned to the Clip for which the event occurred. [\"game-0012200025\", \"recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Clip. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/ClipEvents/#resumed-clip-resumedclip","title":"Resumed Clip (resumedClip)","text":"The resumedClip event is recorded when a user taps a paused Clip to resume playback. It is not recorded when a Clip resumes automatically, for example after the user finishes sharing it. It is never recorded for live Clips, because live Clips cannot be paused or resumed.
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the external IDs of the categories assigned to the Clip for which the event occurred. [\"game-0012200025\", \"recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Clip. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/ClipEvents/#liked-clip-likedclip","title":"Liked Clip (likedClip)","text":"The likedClip event is recorded when a user taps the like button on a Clip they have not liked.
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the external IDs of the categories assigned to the Clip for which the event occurred. [\"game-0012200025\", \"recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Clip. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/ClipEvents/#unliked-clip-unlikedclip","title":"Unliked Clip (unlikedClip)","text":"The unlikedClip event is recorded when a user taps the like button on a Clip they have liked.
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the external IDs of the categories assigned to the Clip for which the event occurred. [\"game-0012200025\", \"recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Clip. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/ClipEvents/#opened-category-openedcategory","title":"Opened Category (openedCategory)","text":"The openedCategory event is recorded when:
Opening the Clips player with openCollection(collectionId, { categoryId }) shows the Clips of that Category without recording this event.
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the external IDs of the categories assigned to the Clip for which the event occurred. [\"game-0012200025\", \"recap\"] Category Details categoryDetails A list with the Category Detail object of the Category being navigated to. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Category ID categoryId The ID of the Category being navigated to. 012200025, 12312452, \u2026 Category Name categoryName The name of the Category being navigated to. \u201cMust See Moments\u201d, \u201cRapid Replay\u201d, \u2026 Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/ClipEvents/#dismissed-category-dismissedcategory","title":"Dismissed Category (dismissedCategory)","text":"The dismissedCategory event is recorded when a user navigates back to the previous Category with the back button. It is not recorded when the user dismisses the top level Collection.
The event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the external IDs of the categories assigned to the Clip for which the event occurred. [\"game-0012200025\", \"recap\"] Category Details categoryDetails A list with the Category Detail object of the Category being dismissed. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Category ID categoryId The ID of the Category being dismissed. 012200025, 12312452, \u2026 Category Name categoryName The name of the Category being dismissed. \u201cMust See Moments\u201d, \u201cRapid Replay\u201d, \u2026 Collection collection The ID of the Collection, if the Clip is being played from one. live-stories, top-stories, \u2026 Clip ID clipId The ID of the Clip for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Clip Index clipIndex The index of the Clip in the row or grid at the point it was selected, or the index of the Clip in the feed at the point it was viewed (if the Clip wasn\u2019t opened from a row or grid). This property uses 1-based indexing. 1, 2, 3, \u2026 Clip Title clipTitle The title of the Clip for which the event occurred. \"Highlights\", \"Tonight's Movies\" Clip Has Action clipHasAction Whether the Clip associated with the event contains an Action. true, false Clip Action Text clipActionText If the Clip associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cWatch Now\u201d, \u2026 Clip Action URL clipActionUrl If the Clip associated with the event has an Action, the URL to which the Action links. https://example.com/action"},{"location":"analytics/PollEvents/","title":"Poll Events","text":"This page lists the Poll event that the SDK sends to onUserActivityOccurred, when it is recorded, and its properties. The Storyteller Web Showcase handles these events in its onUserActivityOccurred handler.
votedPoll)","text":"The votedPoll event is recorded when a user votes in a Poll.
This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Poll Answer ID pollAnswerId The ID of the Answer the user selected as their vote. be772f10-177e-4754-ac09-f91cb547316f Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cGame Day: 532CE Greens v Blues\u201d"},{"location":"analytics/QuizEvents/","title":"Quiz Events","text":"This page lists the Quiz events that the SDK sends to onUserActivityOccurred, when each one is recorded, and its properties. The Storyteller Web Showcase handles these events in its onUserActivityOccurred handler.
triviaQuizQuestionAnswered)","text":"The triviaQuizQuestionAnswered event is recorded when:
This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cGame Day: 532CE Greens v Blues\u201d Trivia Quiz Answer ID triviaQuizAnswerId The ID of the Trivia Quiz Answer the user selects. If the user times out or exits the Story view, this should be an empty GUID. be772f10-177e-4754-ac09-f91cb547316f Trivia Quiz ID triviaQuizId The ID of the Trivia Quiz with which the user is interacting. be772f10-177e-4754-ac09-f91cb547316f Trivia Quiz Question ID triviaQuizQuestionId The ID of the Trivia Quiz question with which the user is interacting. 9c1d7e62-4a5b-4f0e-8d3a-2b6f1c0e7a94 Trivia Quiz Title triviaQuizTitle The Title of the Trivia Quiz with which the user is interacting. \u201cWho is the greatest quarterback of all time?\u201d"},{"location":"analytics/QuizEvents/#trivia-quiz-completed-triviaquizcompleted","title":"Trivia Quiz Completed (triviaQuizCompleted)","text":"The triviaQuizCompleted event is recorded when a user completes a Trivia Quiz. It therefore fires at the same time as the final triviaQuizQuestionAnswered event for that Quiz, and is only fired once per user per Quiz.
This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cGame Day: 532CE Greens v Blues\u201d Trivia Quiz ID triviaQuizId The ID of the Trivia Quiz with which the user is interacting. be772f10-177e-4754-ac09-f91cb547316f Trivia Quiz Score triviaQuizScore The score of the Trivia Quiz, once completed. 2, 5, 9 Trivia Quiz Title triviaQuizTitle The Title of the Trivia Quiz with which the user is interacting. \u201cWho is the greatest quarterback of all time?\u201d"},{"location":"analytics/StoryEvents/","title":"Story Events","text":"This page lists the Story events that the SDK sends to onUserActivityOccurred, when each one is recorded, and its properties. The Storyteller Web Showcase handles these events in its onUserActivityOccurred handler.
Story and Page activity callbacks that identify a Story or Page include a captionsEnabled boolean. The value records the caption choice when the event occurs. Stories and Clips share that choice. The SDK saves it in the browser when functional storage is allowed. With functional storage disabled, the choice lasts until the page reloads.
The player emits enabledStoryCaptions for an enabled choice or disabledStoryCaptions for a disabled choice. Each toggle event includes the resulting captionsEnabled value, plus the active Story and Page identifiers, titles, one-based indexes, category information, and Page action fields.
captionsEnabled true or false for the resulting choice. categories Names of the categories assigned to the Story. categoryDetails A list of objects with name, id, type, and optional externalId and string placement. currentCategory An object with title, optional id, and optional string placement. storyId, storyTitle, storyDisplayTitle, storyIndex, storyPageCount The active Story and its one-based index. pageId, pageTitle, pageType, pageIndex The active Page and its one-based index. pageHasAction, pageActionText, pageActionUrl Action details for the active Page."},{"location":"analytics/StoryEvents/#opened-story-openedstory","title":"Opened Story (openedStory)","text":"The openedStory event is recorded when:
This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Opened Reason openedReason The action which the user took to open the Story. OpenedReason Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Read Status storyReadStatus Whether the Story was read or unread at the point it was opened. read, unread Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d"},{"location":"analytics/StoryEvents/#dismissed-story-dismissedstory","title":"Dismissed Story (dismissedStory)","text":"The dismissedStory event is recorded when:
Esc keyThis event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Dismissed Reason dismissedReason The reason the Story was dismissed. DismissedReason Duration Viewed durationViewed In milliseconds, how long the user viewed Stories, measured from the most recent openedStory event with an openedReason of storyListTap or deepLink. The timer resets after each dismissedStory event. 1200, 1312, 29 Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Pages Viewed pagesViewed The total number of Pages the user has viewed since the most recent openedStory event with an openedReason of storyListTap or deepLink. The count resets after each dismissedStory event. 1, 2, 3, 4 Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d"},{"location":"analytics/StoryEvents/#skipped-story-skippedstory","title":"Skipped Story (skippedStory)","text":"The skippedStory event is recorded when:
This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d"},{"location":"analytics/StoryEvents/#completed-story-completedstory","title":"Completed Story (completedStory)","text":"The completedStory event is recorded when the final Page in a Story is opened. The openedPage event is recorded at the same time.
This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d"},{"location":"analytics/StoryEvents/#opened-page-openedpage","title":"Opened Page (openedPage)","text":"The openedPage event is recorded when a user first opens a Page.
This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Content Length contentLength In seconds, the total duration of the Page content. 15, 41, 32 Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Opened Reason openedReason The action which the user took to open the Page. OpenedReason Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d"},{"location":"analytics/StoryEvents/#action-button-tapped-actionbuttontapped","title":"Action Button Tapped (actionButtonTapped)","text":"The actionButtonTapped event is recorded when:
This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d"},{"location":"analytics/StoryEvents/#share-button-tapped-sharebuttontapped","title":"Share Button Tapped (shareButtonTapped)","text":"The shareButtonTapped event is recorded when a user taps the share button on a Page.
This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d"},{"location":"analytics/StoryEvents/#share-success-sharesuccess","title":"Share Success (shareSuccess)","text":"The shareSuccess event is recorded when a user finishes sharing a Page. This happens when the promise returned by your onShareButtonTapped callback resolves, when the browser share sheet completes, or when the Page media finishes downloading.
This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Share Method shareMethod How the Page was shared: as a link (shareLink) or as its media (shareMedia or share). shareLink, shareMedia, share Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d"},{"location":"analytics/StoryEvents/#previous-page-previouspage","title":"Previous Page (previousPage)","text":"The previousPage event is recorded when a user taps back to go to a previous Page in the Story.
This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d"},{"location":"analytics/StoryEvents/#previous-story-previousstory","title":"Previous Story (previousStory)","text":"The previousStory event is recorded when:
dismissedStory is recorded instead)This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d"},{"location":"analytics/StoryEvents/#completed-page-completedpage","title":"Completed Page (completedPage)","text":"The completedPage event is recorded when a Page finishes and the player moves on to the next Page or Story automatically. The event describes the Page that finished.
ActivityType lists this event as deprecated, but the SDK still sends it. Avoid building new reports on it.
This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Content Length contentLength In seconds, the total duration of the Page content. 15, 41, 32 Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d"},{"location":"analytics/StoryEvents/#skipped-page-skippedpage","title":"Skipped Page (skippedPage)","text":"The skippedPage event is recorded when a user taps or swipes forward to leave a Page before it finishes. The event describes the Page the user left.
ActivityType lists this event as deprecated, but the SDK still sends it. Avoid building new reports on it.
This event contains the following properties:
Event Property Property Name Description Sample values Captions EnabledcaptionsEnabled Whether captions were on when the event occurred. true, false Categories categories A list of the category names assigned to the Story for which the event occurred. [\"Top Stories\", \"Europe\", \"Recap\"] Category Details categoryDetails A list of Category Detail objects assigned to the Story for which the event occurred. [{ name: 'Greens v Blues, 10/06/2022', id: '0012200025', externalId: 'game-0012200025', type: 'game', placement: 'Game Screen' }] Current Category currentCategory The Category for the Story with which the user is interacting. This event property includes the Category's name (title), external ID (id), and placement. { title: 'Greens v Blues, 10/06/2022', id: 'game-0012200025', placement: 'Game Screen' } Page Action Text pageActionText If the Page associated with the event has an Action, this property captures its associated \u2018Call To Action\u2019 text. \u201cSwipe Up\u201d, \u201cGet Started\u201d Page Action URL pageActionUrl If the Page associated with the event has an Action, the URL to which the Action links. https://example.com/action Page Has Action pageHasAction Whether the Page associated with the event contains an Action. true, false Page ID pageId The ID of the Page for which the event occurred. cce4f2c3-c6f2-4a0a-9d8c-b52e4080e658 Page Index pageIndex The index of the Page in the Story for which the event occurred. Ads do not affect this index. This property uses 1-based indexing. 1, 2, 3, \u2026 Page Title pageTitle The title of the Page for which the event occurred. \u201cStats page\u201d, \u201cBest Fit\u201d Page Type pageType The type of Page associated with the event. image, video, poll, triviaQuiz Story ID storyId The ID of the Story for which the event occurred. 3241dbc1-ae7b-4b55-a236-1294f18e2584 Story Index storyIndex The index of the Story for which the event occurred in the row from which it was opened, at the point it was opened. This property uses 1-based indexing. 1, 2, 3, \u2026 Story Page Count storyPageCount The number of Pages in the Story. 1, 2, 3, \u2026 Story Playback Mode storyPlaybackMode Whether the Story was opened with a Storyteller.sharedInstance.open* method or its URL (singleStory), or by the user tapping it in a row or grid (list). list, singleStory Story Title storyTitle The title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d Story Display Title storyDisplayTitle The long display title of the Story for which the event occurred. \u201cTonight\u2019s Movies\u201d, \u201cQuote of the Day\u201d"},{"location":"delegates/","title":"Handle delegates and callbacks","text":"A delegate is an object of callback functions that the SDK calls when something happens. Storyteller has one global delegate, and each view has its own delegate. Every callback is optional.
"},{"location":"delegates/#delegate-types","title":"Delegate types","text":"What you want to handle TypeScript type Where you set it Guide Analytics events, share taps, ad requests, and in-app action links from every Story and Clips playerIStorytellerDelegate Storyteller.sharedInstance.delegate Handle global callbacks Loading and player dismissal for one row or grid IListViewDelegate The row or grid's delegate property Handle view callbacks Loading, dismissal, and the back button for one Clips player view IStorytellerClipsPlayerDelegate The delegate property of a StorytellerClipsPlayerView or StorytellerEmbeddedClipsPlayerView Handle view callbacks Set the global delegate before you call initialize, so that it receives the sdkInitialized event. Assigning a delegate replaces the previous one: callbacks you leave out of the new object stop being called.
Check what you need, then choose how to install the Web SDK. Use this page if you are adding Storyteller to a website for the first time.
You need:
<div>, where the SDK can render a view.The examples use these placeholders. Replace them with your own values:
demo-api-key: your API keyyour-user-id: the ID your site uses for the signed-in usercategory-id: the ID of a Story Categorycollection-id: the ID of a Clips collectionChoose the guide that matches how your site builds its JavaScript:
The Storyteller Web Showcase is a Next.js app that uses the Web SDK. Many guides link to its source code on GitHub. The repository is private.
To open the Showcase links:
Until your account has access, Showcase links return a 404 error. If a link still returns 404, check that you accepted the invitation and that you are signed in with the account that has access. If you still can't open the source, contact support@getstoryteller.com.
Resources
"},{"location":"getting-started/#next-steps","title":"Next steps","text":"
Use this guide to update a Web SDK 10.13.x integration to 11.0.0. Version 11 keeps the 10.13 entry points, so most integration code does not change. It also has breaking changes. Read Breaking changes and make the changes that apply to you before you deploy version 11.
"},{"location":"getting-started/migrate-to-11/#record-the-current-integration","title":"Before you update","text":"Record the current integration, so you can test the update and roll it back:
initialize options and how you set and change usersRead the current version from the SDK.
console.log(Storyteller.sharedInstance.version);\nVersion 11 keeps these entry points:
@getstoryteller/storyteller-sdk-javascript package nameStoryteller browser globalStoryteller.sharedInstance.initializedist/storyteller.min.cssNamespace and named imports keep working, and the package includes TypeScript declarations.
"},{"location":"getting-started/migrate-to-11/#breaking-changes","title":"Breaking changes","text":"Each change below says what to do. Some changes apply only to certain integrations, such as self-hosted SDK files or TypeScript code.
"},{"location":"getting-started/migrate-to-11/#viewing-history-loads-from-storyteller","title":"Viewing history loads from Storyteller","text":"When enableFunctionalCookies and enableRemoteViewingStore are true (the defaults), initialize requests the current user's viewing history from Storyteller and waits for it. The history covers read Pages, Clip likes and views, and Poll and Quiz answers. History for an externalId follows the user across browsers and devices.
Read state from 10.13 carries over. With the default privacy options, 10.13 sent each opened Page, Poll vote, Quiz answer, and Clip like to Storyteller under the user ID stored in Storyteller.user. Version 11 keeps that user ID and loads the same history, so Stories that users read in 10.13 still show as read. Read state does not carry over when 10.13 ran with enableFunctionalCookies: false or enableRemoteViewingStore: false; see Local storage keys changed.
enablePersonalization: false does not stop this request. The request sends the user ID but no user attributes, as 10.13 activity events already did.
If this request fails, initialize rejects with InvalidApiKeyError, NetworkError, or NetworkTimeoutError, and the SDK does not send the sdkInitialized event.
To update:
catch on every initialize call. See Handle initialization errors.x-storyteller-recent-viewed-clip-ids to its Access-Control-Allow-Headers response.GET /api/UserActivity/* Clips pages GET /api/app/clips/{collection}/clips/paged/fresh Recently viewed Clips x-storyteller-recent-viewed-clip-ids header on Clips requests See Remote viewing store for the privacy options that control this request.
"},{"location":"getting-started/migrate-to-11/#local-storage-keys-changed","title":"Local storage keys changed","text":"Version 11 uses new local storage keys for viewing history. It does not read the 10.13 keys and does not remove them.
10.13 key 11.0 keyStoryteller.clipLikes Storyteller.likes Storyteller.clipsViewed Storyteller.viewedClips Storyteller.pollAnswerMap Storyteller.pollAnswers Storyteller.quizAnswerMap Storyteller.triviaQuizAnswers Storyteller.storiesReadMap Storyteller.readPages With the default enableRemoteViewingStore: true, the SDK keeps viewing history in Storyteller, not in local storage. With enableRemoteViewingStore: false, the SDK keeps viewing history only in the new local storage keys. Read Pages, likes, and answers that 10.13 saved do not carry over, so Stories that users read in 10.13 show as unread.
To update:
The script build now downloads Story player, Clips player, Poll, Quiz, and caption code as separate files the first time a page needs them. It loads them from the directory that served storyteller.min.js. The Storyteller CDN serves every file. The npm package is not affected.
If you host the SDK files yourself:
dist directory to one directory on your server.storyteller.min.js from its own <script> tag. Do not rename, bundle, or inline it.If your page has a Content Security Policy, its script-src must allow the directory that serves the SDK files, on the CDN or on your server. A policy that allows only a nonce or a hash for the main script also needs 'strict-dynamic' or the SDK host.
See Host the SDK files.
"},{"location":"getting-started/migrate-to-11/#npm-peer-dependencies-and-entry-points","title":"npm peer dependencies and entry points","text":"The npm package now declares these peer dependencies, because its TypeScript declarations import them:
@types/react: >=17 <20@types/react-router-dom: ^5.1.7npm 7 and later installs them. If npm install reports a peer dependency conflict, change your @types/react version to one in that range. See TypeScript declarations.
The package also adds import and require entry points and publishes its declarations at dist/index.npm.d.ts. It no longer ships index.js, types/*.d.ts, or SDK source files. Import only these paths:
@getstoryteller/storyteller-sdk-javascript@getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.cssA default import resolves only in ES module builds. In CommonJS builds, including Jest, use import * as Storyteller or require. Version 10.13 behaved the same way.
reflect-metadata polyfill on the page's global Reflect object. If your code calls Reflect.getMetadata or Reflect.defineMetadata, import reflect-metadata in your application.ActivityType has a new sdkInitialized member. Update exhaustive switch statements over ActivityType.Story has new pinnedChipText and customLiveChipText properties. Add them to typed test data.QuizRenderer.clearQuizData() method was removed. Remove any calls to it.These changes need no code, but check them in your application:
preload to true to prepare more of the Story player in advance.onDataLoadComplete callback reports the number of Clips in the first page as dataCount. Later pages load without delegate callbacks.clipsActionButtonCompactSize, the Clips player shows smaller action buttons.showLikeCount or showShareCount to false, the Clips player hides that count.#171A25 background instead of 18 px text, a 22 px line height, and a #000000 background.sdkInitialized event: onUserActivityOccurred receives sdkInitialized during initialize. If your handler maps every event type, make it ignore or record this one.Install version 11.0.0.
npm install @getstoryteller/storyteller-sdk-javascript@11.0.0\nIf npm reports a peer dependency conflict, see npm peer dependencies and entry points.
Keep the SDK and stylesheet imports together.
import * as Storyteller from '@getstoryteller/storyteller-sdk-javascript';\nimport '@getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css';\nChange the version segment in the CDN URL.
<script src=\"https://content.usestoryteller.com/javascript-sdk/11.0.0/dist/storyteller.min.js\"></script>\nUse the fixed URL in production. This keeps later releases from changing the SDK without an application deployment.
Earlier guides showed a /javascript-sdk/latest/ URL. That path does not serve production releases. Replace it with a fixed version URL, such as the one above.
If you host the SDK files yourself, copy every file in the 11.0.0 dist directory. See The script build loads files from its directory.
Check these paths with version 11.0.0:
initialize resolves. With the default privacy options, also check that the viewing-history request succeeds in the browser's network panel.404 errors.sdkInitialized event if your application handles activity events.destroy() before it removes a view's container, and that a new view appears when the route returns.Review the release notes for other changes that apply to your integration.
"},{"location":"getting-started/migrate-to-11/#roll-back-a-test-deployment","title":"Roll back","text":"Restore the previous fixed npm version or CDN URL, then rebuild and deploy the application. If you host the SDK files, restore the 10.13 files too. Keep the previous version number in the release record until the version 11 checks pass.
Version 10.13 does not read the local storage keys that version 11 uses.
"},{"location":"getting-started/migrate-to-11/#get-help","title":"Get help","text":"If the update fails, work through Troubleshoot an integration. If you still need help, contact Storyteller Support.
"},{"location":"getting-started/npm/","title":"Install from npm","text":"Use the npm package when a bundler, such as webpack or Vite, builds your application's JavaScript. The package is @getstoryteller/storyteller-sdk-javascript.
npm install @getstoryteller/storyteller-sdk-javascript\nThe package includes TypeScript declarations. They import types from React and React Router, so the package declares these peer dependencies:
@types/react >=17 <20@types/react-router-dom ^5.1.7npm 7 and later installs peer dependencies for you. If npm install reports a peer dependency conflict, use an @types/react version in that range. The API reference lists the exported types.
Import both files from code that runs in the browser.
import * as Storyteller from '@getstoryteller/storyteller-sdk-javascript';\nimport '@getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css';\nThe stylesheet ships in the npm package. Configure your bundler to handle CSS imports.
Import only these two paths: the package root and @getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css. Version 11 no longer ships index.js, types/*.d.ts, or SDK source files, so other paths fail.
A default import (import Storyteller from '@getstoryteller/storyteller-sdk-javascript') works only in ES module builds. In CommonJS builds, including Jest, use import * as Storyteller.
The npm package includes the Story player, Clips player, Poll, Quiz, and caption code in its single JavaScript file. Your bundler decides how that code loads. The script-tag build downloads the same code on demand instead.
"},{"location":"getting-started/npm/#commonjs-browser-bundles","title":"CommonJS browser bundles","text":"The package also supports require in browser code built with CommonJS:
const Storyteller = require('@getstoryteller/storyteller-sdk-javascript');\nrequire('@getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css');\nYour bundler needs a CSS loader for the stylesheet require. Node.js can require or import the JavaScript entry, for example during server rendering, but views work only in the browser. Load the stylesheet only through your browser build.
The Storyteller Web Showcase keeps its PackagedStoryteller import and stylesheet import in one browser-only module.
await Storyteller.sharedInstance.initialize('demo-api-key');\nCall initialize and wait for it to resolve before you create a Storyteller view. Replace demo-api-key with your API key. Top-level await works only in ES modules. Otherwise, call initialize inside an async function, as shown in Handle initialization errors.
<div id=\"storyteller-stories-row\" style=\"height: 200px\"></div>\nconst storyRow = new Storyteller.StorytellerStoriesRowView(\n 'storyteller-stories-row'\n);\nCall storyRow.destroy() before your application removes or replaces the container.
Use this guide to show a Storyteller view in a React or Next.js app. Initialize the SDK once for the page, create the view after the component mounts, and destroy the view when the component unmounts.
Install the SDK with npm first.
"},{"location":"getting-started/react-nextjs/#initialize-the-sdk-once","title":"Initialize the SDK once","text":"Add a module that calls initialize once and shares its promise with every component:
// storyteller.js\nimport * as Storyteller from '@getstoryteller/storyteller-sdk-javascript';\n\nlet initialization;\n\nexport function startStoryteller() {\n if (!initialization) {\n initialization = Storyteller.sharedInstance\n .initialize('demo-api-key')\n .catch((error) => {\n initialization = undefined;\n throw error;\n });\n }\n\n return initialization;\n}\nThe first call starts initialize. Later calls return the same promise. If initialize fails, the helper clears the cached promise, so the next call tries again.
Each initialize call resets the global theme (Storyteller.sharedInstance.theme) to the defaults. If you use a global theme, set it after initialize resolves, for example in a .then() inside startStoryteller(). A theme set in a view's configuration is kept. See Customize themes.
When the signed-in user changes, call initialize again as described in Identify and personalize users, then set the global theme again.
Import the SDK, its stylesheet, and the helper:
import { useEffect } from 'react';\nimport * as Storyteller from '@getstoryteller/storyteller-sdk-javascript';\nimport '@getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css';\nimport { startStoryteller } from './storyteller';\nCreate the view after startStoryteller() resolves, and destroy it in the effect cleanup:
export function StoryRow() {\n useEffect(() => {\n let isMounted = true;\n let storyRow;\n\n startStoryteller()\n .then(() => {\n if (isMounted) {\n storyRow = new Storyteller.StorytellerStoriesRowView(\n 'storyteller-stories-row'\n );\n }\n })\n .catch((error) => console.error('Storyteller could not start.', error));\n\n return () => {\n isMounted = false;\n storyRow?.destroy();\n };\n }, []);\n\n return <div id=\"storyteller-stories-row\" style={{ height: 200 }} />;\n}\nIn development, React Strict Mode runs each effect, its cleanup, and the effect again. The cleanup sets isMounted to false, so only the second effect creates a view. Both effects get the same promise from startStoryteller(), so the SDK initializes once.
Each view needs a container ID that is unique on the page. If you render the component more than once at the same time, pass a different ID to each instance. The ID must follow the container ID rules.
"},{"location":"getting-started/react-nextjs/#nextjs-app-router","title":"Next.js App Router","text":"Import the stylesheet in app/layout.js.
import '@getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css';\nKeep the view in a Client Component so the SDK runs in the browser. Add 'use client' at the top of the component file, then use the same StoryRow component as in the React section:
'use client';\n\nimport { useEffect } from 'react';\nimport * as Storyteller from '@getstoryteller/storyteller-sdk-javascript';\nimport { startStoryteller } from './storyteller';\nThe Storyteller Web Showcase uses the same lifecycle. Its isStorytellerInitialized guard runs before view creation. Cleanup calls view.destroy().
Load the SDK from the Storyteller CDN when your site has no JavaScript build step.
"},{"location":"getting-started/script/#add-the-sdk","title":"Add the SDK","text":"Add the versioned script before the closing </body> tag, after the container, so the container exists when your code creates the view. A fixed version keeps the deployed SDK the same until you choose to update it.
<div id=\"storyteller-stories-row\" style=\"height: 200px\"></div>\n\n<script src=\"https://content.usestoryteller.com/javascript-sdk/11.0.0/dist/storyteller.min.js\"></script>\n<script>\n async function startStoryteller() {\n await Storyteller.sharedInstance.initialize('demo-api-key');\n\n new Storyteller.StorytellerStoriesRowView(\n 'storyteller-stories-row'\n );\n }\n\n startStoryteller().catch((error) => {\n console.error('Storyteller could not start.', error);\n });\n</script>\nThe script adds its styles to the page. Storyteller becomes available on window after the script loads.
Replace demo-api-key with your API key. To show Stories from specific Categories, pass their IDs as the second argument:
new Storyteller.StorytellerStoriesRowView('storyteller-stories-row', [\n 'category-id',\n]);\nNote
Earlier guides used a /javascript-sdk/latest/ URL. That path does not serve production releases. Use a fixed version URL, such as the 11.0.0 URL above.
The script downloads the Story player, Clips player, Poll, Quiz, and caption code the first time a page needs it. These files load from the same directory as storyteller.min.js, for example https://content.usestoryteller.com/javascript-sdk/11.0.0/dist/. Their names look like storyteller.story-player.<hash>.min.js.
The Storyteller CDN serves all of these files. To host the SDK on your own server:
dist directory to one directory.storyteller.min.js from its own <script> tag. Don't bundle, rename, or inline it.If your site uses a Content Security Policy (CSP), allow scripts from the SDK directory in script-src, for example https://content.usestoryteller.com/javascript-sdk/11.0.0/dist/. The SDK adds its files to the page as <script> elements without a nonce. If your policy allows scripts only by nonce or hash, also add 'strict-dynamic' or the SDK directory.
The Story player also loads the AMP Story player script from https://stories.usestoryteller.com/amp/.
A horizontal row of Story tiles appears. If the container stays empty, open the browser console and look for a failed script request or an initialization error. See Troubleshoot an integration.
The Storyteller Web Showcase builds the same versioned CDN URL in buildVersionedDemoSdkScriptUrl.
Use this page when Storyteller doesn't appear, doesn't load, or doesn't behave as expected. Find the first step that fails, and fix it before you check later steps.
"},{"location":"getting-started/troubleshooting/#find-your-symptom","title":"Find your symptom","text":"What you see Start withwindow.Storyteller is undefined, or your build can't find the package 1. Confirm that the SDK loaded initialize rejects, or isInitialized stays false 2. Confirm initialization The row or grid stays empty 3. Check an empty row or grid Tiles appear, but a Story or Clip doesn't open or play 4. Check player requests A view breaks or appears twice after a route change 5. Check page transitions A callback or analytics event doesn't arrive 6. Check callbacks and analytics A theme change has no effect 7. Check themes Ads don't appear 8. Check ads"},{"location":"getting-started/troubleshooting/#1-confirm-that-the-sdk-loaded","title":"1. Confirm that the SDK loaded","text":"For a script integration, open the browser Network panel and find storyteller.min.js. The request must return JavaScript with a successful HTTP status.
Then check the browser global.
typeof window.Storyteller;\nThe result should be \"object\".
For an npm integration, check the build output for a missing package or CSS import. The application must include both imports from the npm installation guide.
"},{"location":"getting-started/troubleshooting/#2-confirm-initialization","title":"2. Confirm initialization","text":"Call enableLogging() in your page code before you call initialize. The SDK then logs its warnings and request errors to the console.
Storyteller.sharedInstance.enableLogging();\nawait Storyteller.sharedInstance.initialize('demo-api-key');\nCheck the current state after the promise resolves.
console.log({\n isInitialized: Storyteller.sharedInstance.isInitialized,\n version: Storyteller.sharedInstance.version,\n});\nisInitialized should be true.
If initialize rejects, check the start of error.message. The SDK doesn't export these error classes, and error.name is always \"Error\".
InvalidApiKeyError A request returned HTTP 401 or 404. Confirm that the key belongs to the intended Storyteller tenant. NetworkError Inspect the settings request and the viewing-history request (GET /api/UserActivity/{userId}), their HTTP status, and the response body. Confirm that the settings response contains settings. NetworkTimeoutError Check the network path, proxy, firewall, and request timeout. With the default privacy options, initialize requests the user's viewing history from Storyteller and waits for it. If a proxy or allowlist sits between the browser and the Storyteller API, allow that request.
If the promise rejects with a text message instead of an Error, initialize was called without an API key.
Confirm each item:
Set a delegate with an onDataLoadComplete callback, as shown in Check the result. If success is false and error.message starts with EmptyResponseError, the request worked but returned no Stories or Clips.
Remove optional Category IDs from a Story view to check the default Home list. Confirm that the Story is published in that list.
new Storyteller.StorytellerStoriesRowView('storyteller-stories-row');\nIf the row appears but its tiles have the wrong size, set a height on the row container. Without one, the SDK uses a default tile height.
"},{"location":"getting-started/troubleshooting/#4-check-player-requests","title":"4. Check player requests","text":"Open a Story or Clip and inspect failed Network requests.
The script build downloads the Story player, Clips player, Poll, Quiz, and caption files the first time a page needs them. These files load from the directory that served storyteller.min.js, and their names start with storyteller., such as storyteller.story-player.<hash>.min.js. Check these causes:
dist directory and keep the file names. See Host the SDK files.The npm build includes this code in its own JavaScript file, so these requests don't appear.
Record the first failed request and its HTTP status. Remove API keys, user IDs, and private query values before you share the request.
"},{"location":"getting-started/troubleshooting/#5-check-page-transitions","title":"5. Check page transitions","text":"Destroy each view before a single-page application removes its container.
storyRow.destroy();\nDestroy the old view before you create a new one in the same container. Two views on the page at the same time need different container IDs. Initialize the SDK once for the page, as shown in Use React or Next.js.
"},{"location":"getting-started/troubleshooting/#6-check-callbacks-and-analytics","title":"6. Check callbacks and analytics","text":"Check the global delegate (IStorytellerDelegate):
Storyteller.sharedInstance.delegate before you call initialize. The sdkInitialized event is sent during initialize.onUserActivityOccurred, onShareButtonTapped, getAdConfig, and userNavigatedToApp. A callback you leave out stops working. Define all callbacks in one object, or spread the current delegate.onUserActivityOccurred receives events only when enableUserActivityTracking is true. Ad events also need enableAdTracking.eventTrackingOptions assignment replaces all options. An option you leave out returns to its default.Storyteller.sharedInstance.delegate = {\n ...Storyteller.sharedInstance.delegate,\n getAdConfig: () => ({ slot: '/1234/your-ad-unit' }),\n};\nFor a view delegate (IListViewDelegate), set delegate on the view object. A view starts loading while its constructor runs, so a delegate you assign after new doesn't receive the first onDataLoadStarted call. onDataLoadComplete still arrives.
See Handle delegates and callbacks, Integrate analytics, and Control privacy and tracking.
"},{"location":"getting-started/troubleshooting/#7-check-themes","title":"7. Check themes","text":"configuration is merged over the global theme (Storyteller.sharedInstance.theme) for that view only.initialize call resets the global theme to its defaults. Set the global theme after initialize resolves, and set it again after a later initialize call, such as a user change.uiStyle selects the light or dark theme. With auto, the default, the view follows the user's color scheme, so set both theme.light and theme.dark.Test one clearly visible property on a single view before you combine overrides. See Customize themes.
"},{"location":"getting-started/troubleshooting/#8-check-ads","title":"8. Check ads","text":"Ask Storyteller which ad source your tenant uses. Storyteller First Party Ads need no code. For Google Ad Manager ads, check these items:
getAdConfig on the global delegate. It must return an object with a slot for both Story and Clip requests. null means no ad.story field. They contain clip, nextClip, and collection. A callback that reads adRequestInfo.story without a check throws for Clips.slot must serve 1x1 ads.getAdConfig. See step 6.enableAdTracking: false, ad requests don't include the current Story or Clip, so line items that target them might not match.See Integrate ads.
"},{"location":"getting-started/troubleshooting/#contact-support","title":"Contact support","text":"Send Storyteller Support this information:
Remove API keys, user IDs, tenant data, and ad-targeting values from logs and screenshots.
"},{"location":"reference/","title":"API reference","text":"This reference lists the public API of Storyteller Web SDK 11.0.0. Each entry gives the TypeScript signature, parameters, defaults, errors, and the guide that shows the task. Use the guides to learn a workflow, and use these pages to check an exact name or type.
"},{"location":"reference/#reference-pages","title":"Reference pages","text":"The reference has four pages, organized by the part of the SDK you call:
Page Covers Storyteller instanceStoryteller.sharedInstance properties and methods, and Storyteller.User Views and configuration View constructors, view properties and methods, and the configuration interfaces Callbacks IStorytellerDelegate, IListViewDelegate, and IStorytellerClipsPlayerDelegate Types and enums Enums, event data, ad request data, theme classes, and server rendering"},{"location":"reference/#package-entry-points","title":"Package entry points","text":"The SDK ships as an npm package and as a browser script on the Storyteller CDN. Both entry points expose the same singleton, view classes, and enums.
"},{"location":"reference/#npm-package","title":"npm package","text":"Install the package from npm:
npm install @getstoryteller/storyteller-sdk-javascript\nThe package supports these import forms:
NamespaceNamedDefaultCommonJSimport * as Storyteller from '@getstoryteller/storyteller-sdk-javascript';\nimport {\n sharedInstance,\n StorytellerStoriesRowView,\n} from '@getstoryteller/storyteller-sdk-javascript';\nimport Storyteller from '@getstoryteller/storyteller-sdk-javascript';\nconst Storyteller = require('@getstoryteller/storyteller-sdk-javascript');\nThe guides use the namespace import. The import forms return the same objects:
Storyteller.sharedInstance and the named sharedInstance export are the same instanceindex.mjs) provides itindex.cjs) returns the namespace object itself, which has no default propertywindow or document, so server code can import it. Create views only in the browserThe package exports map resolves these paths:
@getstoryteller/storyteller-sdk-javascript types dist/index.npm.d.ts @getstoryteller/storyteller-sdk-javascript import index.mjs @getstoryteller/storyteller-sdk-javascript require, default index.cjs @getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css none dist/storyteller.min.css @getstoryteller/storyteller-sdk-javascript/package.json none package.json"},{"location":"reference/#stylesheet","title":"Stylesheet","text":"An npm integration must import the stylesheet once, from code that runs in the browser:
import '@getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css';\nYour bundler must handle CSS imports. See Install from npm. In a Next.js App Router project, import the stylesheet in the root layout as shown in Use React or Next.js.
"},{"location":"reference/#cdn-script","title":"CDN script","text":"Load a fixed SDK version from the Storyteller CDN:
<script src=\"https://content.usestoryteller.com/javascript-sdk/11.0.0/dist/storyteller.min.js\"></script>\nThe script defines the Storyteller global on window. It differs from the npm package in these ways:
storyteller.min.jsStorytellerTrackedFunctionalFeature is a type-only export in this build, so Storyteller.StorytellerTrackedFunctionalFeature is undefined. Pass the string values instead, such as 'all' or 'pageReadStatus'See Install with a script tag.
"},{"location":"reference/#typescript-declarations","title":"TypeScript declarations","text":"The package types entry is dist/index.npm.d.ts. It re-exports every name from dist/index.d.ts and declares the default export.
These exports are types only. Import them with import type, or reference them through the namespace, such as Storyteller.IListConfiguration:
IListConfiguration, IStorytellerClipsPlayerConfiguration, IStorytellerEmbeddedClipsPlayerConfigurationIStorytellerDelegate, IListViewDelegate, IStorytellerClipsPlayerDelegateStorytellerEventTrackingOptionsStorytellerAdRequestInfo, StorytellerStoriesAdRequestInfo, StorytellerClipsAdRequestInfoServerRenderedStory, SubsetSome parameter and return types are not exported by name, such as the initialize options and the getAdConfig return value. Derive them from an exported signature when you need a name:
import * as Storyteller from '@getstoryteller/storyteller-sdk-javascript';\n\ntype UserInput = NonNullable<\n Parameters<typeof Storyteller.sharedInstance.initialize>[1]\n>;\n\ntype GetAdConfig = NonNullable<\n Storyteller.IStorytellerDelegate['getAdConfig']\n>;\ntype AdConfig = NonNullable<ReturnType<GetAdConfig>>;\nThe declarations import types from react and react-router-dom. The package lists @types/react (>=17 <20) and @types/react-router-dom (^5.1.7) as peer dependencies.
The package exports these names. Names marked as types exist only in TypeScript.
Export Kind ReferencesharedInstance Instance Storyteller instance User Instance Storyteller.User StorytellerStoriesRowView Class Views StorytellerStoriesGridView Class Views StorytellerClipsRowView Class Views StorytellerClipsGridView Class Views StorytellerClipsPlayerView Class Views StorytellerEmbeddedClipsPlayerView Class Views RowView Deprecated alias of StorytellerStoriesRowView Views GridView Deprecated alias of StorytellerStoriesGridView Views IListConfiguration Type Configuration IStorytellerClipsPlayerConfiguration Type Configuration IStorytellerEmbeddedClipsPlayerConfiguration Type Configuration IStorytellerDelegate Type Callbacks IListViewDelegate Type Callbacks IStorytellerClipsPlayerDelegate Type Callbacks UiStyle Enum Types CellType Enum Types ActivityType Enum Types OpenedReason Enum Types DismissedReason Enum Types StorytellerTrackedFunctionalFeature Enum (npm), type (CDN) Types Alignment, ButtonAlignment, TextCase Enum Types StorytellerEventTrackingOptions Type Types UserActivityData Class Types ActivityEventDetail Class Types StorytellerAdRequestInfo Type Types StorytellerStoriesAdRequestInfo Type Types StorytellerClipsAdRequestInfo Type Types UiTheme Class Types Theme Class Types Subset Type Types ServerRenderer Instance Types ServerRenderedStory Type Types Story Class Other exports QuizRenderer Instance Other exports QuizApiService Instance Other exports"},{"location":"reference/#conventions","title":"Conventions","text":"These pages follow these conventions:
? marks an optional parameter or fieldStoryteller. With the CDN script, the same code runs against the Storyteller globaldemo-api-key and category-id. Replace them with values from your Storyteller tenantThe SDK reports events and asks for ad settings through delegate objects. You set one global delegate on Storyteller.sharedInstance, and you can set a delegate on each view. Every callback is optional. For setup steps, see Handle delegates and callbacks.
The SDK defines three delegate interfaces:
Interface Set it on CallbacksIStorytellerDelegate Storyteller.sharedInstance.delegate onUserActivityOccurred, onShareButtonTapped, getAdConfig, userNavigatedToApp IListViewDelegate The delegate of a Stories or Clips row or grid onDataLoadStarted, onDataLoadComplete, onPlayerDismissed IStorytellerClipsPlayerDelegate The delegate of a StorytellerClipsPlayerView or StorytellerEmbeddedClipsPlayerView The IListViewDelegate callbacks, plus onTopLevelBackTapped Assigning a delegate object replaces the previous one, so include every callback that you need in each assignment.
"},{"location":"reference/callbacks/#istorytellerdelegate","title":"IStorytellerDelegate","text":"interface IStorytellerDelegate {\n onUserActivityOccurred?: (\n type: ActivityType,\n data: UserActivityData\n ) => void;\n onShareButtonTapped?: (\n text: string,\n title: string,\n url: string\n ) => Promise<void>;\n getAdConfig?: (\n adRequestInfo: StorytellerAdRequestInfo\n ) => AdConfig | null;\n userNavigatedToApp?: (url: string) => void;\n}\nThe global delegate handles events from every Story and Clip player on the page.
Storyteller.sharedInstance.delegate = {\n onUserActivityOccurred: (type, data) => {\n console.log(type, data.context);\n },\n};\nonUserActivityOccurred","text":"onUserActivityOccurred?: (type: ActivityType, data: UserActivityData) => void\nCalled for each analytics event. The SDK ignores the return value.
Parameter Type Descriptiontype ActivityType The event name, such as openedStory data UserActivityData The event properties. Each event page lists the properties that it sets The privacy options control the callback:
enableUserActivityTracking is trueenableAdTracking is trueenableFullVideoAnalytics is false, the SDK sets storyId, storyTitle, storyDisplayTitle, pageId, pageTitle, clipId, and clipTitle to nulldata.context holds the view's configuration.context, unless that value is undefined. Assign the delegate before initialize to receive the sdkInitialized event.
onShareButtonTapped","text":"onShareButtonTapped?: (\n text: string,\n title: string,\n url: string\n) => Promise<void>\nCalled when a user taps the link share button in the Story player or the Clips player. Implement it to replace the browser share sheet.
Parameter Type Descriptiontext string Share text. For a Clip, the Clip description title string Share title. For a Story, the Story title. For a Clip, the Clip description url string The link to share The returned promise controls what happens next:
shareSuccess event and resumes playbackshareSuccess eventnavigator.share insteadThe player pauses while the share runs.
navigator.sharegetAdConfig","text":"getAdConfig?: (adRequestInfo: StorytellerAdRequestInfo) => AdConfig | null\nCalled before an ad request when your tenant uses a third-party ad server, such as Google Ad Manager. With Storyteller first-party ads, the SDK does not call it.
Parameter Type DescriptionadRequestInfo StorytellerAdRequestInfo The Story or Clip context of the ad slot Return an ad configuration, or null to send no ad request. The SDK uses this shape of the declared AdConfig union:
interface IntegratingAppAdConfig {\n type?: 'doubleclick';\n slot: string;\n customTargeting?: AdTargeting;\n publisherProvidedId?: string | null;\n}\n\ninterface AdTargeting {\n [index: string]: string | string[];\n}\nslot string Yes Google Ad Manager ad unit, in the form /[NETWORK_CODE]/[UNIT_CODE]. A configuration without slot is not valid customTargeting AdTargeting No Key-value pairs for the ad request. Values are strings or arrays of strings publisherProvidedId string or null No Publisher Provided ID (PPID). The SDK trims whitespace and omits an empty value type 'doubleclick' No Ad server type The SDK adds its default targeting keys and lets your customTargeting values override them. When enableAdTracking is false, the SDK omits its default keys and publisherProvidedId, and still sends your customTargeting.
AdConfig and AdTargeting are not exported by name. The declared AdConfig union also includes { type: 'custom'; remoteUrl: string }, which the SDK uses for Storyteller first-party ads. The SDK ignores that shape when your delegate returns it.
publisherProvidedId was added in 10.13.6userNavigatedToApp","text":"userNavigatedToApp?: (url: string) => void\nCalled when a user taps an in-app action on a Story Page or a Clip. Implement it to route the URL inside your application. Without this callback, in-app actions open like regular URLs.
Parameter Type Descriptionurl string The action URL set in the Storyteller CMS IListViewDelegate","text":"interface IListViewDelegate {\n onDataLoadStarted?: () => void;\n onDataLoadComplete?: (\n success: boolean,\n error: Error | null,\n dataCount: number\n ) => void;\n onPlayerDismissed?: () => void;\n}\nA view delegate handles events from one view. The SDK fills callbacks that you leave out with no-op functions.
const storyRow = new Storyteller.StorytellerStoriesRowView('stories-row-id');\n\nstoryRow.delegate = {\n onDataLoadStarted: () => console.log('Loading Stories'),\n onDataLoadComplete: (success, error, dataCount) => {\n console.log(success, error, dataCount);\n },\n};\nonDataLoadStarted","text":"onDataLoadStarted?: () => void\nCalled each time the view starts loading its content. This happens after the constructor, after a source change (categories, collection, clipId, or externalId), on reloadData, and when a Clips view refreshes after its player closes.
onDataLoadComplete","text":"onDataLoadComplete?: (\n success: boolean,\n error: Error | null,\n dataCount: number\n) => void\nCalled when the content request finishes.
Parameter Type Descriptionsuccess boolean true when the request succeeded error Error or null null on success. On failure, the request error. When the failure is not an Error, the SDK passes an Error with the message Network Error dataCount number Stories views: the number of Stories loaded. Clips views: the number of Clips in the first page. Single-Clip players: 1. 0 on failure Later Clips pages load as users reach the end of the content, and they do not call this callback. See Clips paging.
"},{"location":"reference/callbacks/#onplayerdismissed","title":"onPlayerDismissed","text":"onPlayerDismissed?: () => void\nCalled when the Story or Clip player that the view opened is dismissed. A tap on the Clips player top-level back button calls onTopLevelBackTapped instead.
IStorytellerClipsPlayerDelegate","text":"interface IStorytellerClipsPlayerDelegate extends IListViewDelegate {\n onTopLevelBackTapped?: () => void;\n}\nThe delegate of StorytellerClipsPlayerView and StorytellerEmbeddedClipsPlayerView. It supports the IListViewDelegate callbacks.
onTopLevelBackTapped","text":"onTopLevelBackTapped?: () => void\nCalled when a user taps the top-level back button. The button shows only when topLevelBackButtonEnabled is true. Without this callback, the SDK calls window.history.back().
clipPlayer.topLevelBackButtonEnabled = true;\nclipPlayer.delegate = {\n onTopLevelBackTapped: () => {\n window.history.back();\n },\n};\nStoryteller.sharedInstance is the SDK singleton. You use it to initialize the SDK, set the global delegate, theme, and privacy options, and open Stories or Clips from your own code. Storyteller.User is a second singleton that stores user attributes. The SDK creates both when the script or package loads.
Storyteller.sharedInstance has these properties:
version string Read isInitialized boolean Read-only isPlayerVisible boolean Read-only delegate IStorytellerDelegate Read and write theme Subset<IUiTheme> Read and write currentTheme IStorytellerTheme Read-only uiStyle UiStyle Read-only eventTrackingOptions StorytellerEventTrackingOptions Read and write customInstanceHost string Write-only currentApiKey string or null Read-only It has these methods:
Method Returnsinitialize(apiKey, userInput?) Promise<void> getStoriesCount(categoryIds) Promise<number> getClipsCount(collectionId) Promise<number> openStory(id) Promise<void> openStoryByExternalId(externalId) Promise<void> openPage(pageId) Promise<void> openCategory(categoryId, storyId?) Promise<void> openCollection(collectionId, destination?, openedReason?) Promise<void> openClipByExternalId(collectionId, externalId) Promise<void> dismissPlayer(animated) void disablePlayback() void enablePlayback() void enableLogging() void Deprecated members and an internal member are listed at the end of Methods.
"},{"location":"reference/storyteller/#properties","title":"Properties","text":"These properties are on Storyteller.sharedInstance.
version","text":"version: string\nThe SDK version, such as '11.0.0'. See Use additional SDK methods.
isInitialized","text":"get isInitialized(): boolean\ntrue after an initialize call succeeds. Once true, it stays true for the rest of the page session, including while a later initialize call runs.
isPlayerVisible","text":"get isPlayerVisible(): boolean\ntrue while a Story or Clip player is open, and false after it is dismissed.
delegate","text":"get delegate(): IStorytellerDelegate\nset delegate(delegateObj: IStorytellerDelegate)\nThe global callbacks for Stories, Clips, analytics, sharing, ads, and in-app links. Assigning an object replaces all four callbacks, so a callback that you leave out is cleared. Reading the property returns a new object that holds the current callbacks.
Storyteller.sharedInstance.delegate = {\n onUserActivityOccurred: (type, data) => {\n console.log(type, data.context);\n },\n};\nIStorytellerDelegatetheme","text":"get theme(): Subset<IUiTheme>\nset theme(theme: Subset<IUiTheme>)\nThe global theme for every view. Pass a UiTheme or a plain object with optional light and dark themes. A view's configuration.theme overrides the global theme for that view.
Note
Each initialize call replaces the global theme with a default UiTheme. Set theme after initialize resolves, and set it again after a later initialize call, such as a user change.
await Storyteller.sharedInstance.initialize('demo-api-key');\n\nStoryteller.sharedInstance.theme = new Storyteller.UiTheme({\n light: { colors: { primary: '#1C62EB' } },\n});\ncurrentTheme","text":"get currentTheme(): IStorytellerTheme\nThe resolved global Theme for the current color scheme. The SDK picks the light or dark theme from theme, fills unset values with SDK defaults, and rebuilds it when the system color scheme changes. The value exists after initialize runs or after you assign theme.
uiStyle","text":"get uiStyle(): UiStyle\nThe UiStyle of the global theme. The SDK also uses it for the players it creates for the open methods and hash URLs when no matching view exists on the page. On your pages the value is UiStyle.auto. Set a view's style with configuration.uiStyle.
eventTrackingOptions","text":"get eventTrackingOptions(): StorytellerEventTrackingOptions\nset eventTrackingOptions(newOptions: Partial<StorytellerEventTrackingOptions>)\nThe privacy and tracking options. Every option defaults to true, and disabledFunctionalFeatures defaults to [].
Assigning an object replaces every option: a field that you leave out returns to its default. To change one option, spread the current value:
Storyteller.sharedInstance.eventTrackingOptions = {\n ...Storyteller.sharedInstance.eventTrackingOptions,\n enableAdTracking: false,\n};\nReading the property returns the effective values. When enableFunctionalCookies is false, enablePersonalization and enableStorytellerTracking read as false. Set the options before initialize when enableRemoteViewingStore must apply to the stored user ID.
StorytellerEventTrackingOptionsenableAdTracking was added in 10.9.0 and enableFullVideoAnalytics in 10.11.0customInstanceHost","text":"set customInstanceHost(customInstanceHost: string)\nSets the API host for SDK requests in place of the default Storyteller API host. The SDK removes a trailing / and stores the value in local storage under Storyteller.customInstanceHost. The property has no getter, and no task guide covers it.
currentApiKey","text":"get currentApiKey(): string | null\nThe API key from the latest initialize call. Before that call, it returns the key stored in local storage from an earlier page load, or null when no key is stored.
These methods are on Storyteller.sharedInstance.
initialize","text":"initialize(apiKey: string, userInput?: UserInput): Promise<void>\nStarts the SDK for an API key and user. Create views after the promise resolves.
Parameter Type Required Default DescriptionapiKey string Yes None Your Storyteller Web SDK API key userInput UserInput No {} User options. Pass a plain object such as { externalId: 'user-id' } UserInput has one optional field, externalId:
class UserInput {\n constructor(public externalId?: string | null) {}\n}\nexternalId value Result A string Sets the current user. The SDK stores a SHA-256 hash of the ID. A new ID resets the user data stored in the browser, including user attributes null Clears the user ID and resets the stored user data Omitted Keeps the stored user ID. The SDK creates a random ID when none is stored, or when apiKey differs from the previous key When eventTrackingOptions.enableRemoteViewingStore is false, the SDK deletes the stored user ID and ignores externalId.
The call behaves as follows:
apiKey and externalId return the same promise. A call with different values waits for the active call to settle, then runsStoryteller has already been initialized. Reusing the existing instance.sdkInitialized activity event after the Settings request succeeds or failsThe promise rejects with these values:
Condition Rejection valueapiKey is empty and the SDK is not initialized The string Storyteller couldn't be initialized because no API key was provided. The Settings request returns HTTP 401 or 404 An Error whose message starts with InvalidApiKeyError The Settings request returns HTTP 408 An Error whose message starts with NetworkTimeoutError Any other Settings failure, including an empty response An Error whose message starts with NetworkError User setup fails The error from that step The error classes are not exported. Check the message prefix to tell them apart.
try {\n await Storyteller.sharedInstance.initialize('demo-api-key', {\n externalId: 'user-id',\n });\n} catch (error) {\n console.error('Storyteller could not start.', error);\n}\ngetStoriesCount","text":"getStoriesCount(categoryIds: string[]): Promise<number>\nReturns the number of available Stories in the given categories. The SDK sends one count request per category and adds the results.
Parameter Type Required Default DescriptioncategoryIds string[] Yes None Story category IDs 0 at once, without a requestinitialize call succeeds. The promise stays pending until thengetClipsCount","text":"getClipsCount(collectionId: string): Promise<number>\nReturns the number of available Clips in a collection.
Parameter Type Required Default DescriptioncollectionId string Yes None Clips collection ID initialize call succeeds. The promise stays pending until thenError('Collection is required to load Clips count') for an empty ID, and when the request fails or the response is empty or has no numeric countThe open methods show a Story or Clip player from your code. They share this behavior:
player.disableUrls or clipPlayer.disableUrls theme property is false.location.hash to that view's player URL, such as #top-stories/story-id.#stories/... or #clips/....location.hash. It rejects when the SDK cannot load the content or the content does not exist.The rejection value can be an Error or a string. Handle every rejection:
try {\n await Storyteller.sharedInstance.openStory('story-id');\n} catch (error) {\n console.error('The Story could not be opened.', error);\n}\nCall the open methods after initialize resolves. See Basename for the hash URL format.
openStory","text":"openStory(id: string): Promise<void>\nOpens the Story with this Story ID. The Story plays in single-Story mode.
Parameter Type Required Default Descriptionid string Yes None Story ID No Story with the provided ID was found.openStoryByExternalId","text":"openStoryByExternalId(externalId: string): Promise<void>\nOpens the Story with this external ID. The Story plays in single-Story mode.
Parameter Type Required Default DescriptionexternalId string Yes None Story external ID No Story with the provided External ID was found.openPage","text":"openPage(pageId: string): Promise<void>\nOpens the Story that contains this Page, starting at the Page.
Parameter Type Required Default DescriptionpageId string Yes None Story Page ID openCategory","text":"openCategory(categoryId: string, storyId?: string): Promise<void>\nOpens the Story player for a category. On the page, the SDK uses a Stories view whose only category is categoryId.
categoryId string Yes None Story category ID storyId string No None Story to open first. When it is missing or not in the category, the first Story in the category opens openCollection","text":"openCollection(\n collectionId: string,\n destination?: { categoryId?: string; clipId?: string },\n openedReason?: OpenedReason.deepLink\n): Promise<void>\nOpens the Clips player for a collection.
Parameter Type Required Default DescriptioncollectionId string Yes None Clips collection ID destination { categoryId?: string; clipId?: string } No None Clip or Clip category to show first. clipId takes priority when you pass both. When the destination is missing or not found, the first Clip in the collection opens openedReason OpenedReason.deepLink No Set by the SDK The OpenedReason reported in analytics events. OpenedReason.deepLink is the only accepted value destinationopenClipByExternalId","text":"openClipByExternalId(collectionId: string, externalId: string): Promise<void>\nOpens the Clips player for a collection at the Clip with this external ID. When no view on the page has the Clip, the SDK loads collection pages until it finds the Clip, up to 100 pages.
Parameter Type Required Default DescriptioncollectionId string Yes None Clips collection ID externalId string Yes None Clip external ID dismissPlayer","text":"dismissPlayer(animated: boolean): void\nCloses the open Story or Clip player. It has no effect when no player is open. The dismissed event reports DismissedReason.instanceMethod. A StorytellerEmbeddedClipsPlayerView ignores this call.
animated boolean Yes None true plays the close animation disablePlayback","text":"disablePlayback(): void\nPauses the open Story player and the active Clip video. Players that open while playback is disabled stay paused.
enablePlayback","text":"enablePlayback(): void\nAllows playback again after disablePlayback, and resumes the open Story player and the active Clip. Playback is enabled by default.
enableLogging","text":"enableLogging(): void\nTurns on SDK info, warning, and log messages in the browser console. The SDK always writes errors to the console, with or without this call.
These members still work in 11.0.0. Replace them with the members listed:
Member Behavior ReplacementopenClip(id: string, onError?: (message: string) => void): void Opens a Clip that a Clips view on the page has loaded. Calls onError with a message when no view has the Clip openCollection or openClipByExternalId enableEventTracking(): void Sets every tracking option to its default eventTrackingOptions disableEventTracking(): void Sets every tracking option to its default, except enableStorytellerTracking: false eventTrackingOptions get currentUserId(): string Always returns ''. Deprecated in 10.11.0 None"},{"location":"reference/storyteller/#internal-members","title":"Internal members","text":"The declarations include requestUserActivityHistory_(): Promise<void>. It reloads the current user's activity history, a step that initialize already runs. No guide documents it, and integrations do not need to call it.
Storyteller.User","text":"Storyteller.User stores user attributes for personalization and audience targeting. The SDK keeps them in local storage and adds them to its content requests.
Storyteller.User.setUserAttribute('location', 'New York');\nSet attributes after initialize resolves. A new externalId in initialize clears the stored attributes. See Identify and personalize users.
setUserAttribute(key, value) true, -1, or undefined getUserAttribute(key) string or undefined getUserAttributes() Record<string, string> removeUserAttribute(key) void setLocale(locale) void locale string or undefined"},{"location":"reference/storyteller/#setuserattribute","title":"setUserAttribute","text":"setUserAttribute(key: string, value: string): true | -1 | undefined\nStores one attribute. An existing value for the key is replaced.
Parameter Type Required Default Descriptionkey string Yes None Attribute name value string Yes None Attribute value true when the attribute is stored. undefined when eventTrackingOptions.enablePersonalization is false: the SDK does not store the attribute and logs a warning, which shows when logging is enabled. -1 when the stored value cannot be read backError('Key and value are required when setting user attributes') when key or value is emptygetUserAttribute","text":"getUserAttribute(key: string): string | undefined\nReturns the stored value for key, or undefined when none is stored.
getUserAttributes","text":"getUserAttributes(): IUserAttributes\nReturns all stored attributes as an object. IUserAttributes is Record<string, string>. Returns {} when none are stored.
removeUserAttribute","text":"removeUserAttribute(key: string): void\nRemoves one attribute.
setLocale","text":"setLocale(locale: string): void\nSets the Clips locale. The SDK stores it as the stLocale user attribute, so it follows the same rules as setUserAttribute.
locale string Yes None Language code, such as 'es' setUserAttribute error when locale is emptylocale","text":"get locale(): string | undefined\nThe stored stLocale attribute, or undefined.
The declarations also include parseUserAttributesToQueryStringAlphabetically(): string. The SDK uses it to build request query strings from the stored attributes.
This page lists the enums, data types, theme classes, and server rendering helpers that the SDK exports. Theme properties are covered in Customize themes, and event properties in the analytics event pages.
"},{"location":"reference/types/#enums","title":"Enums","text":"Every enum value is a string equal to its member name. In TypeScript, pass the enum member, such as Storyteller.UiStyle.dark. In JavaScript, you can also pass the string, such as 'dark'.
UiStyle","text":"enum UiStyle {\n auto = 'auto',\n light = 'light',\n dark = 'dark',\n}\nSelects the light or dark theme of a UiTheme. auto follows the system color scheme. Set it with configuration.uiStyle or the data-ui-style container attribute. See uiStyle.
CellType","text":"enum StorytellerListViewCellType {\n round = 'round',\n square = 'square',\n}\nExported as CellType. Sets the tile shape of a row. The default is square. See cellType.
ActivityType","text":"The type argument of onUserActivityOccurred. The event pages list when each event fires and its properties:
sdkInitialized SDK initialization Stories and Clips actionButtonTapped, shareButtonTapped, shareSuccess Story events, Clip events Stories openedStory, dismissedStory, skippedStory, completedStory, openedPage, previousPage, previousStory Story events Story captions enabledStoryCaptions, disabledStoryCaptions Story caption events Polls votedPoll Poll events Quizzes triviaQuizQuestionAnswered, triviaQuizCompleted Quiz events Ads openedAd, dismissedAd, pausedAdPage, resumedAdPage, finishedAd, skippedAd, adActionButtonTapped, viewedAdPageFirstQuartile, viewedAdPageMidpoint, viewedAdPageThirdQuartile, viewedAdPageComplete Ad events Clips openedClip, dismissedClip, finishedClip, nextClip, previousClip, completedLoop, pausedClip, resumedClip, likedClip, unlikedClip, openedCategory, dismissedCategory Clip events Clip captions enabledClipCaptions, disabledClipCaptions Clip caption events The source groups these values as no longer used or deprecated:
completedPage and skippedPage. The Story player still records these two events, and the event pages do not document themswipedUp, viewedPage, completedAd, swipedUpOnAd, previousAd, impression, readyToPlay, mediaStarted, bufferingStarted, bufferingEnded. The SDK does not record these eventsOpenedReason","text":"The openedReason property of open events:
storyListTap, deepLink, swipe, automaticPlayback, tap Clips clipListTap, categoryListTap, categoryBackTap, deepLink See OpenedReason for each value. openCollection accepts OpenedReason.deepLink as its third argument.
DismissedReason","text":"The dismissedReason property of dismiss events:
backgroundTapped, instanceMethod, windowUnload Stories closeButtonTapped, swipedDown, swipedFirstStory, swipedFinalStory, skippedFinalPage, completedFinalPage, backTapped, escapeKeyPressed Clips backButtonTapped See DismissedReason for each value. dismissPlayer reports instanceMethod.
StorytellerTrackedFunctionalFeature","text":"enum StorytellerTrackedFunctionalFeature {\n all = 'all',\n clipLikes = 'clipLikes',\n clipShares = 'clipShares',\n clipViewedStatus = 'clipViewedStatus',\n pageReadStatus = 'pageReadStatus',\n pollVotes = 'pollVotes',\n triviaQuizAnswers = 'triviaQuizAnswers',\n}\nThe items of eventTrackingOptions.disabledFunctionalFeatures. all disables every item. See Disabled functional features.
Note
The npm package exports this enum at runtime. The CDN script does not, so Storyteller.StorytellerTrackedFunctionalFeature is undefined there. Pass the string values instead, such as ['pageReadStatus'].
Three enums set theme properties. See Customize themes for each property:
Enum Values Theme propertiesAlignment start, center, end storyTiles.title.alignment, storyTiles.rectangularTile.chip.alignment ButtonAlignment left, center, right player.actionButton.alignment TextCase default, upper, lower buttons.textCase"},{"location":"reference/types/#privacy-options","title":"Privacy options","text":"The type of Storyteller.sharedInstance.eventTrackingOptions.
StorytellerEventTrackingOptions","text":"type StorytellerEventTrackingOptions = {\n disabledFunctionalFeatures: StorytellerTrackedFunctionalFeature[];\n enableAdTracking: boolean;\n enableFullVideoAnalytics: boolean;\n enableFunctionalCookies: boolean;\n enablePersonalization: boolean;\n enableRemoteViewingStore: boolean;\n enableStorytellerTracking: boolean;\n enableUserActivityTracking: boolean;\n};\ndisabledFunctionalFeatures [] Stops tracking the listed features enableAdTracking true false stops ad events and removes Story and Clip details from ad requests enableFullVideoAnalytics true false sets Story, Page, and Clip IDs and titles to null in callback data enableFunctionalCookies true false stops non-essential local storage, and turns off personalization and Storyteller tracking enablePersonalization true false stops sending user IDs and user attributes for personalization enableRemoteViewingStore true false keeps user IDs off backend services and keeps viewing activity on the device enableStorytellerTracking true false stops storing analytics events on Storyteller servers enableUserActivityTracking true false stops onUserActivityOccurred calls"},{"location":"reference/types/#event-data","title":"Event data","text":"The data types of analytics events.
"},{"location":"reference/types/#useractivitydata","title":"UserActivityData","text":"The data argument of onUserActivityOccurred. Every field is optional, and each event sets a subset. The event pages list the fields of each event.
context (unknown): the view's configuration.context Stories and Pages storyId, storyTitle, storyDisplayTitle, pageId, pageTitle (string, or null when enableFullVideoAnalytics is false); storyIndex, storyPageCount, pageIndex, durationViewed, pagesViewed, contentLength (number); storyReadStatus (string); storyPlaybackMode ('list' or 'singleStory'); pageType ('image', 'video', 'poll', or 'triviaQuiz'); pageHasAction (boolean); pageActionText, pageActionUrl (string or null) Navigation openedReason (OpenedReason); dismissedReason (DismissedReason); shareMethod ('share', 'shareMedia', 'shareLink', or '') Categories categories (string[]); categoryDetails (CategoryDetail[]); currentCategory (CurrentCategory); categoryId, categoryName (string) Ads adId, adStrategy (string); advertiserName (string or null); adType ('stories' or 'clips'); adPlacement ('betweenClips', 'betweenStories', 'betweenStoriesAndPages', or 'betweenPages') Polls pollAnswerId (string) Quizzes triviaQuizId, triviaQuizQuestionId, triviaQuizAnswerId, triviaQuizTitle (string); triviaQuizScore (number) Clips clipId, clipTitle (string, or null when enableFullVideoAnalytics is false); collection (string); clipActionText, clipActionUrl (string or null); clipIndex, clipsViewed, loopsViewed (number); clipHasAction (boolean) Captions captionsEnabled (boolean) SDK initialization initializationSucceeded, enableAdTracking, enableFullVideoAnalytics, enablePersonalization, enableRemoteViewingStore, enableStorytellerTracking, enableUserActivityTracking (boolean); appId, screenResolution (string or null); deviceBrand, deviceModel, operatingSystem, osVersion (string); deviceType ('Phone', 'Tablet', 'TV', or 'Desktop') The category types have these fields:
class CategoryDetail {\n name: string;\n id?: string;\n type: string;\n placement?: string;\n externalId?: string;\n}\n\nclass CurrentCategory {\n title: string;\n id?: string;\n placement?: string;\n}\nThe SDK exports UserActivityData as a class. The callback receives a plain object with these fields.
ActivityEventDetail","text":"class ActivityEventDetail {\n type: ActivityType;\n data: UserActivityData;\n constructor(type: ActivityType, data: UserActivityData);\n}\nA pair of event type and event data. The SDK exports the class, but no SDK callback receives it in 11.0.0.
"},{"location":"reference/types/#ad-request-data","title":"Ad request data","text":"The adRequestInfo argument of getAdConfig. See AdRequestInfo.
StorytellerAdRequestInfo","text":"type StorytellerAdRequestInfo =\n | StorytellerStoriesAdRequestInfo\n | StorytellerClipsAdRequestInfo;\nCheck for the story field to tell the variants apart:
const isStoryAd = (\n info: Storyteller.StorytellerAdRequestInfo\n): info is Storyteller.StorytellerStoriesAdRequestInfo => 'story' in info;\nStorytellerStoriesAdRequestInfo","text":"type StorytellerStoriesAdRequestInfo = {\n placement: string;\n categories: string[];\n story: {\n id: '';\n categories: CategoryDetail[];\n };\n};\nplacement Placement code of the Story category that matches the first category ID of the view. '' when none matches categories Category IDs of the view that shows the Story story.categories Categories of the Story, as CategoryDetail objects story.id Always ''. Deprecated See Stories AdRequestInfo.
"},{"location":"reference/types/#storytellerclipsadrequestinfo","title":"StorytellerClipsAdRequestInfo","text":"type StorytellerClipsAdRequestInfo = {\n collection: string;\n clip: {\n id: '';\n categories: ClipCategory[];\n };\n nextClip?: {\n categories: ClipCategory[];\n };\n};\ncollection Collection ID clip.categories Categories of the current Clip nextClip.categories Categories of the next Clip. nextClip is absent when no next Clip exists clip.id Always ''. Deprecated ClipCategory has these fields:
interface ClipCategory {\n id: string;\n name: string;\n externalId: string;\n placement: string | null;\n type: string;\n displayTitle: string;\n availableForNavigation: boolean;\n}\nSee Clips AdRequestInfo.
"},{"location":"reference/types/#theme-classes","title":"Theme classes","text":"The classes and types that build a theme. Customize themes lists every theme property and default.
"},{"location":"reference/types/#uitheme","title":"UiTheme","text":"class UiTheme implements IUiTheme {\n light: StorytellerTheme;\n dark: StorytellerTheme;\n constructor(baseTheme?: Subset<IUiTheme> | null);\n}\nHolds a light and a dark Theme. The constructor builds both from baseTheme, and unset properties keep their defaults. The view's UiStyle decides which theme applies. See Customize themes.
const theme = new Storyteller.UiTheme({\n light: { colors: { primary: '#1C62EB' } },\n dark: { colors: { primary: '#6699FF' } },\n});\nTheme","text":"class StorytellerTheme implements IStorytellerTheme {\n colors: StorytellerColorsTheme;\n font: string;\n primitives: StorytellerPrimitivesTheme;\n lists: StorytellerListsTheme;\n storyTiles: StorytellerTilesTheme;\n player: StorytellerPlayerTheme;\n clipPlayer: StorytellerClipPlayerTheme;\n buttons: StorytellerButtonsTheme;\n instructions: StorytellerInstructionsTheme;\n engagementUnits: StorytellerEngagementUnitsTheme;\n isDark: boolean;\n constructor(theme?: Subset<IStorytellerTheme>);\n toPlainObject(): this;\n}\nExported as Theme. One color scheme of a theme. The constructor copies the properties of theme over the defaults. The SDK sets isDark when it builds the dark theme. toPlainObject returns the instance.
colors Colors font Font primitives Primitives lists Lists storyTiles Story Tiles player Player clipPlayer Clips player buttons Buttons instructions Instructions engagementUnits Polls and Quizzes theme"},{"location":"reference/types/#subset","title":"Subset","text":"type Subset<K> = {\n [attr in keyof K]?: K[attr] extends object\n ? Subset<K[attr]>\n : K[attr] extends object | null\n ? Subset<K[attr]> | null\n : K[attr] extends object | null | undefined\n ? Subset<K[attr]> | null | undefined\n : K[attr];\n};\nA recursive Partial. Theme inputs use it, so you set only the properties that you change, at any depth.
const rowTheme: Storyteller.Subset<Storyteller.UiTheme> = {\n light: { lists: { row: { startInset: 0 } } },\n};\nThese exports build Story markup for server-side rendering. They do not use window or document.
ServerRenderer","text":"ServerRenderer.getStories(categories?: string[]): Promise<ServerRenderedStory[]>\nServerRenderer.render(stories: ServerRenderedStory[]): React.JSX.Element\nA singleton instance. getStories loads the Stories of the given categories with the API key from initialize, and keeps the Stories that have a Google Web Story URL. render returns a hidden <amp-story-player> element with a link, poster image, and title for each Story. No task guide covers these methods.
categories string[] No [] Story category IDs stories ServerRenderedStory[] Yes None Stories from getStories"},{"location":"reference/types/#serverrenderedstory","title":"ServerRenderedStory","text":"type ServerRenderedStory = {\n id: string;\n href: string;\n title: string;\n thumbnailUrl: string;\n};\nhref is the Story's Google Web Story URL.
The SDK also exports these names. No guide covers them, and integrations do not need them:
Export Kind NotesStory Class Story data model from the Stories API. No public SDK method or callback returns it in 11.0.0 QuizRenderer Instance Renders Quiz questions and results inside a Story page document. The SDK's Story page script uses its own copy QuizApiService Instance Loads Quiz data for Story pages. The SDK's Story page script uses its own copy"},{"location":"reference/views/","title":"Views and configuration","text":"A view renders Storyteller content into a container element on your page. This page lists the constructor of each view class, the properties and methods that views share, and the configuration interfaces. For layout and setup tasks, see Choose a view and Configure views.
"},{"location":"reference/views/#view-classes","title":"View classes","text":"The SDK exports six view classes:
Class Shows Content argument Configuration input DelegateStorytellerStoriesRowView Stories in a horizontal row Optional category IDs IListConfiguration<'StorytellerStoriesRowView'> IListViewDelegate StorytellerStoriesGridView Stories in a grid Optional category IDs IListConfiguration<'StorytellerStoriesGridView'> IListViewDelegate StorytellerClipsRowView Clips in a horizontal row Collection ID IListConfiguration<'StorytellerClipsRowView'> IListViewDelegate StorytellerClipsGridView Clips in a grid Collection ID IListConfiguration<'StorytellerClipsGridView'> IListViewDelegate StorytellerClipsPlayerView A Clips player mounted in the page Collection ID, { clipId }, or { externalId } IStorytellerClipsPlayerConfiguration IStorytellerClipsPlayerDelegate StorytellerEmbeddedClipsPlayerView A Clips player that fills a fixed area of the page Collection ID, { clipId }, or { externalId } IStorytellerEmbeddedClipsPlayerConfiguration IStorytellerClipsPlayerDelegate Create a view after initialize resolves, and call destroy before your application removes the container.
Each constructor takes the container element ID first. The constructor renders the view and starts loading its content.
"},{"location":"reference/views/#storytellerstoriesrowview","title":"StorytellerStoriesRowView","text":"new StorytellerStoriesRowView(\n elementId: string,\n listCategories?: string[],\n useGoogleWebStoryUrls?: boolean\n)\nelementId string Yes None ID of the container element listCategories string[] No [] Story category IDs. With no categories, the row shows the Stories in the Home list useGoogleWebStoryUrls boolean No false true turns each Story tile into a link to the Story's Google Web Story URL, when the API provides one, instead of opening the SDK player const storyRow = new Storyteller.StorytellerStoriesRowView(\n 'stories-row-id',\n ['category-id']\n);\nStorytellerStoriesGridView","text":"new StorytellerStoriesGridView(\n elementId: string,\n listCategories?: string[],\n useGoogleWebStoryUrls?: boolean\n)\nThe parameters match StorytellerStoriesRowView.
StorytellerClipsRowView","text":"new StorytellerClipsRowView(\n elementId: string,\n collectionName: string,\n useGoogleWebStoryUrls?: boolean\n)\nelementId string Yes None ID of the container element collectionName string Yes None Clips collection ID. With an empty ID, the view loads no Clips useGoogleWebStoryUrls boolean No false Accepted for parity with Stories views. It has no effect on Clips The declarations also list a fourth argument, { deferInitialization?: boolean }. The SDK's player views use it to delay loading. Leave it out: with deferInitialization: true, a row or grid never loads.
const clipsRow = new Storyteller.StorytellerClipsRowView(\n 'clips-row-id',\n 'collection-id'\n);\nStorytellerClipsGridView","text":"new StorytellerClipsGridView(\n elementId: string,\n collectionName: string,\n useGoogleWebStoryUrls?: boolean\n)\nThe parameters match StorytellerClipsRowView.
StorytellerClipsPlayerView","text":"new StorytellerClipsPlayerView(\n elementId: string,\n source: string | StorytellerClipsPlayerSource,\n useGoogleWebStoryUrls?: boolean\n)\nelementId string Yes None ID of the container element source string or StorytellerClipsPlayerSource Yes None A collection ID string, or an object with exactly one of collection, clipId, or externalId useGoogleWebStoryUrls boolean No false Accepted for parity with Stories views. It has no effect on Clips StorytellerClipsPlayerSource has three optional fields. Set exactly one of them to a non-empty value:
interface StorytellerClipsPlayerSource {\n collection?: string;\n clipId?: string;\n externalId?: string;\n}\nA collection source plays the collection and supports collection navigation. A clipId or externalId source plays one Clip.
The constructor throws an Error for an object source with more than one value or with none:
StorytellerClipsPlayerView only supports one source at a time. Provide exactly one of `collection`, `clipId`, or `externalId`. No non-empty field StorytellerClipsPlayerView requires one of `collection`, `clipId`, or `externalId`. const clipPlayer = new Storyteller.StorytellerClipsPlayerView(\n 'clips-player-id',\n { externalId: 'clip-external-id' }\n);\nStorytellerEmbeddedClipsPlayerView","text":"new StorytellerEmbeddedClipsPlayerView(\n elementId: string,\n source: string | StorytellerClipsPlayerSource,\n useGoogleWebStoryUrls?: boolean\n)\nThe class extends StorytellerClipsPlayerView, so its parameters, source rules, errors, and members match that class. It differs in these ways:
Storyteller.sharedInstance.dismissPlayer does not close itThe embedded player suits a fixed area of your layout, such as a live blog or match centre.
RowView and GridView are deprecated aliases of StorytellerStoriesRowView and StorytellerStoriesGridView. They reference the same classes. Use the full names in new code.
The constructors read the container element when you call them:
No element with ID <elementId> was found. The Storyteller view couldn't be initialized. as a console error, and the view renders nothing-, and _. An ID that is not a valid CSS selector logs a warning when logging is enabledstoryteller class and a storyteller-view-id attribute to the elementThe element can also carry these attributes, which the constructor reads once:
Attribute Values Views Effectdata-ui-style auto, light, dark All Initial uiStyle data-cell-type round, square StorytellerStoriesRowView, StorytellerClipsRowView Initial tile shape data-base-url A basename All Basename to use when configuration.basename is not set A row fills the height of its container, so give the container a height. See the note in Add a Story or Clips row.
"},{"location":"reference/views/#members-of-every-view","title":"Members of every view","text":"Every view class has these members.
"},{"location":"reference/views/#configuration","title":"configuration","text":"set configuration(configuration: Partial<ListConfiguration<ViewName>>)\nget configuration(): ListConfiguration<ViewName>\nViewName is the class name, such as 'StorytellerStoriesRowView'. The two Clips player classes both use 'StorytellerClipsPlayerView', and their setter takes IStorytellerClipsPlayerConfiguration. ListConfiguration is not exported. Assign an IListConfiguration value instead.
Assigning an object updates only the fields that it includes:
categories, collection, clipId, or externalId reloads the view's contenttheme or uiStyle rebuilds the view themedisplayLimit field set to undefined or 0 removes the limitcontext change applies to later activity eventsReading the property returns the current values, including the view theme that the SDK merged from the global theme and configuration.theme.
storyRow.configuration = {\n categories: ['category-id'],\n displayLimit: 10,\n uiStyle: Storyteller.UiStyle.dark,\n};\ndelegate","text":"get delegate(): IListViewDelegate\nset delegate(delegateObj: IListViewDelegate)\nThe view's callbacks. The Clips player classes use IStorytellerClipsPlayerDelegate. Assigning an object replaces the previous delegate. The SDK fills callbacks that you leave out with no-op functions.
storyRow.delegate = {\n onDataLoadComplete: (success, error, dataCount) => {\n const container = document.getElementById('stories-row-id');\n\n if (container) {\n container.hidden = !success || dataCount === 0;\n }\n },\n};\nIListViewDelegatereloadData","text":"reloadData(): Promise<void>\nLoads fresh content for the view from the API. Clips views load the first page again. The view calls onDataLoadStarted, then onDataLoadComplete with the result.
onDataLoadCompletedestroy","text":"destroy(): void\nReleases the view. The SDK unmounts the view from the container, removes the view's player container unless another view shares it, and stops theme updates for the view. A second call does nothing. Call destroy before your application removes or replaces the container, such as in a React effect cleanup.
These members still work in 11.0.0. Replace them with configuration or the shared instance:
theme (get and set) All configuration.theme uiStyle (get and set) All configuration.uiStyle displayLimit (get and set) All configuration.displayLimit categories (get and set) Stories views configuration.categories. The setter does not reload the view cellType (set) StorytellerStoriesRowView configuration.cellType openStory(id: string): void Stories views Storyteller.sharedInstance.openStory openPage(pageId: string, onError?: (message: string) => void): void Stories views Storyteller.sharedInstance.openPage"},{"location":"reference/views/#members-of-some-views","title":"Members of some views","text":"These members exist only on the classes listed.
"},{"location":"reference/views/#celltype","title":"cellType","text":"set cellType(type: StorytellerListViewCellType)\nAvailable on StorytellerClipsRowView. Sets the tile shape to CellType.round or CellType.square. The Clips row configuration has no cellType field, so use this setter or the data-cell-type attribute. For StorytellerStoriesRowView, use configuration.cellType.
topLevelBackButtonEnabled","text":"get topLevelBackButtonEnabled(): boolean\nset topLevelBackButtonEnabled(isEnabled: boolean)\nAvailable on StorytellerClipsPlayerView and StorytellerEmbeddedClipsPlayerView. true shows a back button at the top of the player. A tap calls onTopLevelBackTapped, or window.history.back() when the delegate has no such callback. The default is false. This property is not part of configuration.
clipPlayer.topLevelBackButtonEnabled = true;\nclipPlayer.delegate = {\n onTopLevelBackTapped: () => {\n window.history.back();\n },\n};\nThe configuration interfaces describe what you can assign to a view's configuration property.
IListConfiguration","text":"type IListConfiguration<\n ListType extends keyof ListTypeToConfigMap | void = void\n>\nListTypeToConfigMap is an internal map from each view class name to its fields. Pass a view class name as the type argument to select the fields for that view. Every field is optional:
basename, context, displayLimit, theme, uiStyle 'StorytellerStoriesRowView' The fields for no type argument, plus categories, preload, cellType 'StorytellerStoriesGridView' The fields for no type argument, plus categories, preload 'StorytellerClipsRowView', 'StorytellerClipsGridView' The fields for no type argument, plus collection 'StorytellerClipsPlayerView', 'StorytellerEmbeddedClipsPlayerView' The fields for no type argument, plus collection, clipId, externalId The fields have these types and defaults:
Field Type Views Default Descriptionbasename string All stories or clips. With several views on a page, a value derived from the categories or collection First segment of the player hash URL. The SDK keeps only ASCII letters, numbers, -, and _ categories string[] Stories views The constructor listCategories Story category IDs cellType CellType StorytellerStoriesRowView CellType.square, or the data-cell-type attribute Tile shape collection string Clips views The constructor collection Clips collection ID clipId string Clips players None Clip ID for single-Clip playback externalId string Clips players None Clip external ID for single-Clip playback context unknown All undefined Your attribution data. The SDK returns it in UserActivityData.context displayLimit number Rows and grids. The player types accept it too No limit Maximum number of tiles preload boolean Stories views false true starts more Story player work before the first open. Assigning false later does not undo true theme Subset<UiTheme> All The global theme View theme. The SDK merges it over Storyteller.sharedInstance.theme uiStyle UiStyle All UiStyle.auto, or the data-ui-style attribute Light, dark, or system color scheme type RowConfiguration =\n Storyteller.IListConfiguration<'StorytellerStoriesRowView'>;\n\nconst rowConfiguration: RowConfiguration = {\n basename: 'top-stories',\n cellType: Storyteller.CellType.round,\n context: { location: 'home' },\n};\n\nstoryRow.configuration = rowConfiguration;\ncontext was added in 10.13.17type IStorytellerClipsPlayerConfiguration =\n Partial<StorytellerClipsPlayerConfiguration>;\n\ntype IStorytellerEmbeddedClipsPlayerConfiguration =\n Partial<StorytellerClipsPlayerConfiguration>;\nBoth types have the same fields as IListConfiguration<'StorytellerClipsPlayerView'>: basename, context, displayLimit, theme, uiStyle, collection, clipId, and externalId. Their theme field also accepts a full IUiTheme.
An update that includes a source field changes the source. Include exactly one non-empty source field. Otherwise, the SDK logs an error and keeps the current source.
clipPlayer.configuration = {\n externalId: 'new-clip-external-id',\n};\nA view is an SDK object that renders Storyteller content into an element on your page. Choose the view that matches the content and layout you need, then follow its guide.
Goal View Content source Show Stories in a horizontal rowStorytellerStoriesRowView Optional Category IDs Show Stories in a grid StorytellerStoriesGridView Optional Category IDs Show Clips in a horizontal row StorytellerClipsRowView Collection ID Show Clips in a grid StorytellerClipsGridView Collection ID Play Clips in an area of the page set aside for Clips StorytellerClipsPlayerView Collection ID, { clipId }, or { externalId } Play Clips inside other page content, such as a live blog StorytellerEmbeddedClipsPlayerView Collection ID, { clipId }, or { externalId } Every view constructor takes these arguments:
elementId: the ID of the element the view renders intocategories (Stories views, optional): Category IDs. Without them, the view shows the Stories in your Home list.collectionId (Clips rows and grids): the collection IDsource (Clips player views): a collection ID, { clipId }, or { externalId }. The constructor throws an Error if you pass no source or more than one.The API reference lists the full constructor signatures.
"},{"location":"views/#rows","title":"Rows","text":"Use a row for a compact list that users scroll horizontally. Rows can show round or square tiles through cellType. Grids don't use cellType.
Add a Story or Clips row
"},{"location":"views/#grids","title":"Grids","text":"Use a grid when the page should show more tiles at once. Grids use the same settings as the other views.
Add a Story or Clips grid
"},{"location":"views/#open-clips-from-a-custom-control","title":"Open a player from your code","text":"To open a Story or Clips player from a button, link, or route in your application, call a method on Storyteller.sharedInstance, such as openStory, openCollection, or openClipByExternalId.
Open a player programmatically
"},{"location":"views/#embedded-clips-player","title":"Clips players","text":"Both Clips player views render the Clips player into your container. StorytellerEmbeddedClipsPlayerView shows one Clip at a time, lets the rest of the page scroll, and ignores Storyteller.sharedInstance.dismissPlayer. StorytellerClipsPlayerView uses the full Clips player layout, which can show neighboring Clips on wide screens, and locks page scrolling while it's shown.
Add a Clips player to a page
"},{"location":"views/#polls-and-quizzes","title":"Polls and Quizzes","text":"Polls and Quizzes are Story Pages: Pages inside a Story. Show the Story in a Stories row or grid, and the Story player handles the Poll or Quiz.
Show Polls and Quizzes
"},{"location":"views/#shared-list-configuration","title":"Settings shared by all views","text":"All views share settings for content, themes, display limits, preload behavior, analytics context, and delegates.
Configure views
"},{"location":"views/engagement/","title":"Show Polls and Quizzes","text":"Polls and Quizzes are Story Pages: Pages inside a Story that ask the user a question. Publish a Story that contains a Poll or Quiz Page, then show the Story in a Stories row or grid. The Story player handles the interaction, so you don't write any code for it.
"},{"location":"views/engagement/#poll-results","title":"Poll results","text":"After a user votes, the Poll stays on screen and shows the percentage for each answer. The results stay visible after the first vote. A later tap can move to the next Page or Story.
"},{"location":"views/engagement/#answer-text","title":"Answer text","text":"Poll and Quiz answers can show up to two lines. Longer text is cut off. Check the published answer text at the screen widths your users have.
"},{"location":"views/engagement/#appearance-and-analytics","title":"Appearance and analytics","text":"Use the Poll and Quiz theme settings to style the answers. Handle votes and Quiz answers in the onUserActivityOccurred callback, then check the Poll events and Quiz events for their data fields.
If you are moving from a 10.13.x integration, include long answer text in your version 11 checks.
"}]}