Player Methods

13min
Please note: This documentation is currently being revised. It may therefore be incomplete in some parts.
closePlayer()
Closes the player.
In the case of Embedded Media Player﻿ instances in Picture-in-Picture﻿, cover or fullscreen mode, the player reverts back to its embedded location. 
This action pauses media playback and resets the seek position to 0.
Usage Example
player.closePlayer();
player.closePlayer();
﻿
maximizePlayer()
By invoking this method, Embedded Media Player﻿s or players in Picture-in-Picture Mode﻿ transition to cover mode.
Usage Example
player.maximizePlayer();
player.maximizePlayer();
﻿
minimizePlayer()
By invoking this method, Embedded Media Players﻿ or players in cover or fullscreen mode transition to Picture-in-Picture Mode﻿.
Usage Example
player.minimizePlayer();
player.minimizePlayer();
﻿
off()
Deregisters a previously registered event listener, preventing it from receiving further events.
TypeScript
const eventLogger = (...args: unknown[]) => console.log(...args);

// Register the event listener.
player.on(player.Event.MEDIA_INIT, eventLogger);

// Deregister the event listener.
player.off(player.Event.MEDIA_INIT, eventLogger);
const eventLogger = (...args: unknown[]) => console.log(...args);

// Register the event listener.
player.on(player.Event.MEDIA_INIT, eventLogger);

// Deregister the event listener.
player.off(player.Event.MEDIA_INIT, eventLogger);
﻿
Calling off() with arguments that do not identify any currently registered event listener has no effect.
on()
Registers an event listener to capture any event from the list of Player Events﻿.
Usage Example
player.on(
  player.Event.MEDIA_COMPLETE,
  ({ mediaId, mediaType }) => {
    console.log('Media playback completed for item:', mediaId, mediaType);
  },
);
player.on(
  player.Event.MEDIA_COMPLETE,
  ({ mediaId, mediaType }) => {
    console.log('Media playback completed for item:', mediaId, mediaType);
  },
);
﻿
open()
When invoking this method, the main player is activated in cover mode, displaying either the playlists or media content specified by the input argument that were previously defined.
Name
Description
input
Optional. The input object, which determines the type of media to be displayed. Currently, types of PlaylistItem are the sole options available.
options
Optional. The Player Options﻿ to apply when opening the player.
Please note: If specified, the player options do not overwrite the player's configuration as defined during creation. To update the player's configuration, please use updateConfiguration()﻿.
Schema
Usage Example
TypeScript
type PlaylistItem = {
  /** The distinct identifier of the media item to be rendered. */
  mediaItemId: string;
  /** The distinct type of the media item to be rendered. */
  mediaItemType: 'show' | 'story';
};

type PlaylistItemStory = PlaylistItem & {
  /**
   * The date when the story was published,
   * represented in ISO 8601 date-time format.
   */
  publishedAt: string;
  /**
   * The URL of the image, which serves as either the primary image
   * of the story or, if `videoUrl` is specified, a poster image for
   * the story video.
   */
  imageUrl: string;
  /** The URL of the video utilized by the player for media playback. */
  videoUrl?: string;
};

open(input?: PlaylistItem, options?: PlayerOptions): void;
type PlaylistItem = {
  /** The distinct identifier of the media item to be rendered. */
  mediaItemId: string;
  /** The distinct type of the media item to be rendered. */
  mediaItemType: 'show' | 'story';
};

type PlaylistItemStory = PlaylistItem & {
  /**
   * The date when the story was published,
   * represented in ISO 8601 date-time format.
   */
  publishedAt: string;
  /**
   * The URL of the image, which serves as either the primary image
   * of the story or, if `videoUrl` is specified, a poster image for
   * the story video.
   */
  imageUrl: string;
  /** The URL of the video utilized by the player for media playback. */
  videoUrl?: string;
};

