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 SDK is 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://web.usestoryteller.com/javascript-sdk/2.2.0/dist/storyteller.min.js"></script>
</head>

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.

Storyteller.sharedInstance
  .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', [
      'category-id-1',
      'category-id-2',
    ]);
    const storyGrid = new Storyteller.GridView('storyteller-grid', [
      'category-id-1',
      'category-id-2',
    ]);
    

Find out more about Configuring a StorytellerListView

PREVIOUS
Forward Arrow