Skip to content

Migrate from version 10 to 11#

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.

Before you update#

Record the current integration, so you can test the update and roll it back:

  • the current SDK version
  • the installation path: npm or script tag
  • where the SDK files are hosted, if you host them yourself
  • initialize options and how you set and change users
  • each view constructor and its configuration
  • privacy, analytics, callback, and ad settings
  • any proxy, allowlist, or Content Security Policy between the browser and Storyteller

Read the current version from the SDK.

console.log(Storyteller.sharedInstance.version);

What stays the same#

Version 11 keeps these entry points:

  • the @getstoryteller/storyteller-sdk-javascript package name
  • the Storyteller browser global
  • Storyteller.sharedInstance.initialize
  • the Story and Clip view constructor names
  • the npm stylesheet, dist/storyteller.min.css

Namespace and named imports keep working, and the package includes TypeScript declarations.

Breaking changes#

Each change below says what to do. Some changes apply only to certain integrations, such as self-hosted SDK files or TypeScript code.

Viewing history loads from Storyteller#

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:

  1. Keep a catch on every initialize call. See Handle initialization errors.
  2. If a proxy, firewall, or allowlist sits between the browser and the Storyteller API, allow the requests in the table below.
  3. If your proxy answers CORS preflight requests, add x-storyteller-recent-viewed-clip-ids to its Access-Control-Allow-Headers response.
Request Path or header
Viewing history 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.

Local storage keys changed#

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 key
Storyteller.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:

  1. Replace the 10.13 key names in your cookie or consent inventory. The local storage table lists every current key.
  2. If your consent policy requires it, remove the five 10.13 keys yourself.

The script build loads files from its directory#

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:

  1. Copy every file in the version's dist directory to one directory on your server.
  2. Keep the file names.
  3. Load 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.

npm peer dependencies and entry points#

The npm package now declares these peer dependencies, because its TypeScript declarations import them:

  • @types/react: >=17 <20
  • @types/react-router-dom: ^5.1.7

npm 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.css

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

Global and TypeScript changes#

  • The SDK no longer installs the 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.
  • The undocumented QuizRenderer.clearQuizData() method was removed. Remove any calls to it.

Behavior changes#

These changes need no code, but check them in your application:

  • Player code loads on demand (script tag only): the script build downloads Story player, Clips player, Poll, Quiz, and caption code the first time a page needs it. The npm package still includes this code, and your bundler decides how it loads.
  • AMP player preload: each Stories row or grid starts a low-priority download of the AMP player script before the first Story opens. Set preload to true to prepare more of the Story player in advance.
  • Story ordering: when the Stories API uses started-aware ordering, rows and grids show Stories the user has not opened, then Stories in progress, then finished Stories. Pinned and Live Stories keep their priority.
  • Clips paging: Clips rows, grids, and players that show a Collection load more Clips as the user reaches the last loaded Clip. The onDataLoadComplete callback reports the number of Clips in the first page as dataCount. Later pages load without delegate callbacks.
  • Clip details: the Clips player can show a long description in an expandable details area.
  • Story chips: Story tiles can show custom Live and pinned chip text from Story content.
  • Compact Clip action buttons: if your remote theme sets clipsActionButtonCompactSize, the Clips player shows smaller action buttons.
  • Like and share counts: if your remote theme sets showLikeCount or showShareCount to false, the Clips player hides that count.
  • Caption defaults: each caption theme field set for a feed now overrides only that field of the tenant caption theme. Default captions use 16 px text, the font's natural line height, and a #171A25 background instead of 18 px text, a 22 px line height, and a #000000 background.
  • Stories with no Pages: rows and grids no longer show them.
  • sdkInitialized event: onUserActivityOccurred receives sdkInitialized during initialize. If your handler maps every event type, make it ignore or record this one.

Update an npm integration#

Install version 11.0.0.

npm install @getstoryteller/[email protected]

If 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';
import '@getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css';

Update a script integration#

Change the version segment in the CDN URL.

<script src="https://content.usestoryteller.com/javascript-sdk/11.0.0/dist/storyteller.min.js"></script>

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

Test the update#

Check these paths with version 11.0.0:

  1. Initialize the SDK with a test tenant. Check that initialize resolves. With the default privacy options, also check that the viewing-history request succeeds in the browser's network panel.
  2. Load every row, grid, and embedded player your application uses. Check Story ordering and later Clips pages where your tenant enables them.
  3. Open and close Story and Clips players. Check long Clip descriptions, custom Story chips, compact Clip action buttons, like and share counts, captions, and long Poll and Quiz answers where you use them.
  4. Read a Story, reload the page, and check that the Story still shows as read. Repeat the check after you change between anonymous and signed-in users, if your application supports both.
  5. If you host the SDK files, open a Story, a Clips player, a Poll, and a Quiz. Check that each player, Poll, Quiz, and caption file loads from your server with no 404 errors.
  6. Open each player and check the browser console for Content Security Policy errors.
  7. Confirm privacy settings, analytics callbacks, and ad requests. Check the sdkInitialized event if your application handles activity events.
  8. Change routes in a single-page application. Check that your code calls 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.

Roll back#

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.

Get help#

If the update fails, work through Troubleshoot an integration. If you still need help, contact Storyteller Support.