open(input?: PlaylistItem, options?: PlayerOptions): void;
﻿
TypeScript
player.open({
  mediaId: '830b1062-3b68-4d67-bbae-724ccd6ad456',
  mediaType: 'story',
});
player.open({
  mediaId: '830b1062-3b68-4d67-bbae-724ccd6ad456',
  mediaType: 'story',
});
﻿
removeAllListeners()
Proceed with care when employing this functionality, as it removes all event listeners that have been registered using player.on().
Usage Example
player
  .on(
    player.Event.NAVIGATE_NEXT_ITEM,
    ({ mediaId, mediaType }) => {
      console.log('Transition to next item.', mediaId, mediaType);
    },
  )
  .on(
    player.Event.MEDIA_PAUSE,
    ({ seekPosition }) => {
      console.log('Media playback paused at position:', seekPosition);
    },
  );

player.removeAllListeners();
player
  .on(
    player.Event.NAVIGATE_NEXT_ITEM,
    ({ mediaId, mediaType }) => {
      console.log('Transition to next item.', mediaId, mediaType);
    },
  )
  .on(
    player.Event.MEDIA_PAUSE,
    ({ seekPosition }) => {
      console.log('Media playback paused at position:', seekPosition);
    },
  );

player.removeAllListeners();
﻿
requestFullscreen()
By invoking this method, the player is switched to fullscreen mode.
If fullscreen mode is not allowed/supported, the player is switched to cover mode.
Schema
Usage Example
Schema
requestFullscreen(): void;
requestFullscreen(): void;
﻿
Promise
Callback
player.requestFullscreen();
player.requestFullscreen();
﻿
updateConfiguration()
By invoking this method, the player configuration options get updated.
Parameter
Description
options
﻿Player Options﻿ object.
Schema
Usage Example
Schema
updateConfiguration(options: PlayerOptions): void;
updateConfiguration(options: PlayerOptions): void;
﻿
Usage Example
player.updateConfiguration({
  currencyCode: 'GBP',
  locale: 'en-GB',
  socialSharingUrlTemplate:
    'https://my-storefront.com/en/gb/path?utm_source=lsc-social-share',
  store: 'uk',
});
player.updateConfiguration({
  currencyCode: 'GBP',
  locale: 'en-GB',
  socialSharingUrlTemplate:
    'https://my-storefront.com/en/gb/path?utm_source=lsc-social-share',
  store: 'uk',
});
﻿
updatePlaylists()
By invoking this method, the playlists for the player to render get updated.
Parameter
Description
playlists
Array of Playlist objects to be rendered by the player.
The player requires a distinct media item description depending on the type of media. Currently, story is the sole supported media item type.
For a comprehensive description of the playlist schema, refer to its definition provided in the tab view below.
Schema
Usage Example
Schema
type PlaylistItem = {
  /** The distinct identifier of the media item to be rendered. */
  mediaItemId: string;
  /** The distinct type of the media item to be rendered. */
  mediaItemType: 'story';
};

type Image = {
  /** The blur-hash of the image asset. */
  hash?: string;
  /** Height of the original image asset. */
  height?: number;
  /** Publicly accessible URL of the image asset. */
  url: string;
  /** Width of the original image asset. */
  width?: number;
};

type Video = {
  /** The duration of the video, represented in milliseconds. */
  durationInMs?: number;
  /** The blur-hash of the original video poster image asset */
  hash?: string;
  /** Height of the original video asset. */
  height?: number;
  /** Publicly accessible URL of the video asset. */
  url: string;
  /** Width of the original video asset. */
  width?: number;
};

type PlaylistItemStory = PlaylistItem & {
  /**
   * The date when the story was published,
   * represented in ISO 8601 date-time format.
   */
  publishedAt: string;
  /**
   * The image object, which serves as either the primary image
   * of the story or, if `video` is specified, a poster image for
   * the story video.
   */
  image: Image;
  /**
   * The video object which specifies the video URL for media playback
   * along with additional meta-data.
   */
  video?: Video;
};

type Playlist = {
  /** Avatar image of the playlist. */
  avatar: string;
  /** The distinct display name of the playlist. */
  displayName: string;
  /** An array of media items to be rendered in the player. */
  items: PlaylistItemStory[];
  /** The distinct identifier associtated with the source of a playlist. */
  sourceId: string;
  /**
   * The distinct type associated with the source of a playlist.
   *
   * - `channel` — Contains all stories associated with the source channel.
   * - `user` — Contains all stories associated with a creator.
   */
  sourceType: 'channel' | 'user';
};

