Skip to content

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.

Resources

Storyteller Web Sample App

How to Add the SDK to Your Site#

Before you can add the Storyteller SDK to your site, you will need to obtain an API Key. This is a secret ket used to authenticate the SDK on your site. Throughout this document it will be marked as [API_KEY].

SDK Installation#

NPM#

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

var Storyteller = require('@getstoryteller/storyteller-sdk-javascript');
require('@getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css');

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.

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

SDK Initialization#

Use the Storyteller.sharedInstance.initialize method to initialize the SDK and authenticate using your API Key.

Storyteller.sharedInstance.initialize(
  '[API_KEY]'
);

Learn more

See Working with Users for more information about how to supply information about the current user to the SDK.

Handling Errors#

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

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

or

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

Initialization errors:

  • InitializationError: when the context is null
  • InvalidApiKeyError: thrown when an invalid API key is used
  • NetworkError: when the call to load the settings for the SDK fails (i.e. a non-success HTTP status code is returned)
  • NetworkTimeoutError: when the call to load the settings for the SDK times out
  • JsonParseError: when a malformed settings response is received from the server

Implementing Storyteller Callbacks#

StorytellerDelegate has callbacks for events which can be implemented.

Learn more

See StorytellerDelegate for more details.

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.StorytellerStoriesRowView(containerId: string, categories?: string[]), or a new Storyteller.StorytellerStoriesGridView(containerId: string, categories?: string[]) for Stories, Storyteller.StorytellerClipsRowView(containerId: string, collectionId: string) or Storyteller.StorytellerClipsGridView(containerId: string, collectionId: string) for Clips

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

    • categories: an optional list of category IDs (Stories)

    • collectionId: the ID of the collection (Clips)

const storyRow = new Storyteller.StorytellerStoriesRowView('storyteller-stories-row', [
  'category-id-1',
  'category-id-2',
]);

const storyGrid = new Storyteller.StorytellerStoriesGridView('storyteller-stories-grid', [
  'category-id-1',
  'category-id-2',
]);

const clipsRow = new Storyteller.StorytellerClipsRowView('storyteller-clips-row', 'collection-id');

const clipsGrid = new Storyteller.StorytellerClipsGridView('storyteller-clips-grid', 'collection-id');

Warning

Note that the containerId must follow best practices for HTML IDs; only ASCII letters, numbers, dashes (-), and underscores (_) should be used.

Learn more

Find out more about Configuring a StorytellerListView