Quickstart Guide

This is a developers' guide for setting up Storyteller for web. This guide will cover the basic technical steps for initializing the Storyteller SDK, authenticating a user, and adding a StorytellerListView to your site.


How to add the SDK to your site

Before you can add the Storyteller SDK to your site, you will need to obtain the following:

  • API Key - This is a secret key used to authenticate the SDK, marked as [API_KEY]

SDK Installation


The recommended installation method is to install the NPM package - @getstoryteller/storyteller-sdk-javascript. Install the latest version by running the following command.

npm install @getstoryteller/storyteller-sdk-javascript

Then import the SDK.

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


var Storyteller = require("@getstoryteller/storyteller-sdk-javascript");

Storyteller CDN

The SDK is also available from the Storyteller CDN. Include the JavaScript file in the <head> of the page where you would like to use Storyteller.

  <script type="text/javascript" src="https://web.usestoryteller.com/javascript-sdk/7.5.0/dist/storyteller.min.js"></script>

SDK Initialization

Use the Storyteller.sharedInstance.initialize(apiKey: string, userDetails: { externalId: String }) method to initialize the SDK and authenticate using your API Key.

Storyteller.sharedInstance.initialize('[API_KEY], { externalId: [EXTERNAL_ID] }');

See Working with Users for more information about user details.

Handling Errors

The initialize method returns a promise, allowing you to handle initialization success and error.

  .initialize(apiKey, { externalId })
  .then(() => {
    // handle success - e.g. initialize list(s)
  .catch((e) => {
    // handle error


async function initializeStoryteller() {
  try {
    await Storyteller.sharedInstance.initialize(apiKey, { externalId });
    // handle success - e.g. initialize list(s)
  } catch (e) {
    // handle error

Initialization errors:

  • HttpRequestError: the request to fetch settings has failed. The status code is included to provide information about the error
  • InvalidApiKeyError: thrown when an invalid Api Key is used
  • JsonParseError: this error is thrown when the settings response cannot be parsed

Adding a Storyteller List

  1. Add a <div> for the list to be rendered within.

    <div id="storyteller-list"></div>
  2. Initialize the Storyteller row by creating a new Storyteller.RowView(containerId: string, categories?: string[]), or a new Storyteller.GridView(containerId: string, categories?: string[])

    • containerId: the id of the container div where the row will be rendered

    • categories: an optional list of category IDs

    const storyRow = new Storyteller.RowView('storyteller-row', [
    const storyGrid = new Storyteller.GridView('storyteller-grid', [

Find out more about Configuring a StorytellerListView

Forward Arrow