Add a Clips player to a page

Use a Clips player view to play Clips in an element on your page, instead of opening the Clips player from a row or grid. The Web SDK has two Clips player views. Both render into your container, fill it, and accept the same content sources, configuration, and delegate.

Choose a Clips player view

View	Use it for	Behavior
StorytellerEmbeddedClipsPlayerView	Clips inside other page content, such as a live blog or match center	Shows one Clip at a time. The rest of the page keeps scrolling. Storyteller.sharedInstance.dismissPlayer doesn't close it.
StorytellerClipsPlayerView	An area of the page set aside for Clips	Uses the full Clips player layout, which can show neighboring Clips on wide screens. Locks page scrolling while it's shown. dismissPlayer dismisses it.

The rest of this page uses StorytellerEmbeddedClipsPlayerView. The same steps apply to StorytellerClipsPlayerView.

Initialization

StorytellerEmbeddedClipsPlayerView accepts the same content sources as StorytellerClipsPlayerView: a collection ID, { clipId }, or { externalId }.

const embeddedCollectionPlayer =
  new Storyteller.StorytellerEmbeddedClipsPlayerView(
    'embedded-clips-player-id',
    'clip-collection-id'
  );

const embeddedSingleClipPlayer =
  new Storyteller.StorytellerEmbeddedClipsPlayerView(
    'embedded-clips-player-id',
    { clipId: 'clip-id' }
  );

const embeddedSingleClipPlayerByExternalId =
  new Storyteller.StorytellerEmbeddedClipsPlayerView(
    'embedded-clips-player-id',
    { externalId: 'clip-external-id' }
  );

Provide exactly one source. With a collection ID, the player keeps collection behavior: users can move between the collection's Clips when the collection supports it. With { clipId } or { externalId }, the player shows only that Clip. The constructor throws an Error if you pass no source or more than one.

Sizing

Set the player's size with CSS on the container. The constructor has no width or height options.

For portrait Clips, set the container width and use a 9 / 16 aspect ratio so the browser works out the height:

<div
  id="embedded-clips-player-id"
  style="width: 430px; max-width: 100%; aspect-ratio: 9 / 16;"
></div>

const embeddedSingleClipPlayer =
  new Storyteller.StorytellerEmbeddedClipsPlayerView(
    'embedded-clips-player-id',
    { externalId: 'clip-external-id' }
  );

Configuration

The embedded Clips player uses the same configuration fields as StorytellerClipsPlayerView. See Configure views for every field. The TypeScript example assumes import * as Storyteller from '@getstoryteller/storyteller-sdk-javascript'; and imports the IStorytellerEmbeddedClipsPlayerConfiguration type.

const customTheme = new Storyteller.UiTheme(); // See Customize themes
const embeddedClipPlayer = new Storyteller.StorytellerEmbeddedClipsPlayerView(
  'embedded-clips-player-id',
  { externalId: 'clip-external-id' }
);
const embeddedClipPlayerConfiguration: IStorytellerEmbeddedClipsPlayerConfiguration =
  {
    theme: customTheme,
    uiStyle: Storyteller.UiStyle.dark,
  };

embeddedClipPlayer.configuration = embeddedClipPlayerConfiguration;

You can also change the source through configuration. Provide exactly one of collection, clipId, or externalId. An update with an invalid source logs an error and keeps the current source.

embeddedClipPlayer.configuration = {
  externalId: 'new-clip-external-id',
};

Handle the back button

StorytellerEmbeddedClipsPlayerView uses the Clips player delegate (IStorytellerClipsPlayerDelegate) through the same delegate property as StorytellerClipsPlayerView. See Handle view callbacks for every callback.

const embeddedClipPlayer = new Storyteller.StorytellerEmbeddedClipsPlayerView(
  'embedded-clips-player-id',
  { externalId: 'clip-external-id' }
);

embeddedClipPlayer.topLevelBackButtonEnabled = true;
embeddedClipPlayer.delegate = {
  onTopLevelBackTapped: () => {
    window.history.back();
  },
};

onPlayerDismissed means that the player was dismissed, so the back button doesn't call it. The button calls onTopLevelBackTapped if you define it; otherwise, it calls window.history.back().

When topLevelBackButtonEnabled is false or not set, the player doesn't show the back button and doesn't call onTopLevelBackTapped from it.

Use a Clips player for a dedicated area

Use StorytellerClipsPlayerView when an area of your page, such as a Clips section or a Clips page, is set aside for the player. It takes the same arguments, configuration, and delegate as StorytellerEmbeddedClipsPlayerView:

const clipPlayer = new Storyteller.StorytellerClipsPlayerView(
  'clips-player-id',
  'clip-collection-id'
);

clipPlayer.topLevelBackButtonEnabled = true;
clipPlayer.delegate = {
  onTopLevelBackTapped: () => {
    window.history.back();
  },
};

StorytellerClipsPlayerView differs from the embedded player in three ways:

• It uses the full Clips player layout, which can show neighboring Clips on wide screens.
• It locks page scrolling while it's shown.
• Storyteller.sharedInstance.dismissPlayer dismisses it and calls its onPlayerDismissed callback.

For its constructor and configuration, see Clips player initialization and Clips player configuration.