updatePlaylists(playlists: Playlist[]): void;
type PlaylistItem = {
  /** The distinct identifier of the media item to be rendered. */
  mediaItemId: string;
  /** The distinct type of the media item to be rendered. */
  mediaItemType: 'story';
};

type Image = {
  /** The blur-hash of the image asset. */
  hash?: string;
  /** Height of the original image asset. */
  height?: number;
  /** Publicly accessible URL of the image asset. */
  url: string;
  /** Width of the original image asset. */
  width?: number;
};

type Video = {
  /** The duration of the video, represented in milliseconds. */
  durationInMs?: number;
  /** The blur-hash of the original video poster image asset */
  hash?: string;
  /** Height of the original video asset. */
  height?: number;
  /** Publicly accessible URL of the video asset. */
  url: string;
  /** Width of the original video asset. */
  width?: number;
};

type PlaylistItemStory = PlaylistItem & {
  /**
   * The date when the story was published,
   * represented in ISO 8601 date-time format.
   */
  publishedAt: string;
  /**
   * The image object, which serves as either the primary image
   * of the story or, if `video` is specified, a poster image for
   * the story video.
   */
  image: Image;
  /**
   * The video object which specifies the video URL for media playback
   * along with additional meta-data.
   */
  video?: Video;
};

type Playlist = {
  /** Avatar image of the playlist. */
  avatar: string;
  /** The distinct display name of the playlist. */
  displayName: string;
  /** An array of media items to be rendered in the player. */
  items: PlaylistItemStory[];
  /** The distinct identifier associtated with the source of a playlist. */
  sourceId: string;
  /**
   * The distinct type associated with the source of a playlist.
   *
   * - `channel` — Contains all stories associated with the source channel.
   * - `user` — Contains all stories associated with a creator.
   */
  sourceType: 'channel' | 'user';
};

updatePlaylists(playlists: Playlist[]): void;
﻿
Usage Example
player.updatePlaylists([
  {
    avatar: 'https://image.lisa-cdn.net/path/to/creator/avatar.webp',
    displayName: 'Jane Doe',
    items: [
      {
        mediaItemId: '9b4fb430-8439-4328-9f41-d08df0c56384',
        mediaItemType: 'story',
        publishedAt: '2023-03-03T12:47:21.237Z',
        imageUrl: 'https://image.lisa-cdn.net/poster-image.webp',
        videoUrl: 'https://video.lisa-cdn.net/sample-story.m3u8',
      },
    ],
    sourceId: '7627c72b-075c-4cf8-9018-333283c13077',
    sourceType: 'user',
  }
]);
player.updatePlaylists([
  {
    avatar: 'https://image.lisa-cdn.net/path/to/creator/avatar.webp',
    displayName: 'Jane Doe',
    items: [
      {
        mediaItemId: '9b4fb430-8439-4328-9f41-d08df0c56384',
        mediaItemType: 'story',
        publishedAt: '2023-03-03T12:47:21.237Z',
        imageUrl: 'https://image.lisa-cdn.net/poster-image.webp',
        videoUrl: 'https://video.lisa-cdn.net/sample-story.m3u8',
      },
    ],
    sourceId: '7627c72b-075c-4cf8-9018-333283c13077',
    sourceType: 'user',
  }
]);
﻿
﻿
Name	Description
input	Optional. The input object, which determines the type of media to be displayed. Currently, types of PlaylistItem are the sole options available.
options	Optional. The Player Options to apply when opening the player. Please note: If specified, the player options do not overwrite the player's configuration as defined during creation. To update the player's configuration, please use updateConfiguration().
Parameter	Description
options	Player Options object.
Parameter	Description
playlists	Array of Playlist objects to be rendered by the player. The player requires a distinct media item description depending on the type of media. Currently, story is the sole supported media item type. For a comprehensive description of the playlist schema, refer to its definition provided in the tab view below.
Updated 25 Mar 2024
Did this page help you?
Player Events
Player Options