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 the following:
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>
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
});
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