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.
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].
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";
or
var Storyteller = require("@getstoryteller/storyteller-sdk-javascript");
require("@getstoryteller/storyteller-sdk-javascript/dist/storyteller.min.css");
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/7.9.1/dist/storyteller.min.js"></script>
</head>
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.
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:
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