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.

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 the following:

API Key - This is a secret key used to authenticate the SDK, 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 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://web.usestoryteller.com/javascript-sdk/7.4.1/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