Developers / Web SDK / Quickstart Guide

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

Add a <div> for the list to be rendered within.
```
<div id="storyteller-list"></div>
```
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

Working with Users Forward Arrow