Skip to content

API reference#

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.

Reference pages#

The reference has four pages, organized by the part of the SDK you call:

Page Covers
Storyteller instance Storyteller.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

Package entry points#

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.

npm package#

Install the package from npm:

npm install @getstoryteller/storyteller-sdk-javascript

The package supports these import forms:

import * as Storyteller from '@getstoryteller/storyteller-sdk-javascript';

import {
  sharedInstance,
  StorytellerStoriesRowView,
} from '@getstoryteller/storyteller-sdk-javascript';

import Storyteller from '@getstoryteller/storyteller-sdk-javascript';

const Storyteller = require('@getstoryteller/storyteller-sdk-javascript');

The guides use the namespace import. The import forms return the same objects:

  • Storyteller.sharedInstance and the named sharedInstance export are the same instance
  • The default export is the namespace object. The ESM entry (index.mjs) provides it
  • The CommonJS entry (index.cjs) returns the namespace object itself, which has no default property
  • Importing the package in Node.js does not require window or document, so server code can import it. Create views only in the browser

The package exports map resolves these paths:

Import path Condition File
@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

Stylesheet#

An npm integration must import the stylesheet once, from code that runs in the browser:

import '@getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css';

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

CDN script#

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>

The script defines the Storyteller global on window. It differs from the npm package in these ways:

  • The script adds its styles to the page, so you do not need the npm stylesheet
  • The script loads its Story player, Clips player, Poll, Quiz, and caption files from the directory that served storyteller.min.js
  • StorytellerTrackedFunctionalFeature 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.

TypeScript declarations#

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, IStorytellerEmbeddedClipsPlayerConfiguration
  • IStorytellerDelegate, IListViewDelegate, IStorytellerClipsPlayerDelegate
  • StorytellerEventTrackingOptions
  • StorytellerAdRequestInfo, StorytellerStoriesAdRequestInfo, StorytellerClipsAdRequestInfo
  • ServerRenderedStory, Subset

Some 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';

type UserInput = NonNullable<
  Parameters<typeof Storyteller.sharedInstance.initialize>[1]
>;

type GetAdConfig = NonNullable<
  Storyteller.IStorytellerDelegate['getAdConfig']
>;
type AdConfig = NonNullable<ReturnType<GetAdConfig>>;

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

Exports#

The package exports these names. Names marked as types exist only in TypeScript.

Export Kind Reference
sharedInstance 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

Conventions#

These pages follow these conventions:

  • Signatures come from the published declaration files. A ? marks an optional parameter or field
  • Since gives the release that added or last changed a member, when the release notes record it
  • Examples use the namespace import Storyteller. With the CDN script, the same code runs against the Storyteller global
  • Examples use placeholder values such as demo-api-key and category-id. Replace them with values from your Storyteller tenant