Skip to content

Open a player programmatically#

Open a Story or Clips player from your own button, link, or route instead of a tile. These methods are on Storyteller.sharedInstance. Each one returns a promise that rejects when the SDK can't open the content. Call them after initialize resolves.

const openFeaturedStory = async () => {
  try {
    await Storyteller.sharedInstance.openStory('story-id');
  } catch (error) {
    console.error('The Story could not be opened.', error);
  }
};

document
  .getElementById('featured-story-button')
  ?.addEventListener('click', openFeaturedStory);

The SDK first looks for the content in the views on your page and opens it in that view's player. It uses only views whose player URLs are turned on, which means the disableUrls theme setting is false. If no view on the page has the content, the SDK loads it from Storyteller and opens it in a default player. Either way, the SDK opens the player by setting the page's hash URL, such as #stories/story-id, and the promise resolves at that point. See basename for the URL format.

Open a Story#

openStory#

Opens a Story by its ID.

await Storyteller.sharedInstance.openStory('story-id');

Full signature: openStory.

openStoryByExternalId#

Opens a Story by its external ID.

await Storyteller.sharedInstance.openStoryByExternalId('story-external-id');

Full signature: openStoryByExternalId.

openPage#

Opens the Story that contains a Page, starting at that Page.

await Storyteller.sharedInstance.openPage('page-id');

Full signature: openPage.

openCategory#

Opens the Story player for a Category. Pass a Story ID as the second argument to start at that Story; otherwise, the first Story in the Category opens.

await Storyteller.sharedInstance.openCategory('category-id', 'story-id');

Full signature: openCategory.

Open Clips#

openCollection#

Opens the Clips player for a collection. Pass a destination to start at a Clip, or at the first Clip in a Clip Category. Otherwise, the first Clip in the collection opens.

await Storyteller.sharedInstance.openCollection('collection-id');

await Storyteller.sharedInstance.openCollection('collection-id', {
  clipId: 'clip-id',
});

await Storyteller.sharedInstance.openCollection('collection-id', {
  categoryId: 'clip-category-id',
});

When the user arrived through a deep link, pass Storyteller.OpenedReason.deepLink as the third argument so analytics events report deepLink as the reason:

await Storyteller.sharedInstance.openCollection(
  'collection-id',
  { clipId: 'clip-id' },
  Storyteller.OpenedReason.deepLink
);

Full signature: openCollection.

openClipByExternalId#

Opens the Clips player for a collection, at the Clip with this external ID.

await Storyteller.sharedInstance.openClipByExternalId(
  'collection-id',
  'clip-external-id'
);

Full signature: openClipByExternalId.

Close the player#

Call dismissPlayer to close the open Story or Clips player, for example when your application navigates away. Pass true to play the close animation. If no player is open, the call does nothing. It doesn't close a StorytellerEmbeddedClipsPlayerView.

if (Storyteller.sharedInstance.isPlayerVisible) {
  Storyteller.sharedInstance.dismissPlayer(true);
}

Full signature: dismissPlayer.

Handle errors#

Wrap each call in try/catch, or add .catch(), so that a rejected promise doesn't go unhandled. The rejection value can be an Error or a string.

Method When the content is missing
openStory, openStoryByExternalId Rejects when the Story request fails, or with a string when no Story has the ID.
openPage Rejects when the SDK can't load a Story that contains the Page.
openCategory Rejects when the SDK can't load the Category, or the Category has no Stories. If storyId isn't in the Category, the first Story opens instead.
openCollection Rejects when the SDK can't load the collection, or the collection has no Clips. If the destination Clip or Category isn't in the collection, the first Clip opens instead.
openClipByExternalId Rejects when the SDK can't load the collection, or with a string when the collection has no Clip with the external ID.

When the SDK opens the first Story or Clip instead of the one you asked for, it logs a message. Call enableLogging to see it in the browser console.

Next steps#