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.
The privacy and tracking options. Each assignment replaces every option:
options you leave out return to their defaults. See
Control privacy and tracking.
Initializes 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 key
userInput.externalId: your ID for the signed-in user, or null for an anonymous user. See Setting a user ID.
try{awaitStoryteller.sharedInstance.initialize('demo-api-key',{externalId:'your-user-id',});}catch(error){console.error('Storyteller could not initialize.',error);}
Calls with the same API key and externalId made while an earlier call is still running share that call's promise. React Strict Mode's repeated effects therefore initialize the SDK once.
With the default privacy options, initialize also loads the user's viewing history from Storyteller, and rejects if that request fails.
Each call resets Storyteller.sharedInstance.theme to its defaults. Set the global theme after the promise resolves.
The promise rejects with an 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.
Pauses 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.
Turns 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();
The Storyteller Web Showcase turns on logging in its debug mode with this
enableLogging call.
Returns 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.
awaitStoryteller.sharedInstance.initialize('demo-api-key');constcount=awaitStoryteller.sharedInstance.getStoriesCount(['category-id']);if(count>0){// Show the row only when the Category has StoriesnewStoryteller.StorytellerStoriesRowView('stories-row-id',['category-id']);}
Returns 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.
Opens 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.
Opens 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.
Opens 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.
Opens 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.
Opens 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.
{"slug": "additional-methods", "page_title": "Use Additional SDK Methods", "page_url": "AdditionalMethods/", "canonical_url": "/web/AdditionalMethods/", "markdown": "# Use additional SDK methods {#additional-methods}\n\nThis page lists the properties and methods of `Storyteller.sharedInstance`, the\nSDK object you initialize and use to open players, count content, and read SDK\nstate. For methods on a view, such as `reloadData` and `destroy`, see\n[Configure views](StorytellerListView.md#methods). The\n[API reference](reference/index.md) lists every public member, including\n`theme`, `currentTheme`, `currentApiKey`, and `customInstanceHost`.\n\nExamples that use `await` must run inside an `async` function or a JavaScript\nmodule.\n\n## Set the global delegate {#setting-the-global-storytellerdelegate}\n\n```javascript\nStoryteller.sharedInstance.delegate = {\n // Your callbacks here\n};\n```\n\n!!! info \"Learn more\"\n\n To set the global delegate, see [Handle global callbacks](StorytellerDelegate.md).\n\n<!-- markdownlint-disable MD033 -->\n<span id=\"static-attributes\"><\/span>\n<!-- markdownlint-enable MD033 -->\n\n## Instance properties\n\n### isInitialized\n\n```typescript\nreadonly isInitialized: boolean\n```\n\n`true` after an `initialize` call succeeds.\n\n```javascript\nconst initialized = Storyteller.sharedInstance.isInitialized;\n```\n\n### isPlayerVisible\n\n```typescript\nreadonly isPlayerVisible: boolean\n```\n\n`true` while a Story or Clips player is open, and `false` after it is\ndismissed.\n\n```javascript\nconst isStoryPlayerVisible = Storyteller.sharedInstance.isPlayerVisible;\n```\n\n### version\n\n```typescript\nversion: string\n```\n\nThe SDK version.\n\n```javascript\nconst storytellerVersion = Storyteller.sharedInstance.version;\n```\n\n### `eventTrackingOptions`\n\nThe privacy and tracking options. Each assignment replaces every option:\noptions you leave out return to their defaults. See\n[Control privacy and tracking](PrivacyAndTracking.md).\n\n<!-- markdownlint-disable MD033 -->\n<span id=\"static-methods\"><\/span>\n<!-- markdownlint-enable MD033 -->\n\n## Instance methods\n\n### initialize {#initialize}\n\n```typescript\ninitialize(apiKey: string, userInput?: { externalId?: string | null }): Promise<void>\n```\n\nInitializes the SDK with your API key and, optionally, your ID for the current\nuser. Call it before you use other methods, and wait for the promise.\n\n- `apiKey`: your Storyteller API key\n- `userInput.externalId`: your ID for the signed-in user, or `null` for an anonymous user. See [Setting a user ID](Users.md#setting-a-user-id).\n\n```javascript\ntry {\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}\n```\n\n- Calls with the same API key and `externalId` made while an earlier call is still running share that call's promise. React Strict Mode's repeated effects therefore initialize the SDK once.\n- With the default privacy options, `initialize` also loads the user's viewing history from Storyteller, and rejects if that request fails.\n- Each call resets `Storyteller.sharedInstance.theme` to its defaults. Set the global theme after the promise resolves.\n- The promise rejects with an `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](Quickstart.md#handle-initialization-errors).\n\n### dismissPlayer\n\n```typescript\ndismissPlayer(animated: boolean): void\n```\n\nCloses the open Story or Clips player. If no player is open, it does nothing.\nIt doesn't close a `StorytellerEmbeddedClipsPlayerView`.\n\n- `animated`: `true` plays the close animation.\n\n```javascript\nStoryteller.sharedInstance.dismissPlayer(true);\n```\n\n### disablePlayback {#disableplayback}\n\n```typescript\ndisablePlayback(): void\n```\n\nPauses the open Story player and the current Clip in every Clips player on the\npage. Stories and Clips that open while playback is disabled stay paused until\nyou call `enablePlayback`. Use it when your page shows something over\nStoryteller content, such as your own video or a dialog.\n\n```javascript\nStoryteller.sharedInstance.disablePlayback();\n```\n\n### enablePlayback {#enableplayback}\n\n```typescript\nenablePlayback(): void\n```\n\nAllows playback again after `disablePlayback`, and resumes the open Story and\nthe current Clip. Playback is enabled by default.\n\n```javascript\nStoryteller.sharedInstance.enablePlayback();\n```\n\n### enableLogging\n\n```typescript\nenableLogging(): void\n```\n\nTurns on the SDK's info, warning, and log messages in the browser console. The\nSDK always logs errors. Use it for debugging and monitoring, and call it before\n`initialize` to see initialization logs.\n\n```javascript\nStoryteller.sharedInstance.enableLogging();\n```\n\nThe Storyteller Web Showcase turns on logging in its debug mode with this\n[`enableLogging` call](https://github.com/getstoryteller/storyteller-showcase-web/blob/11.0.0/nextjs/src/components/contexts/useStorytellerSdk.ts#L82).\n\n### getStoriesCount\n\n```typescript\ngetStoriesCount(categoryIds: string[]): Promise<number>\n```\n\nReturns the total number of available Stories in the given Category IDs. The\nSDK sends one small count request for each Category and adds the results. An\nempty array returns `0` without a request.\n\nThe SDK sends the count requests only after `initialize` succeeds. A count call\nmade before or during initialization waits for it. If initialization never\nstarts or fails, the promise stays pending until a later `initialize` call\nsucceeds. A failed count request rejects the promise.\n\nUse the count method for an optional row that should appear only when it has\ncontent. Load a primary row directly, without a count, to avoid an extra\nrequest.\n\n```javascript\nawait 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}\n```\n\n### getClipsCount\n\n```typescript\ngetClipsCount(collectionId: string): Promise<number>\n```\n\nReturns the number of available Clips in the collection. It waits for\ninitialization and handles errors in the same way as `getStoriesCount`. Use it\nbefore you create an optional Clips view.\n\n```javascript\nconst clipsCount = await Storyteller.sharedInstance.getClipsCount('collection-id');\n```\n\n### openStory\n\n```typescript\nopenStory(id: string): Promise<void>\n```\n\nOpens the Story with this ID. The promise rejects if the SDK can't open the\nStory, for example because it can't be found. See\n[Open a player programmatically](OpenPlayer.md#open-a-story).\n\n```javascript\nawait Storyteller.sharedInstance.openStory('story-id');\n```\n\n### openStoryByExternalId\n\n```typescript\nopenStoryByExternalId(externalId: string): Promise<void>\n```\n\nOpens the Story with this external ID. The promise rejects if the SDK can't\nopen the Story, for example because it can't be found.\n\n```javascript\nawait Storyteller.sharedInstance.openStoryByExternalId('story-external-id');\n```\n\n### openPage\n\n```typescript\nopenPage(pageId: string): Promise<void>\n```\n\nOpens the Story that contains this Page, starting at the Page. The promise\nrejects if the SDK can't open the Page, for example because it can't be found.\n\n```javascript\nawait Storyteller.sharedInstance.openPage('page-id');\n```\n\n### openCategory\n\n```typescript\nopenCategory(categoryId: string, storyId?: string): Promise<void>\n```\n\nOpens the Story player for the Category, at the Story with the ID `storyId`. If\nyou leave out `storyId`, or it isn't in the Category, the first Story in the\nCategory opens. The promise rejects if the SDK can't open the Category, for\nexample because it can't be found.\n\n```javascript\nawait Storyteller.sharedInstance.openCategory('category-id', 'story-id');\n```\n\n### openCollection\n\n```typescript\nopenCollection(\n collectionId: string,\n destination?: { categoryId?: string; clipId?: string },\n openedReason?: OpenedReason.deepLink\n): Promise<void>\n```\n\nOpens the Clips player for the collection. It accepts the following parameters:\n\n- `collectionId`: the ID of the collection to open.\n- `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.\n- `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.\n\nThe promise rejects if the SDK can't open the collection, for example because\nit can't be found.\n\n```javascript\nawait Storyteller.sharedInstance.openCollection(\n 'collection-id',\n { clipId: 'clip-id' },\n Storyteller.OpenedReason.deepLink\n);\n```\n\n### openClipByExternalId\n\n```typescript\nopenClipByExternalId(collectionId: string, externalId: string): Promise<void>\n```\n\nOpens the Clips player for the collection, at the Clip with this external ID.\nThe promise rejects if the SDK can't open the Clip, for example because the\ncollection has no Clip with that external ID.\n\n```javascript\nawait Storyteller.sharedInstance.openClipByExternalId(\n 'collection-id',\n 'clip-external-id'\n);\n```\n\n### Deprecated members {#deprecated-members}\n\nThese members still work in version 11, but don't use them in new code:\n\n| Member | Use instead |\n| --- | --- |\n| `openClip(id, onError?)` | [`openCollection`](#opencollection) or [`openClipByExternalId`](#openclipbyexternalid) |\n| `enableEventTracking()` | [`eventTrackingOptions`](PrivacyAndTracking.md) |\n| `disableEventTracking()` | [`eventTrackingOptions`](PrivacyAndTracking.md) |\n| `currentUserId` | None. It always returns an empty string. |\n", "copy_markdown_include_header": false, "base_path": "", "ai_dir": "ai", "missing_payload_behavior": "empty"}