FairShare media

Use <fluid-media-widget> to display one media item or a playlist. You can listen for playback events and scope listeners to a specific embed. For widget modes that render CTA controls, you can also override the call to action without building a player from scratch.

Embed media

Use media-id for one item or playlist-id for a playlist:

<fluid-media-widget
  playlist-id="spring-launch-demos"
  embed-type="inline"
></fluid-media-widget>

If you provide both identifiers, playlist-id takes precedence. See FairShare web components for common widget attributes.

Listen for media events

The media API exposes six subscription methods:

Event	Method	When it fires
Load	`onLoad()`	Media metadata is ready
Start	`onStart()`	Playback begins for the first time
Pause	`onPause()`	Playback pauses
Resume	`onResume()`	Playback resumes after a pause
Complete	`onComplete()`	Playback reaches the end
CTA click	`onCtaActionClick()`	The shopper selects the call to action

Subscribe through FairShareSDK.media:

const unsubscribe = window.FairShareSDK.media.onStart((payload) => {
  console.log("Started:", payload.mediaId);
});

// Stop listening when your component unmounts.
unsubscribe();

Playback payloads include the media identifier and type, timestamp, playback position and duration, media URL, title, and the playlist identifier when applicable. Media types include video, image, pdf, and website. START fires once on the first play. A play after pausing emits RESUME. Completing the media resets the lifecycle, so replaying it emits START again.

Filter subscriptions

Pass a filter as the second argument to listen to one media item, one playlist, or a specific media item within a playlist:

const stopMediaListener = window.FairShareSDK.media.onComplete(
  (payload) => {
    console.log("Completed:", payload.mediaId);
  },
  { mediaId: "starter-kit-demo" },
);

const stopPlaylistListener = window.FairShareSDK.media.onPause(
  (payload) => {
    console.log("Paused:", payload.mediaId);
  },
  { playlistId: "spring-launch-demos" },
);

Every subscription returns an unsubscribe function.

Listen on window

The same lifecycle is available as window events:

window.addEventListener("FLUID_MEDIA_CTA_CLICK", (event) => {
  console.log("CTA selected:", event.detail.ctaType);
});

The event names are:

FLUID_MEDIA_LOAD
FLUID_MEDIA_START
FLUID_MEDIA_PAUSE
FLUID_MEDIA_RESUME
FLUID_MEDIA_COMPLETE
FLUID_MEDIA_CTA_CLICK

Prefer FairShareSDK.media subscriptions when possible because they support filters and return cleanup functions.

Configure media calls to action

CTA settings affect widgets that render CTA controls. Currently, default and popover widgets render them; inline and inline-shopping widgets do not. Set a default CTA for eligible media widgets on the page:

window.FairShareSDK.media.settings.setDefault({
  ctaOptionsManualOverride: {
    type: "cart",
  },
});

Override the default for one playlist or media item:

window.FairShareSDK.media.settings.setForPlaylist("spring-launch-demos", {
  ctaOptionsManualOverride: {
    type: "link",
    url: "https://shop.example.com/starter-kits",
    buttonText: "Shop starter kits",
  },
});

window.FairShareSDK.media.settings.setForMedia("unboxing-the-starter-kit", {
  ctaOptionsManualOverride: {
    type: "email",
    buttonText: "Ask a question",
  },
});

Set defaults, playlist overrides, and media overrides together when you already have the complete page configuration:

window.FairShareSDK.media.settings.set({
  default: {
    ctaOptionsManualOverride: {
      type: "cart",
      buttonText: "Add to cart",
    },
  },
  byPlaylistId: {
    "spring-launch-demos": {
      ctaOptionsManualOverride: {
        type: "link",
        url: "https://shop.example.com/starter-kits",
        buttonText: "Shop starter kits",
      },
    },
  },
  byMediaId: {
    "unboxing-the-starter-kit": {
      ctaOptionsManualOverride: {
        type: "email",
        buttonText: "Ask a question",
      },
    },
  },
});

You can also set cta-options-manual-override directly on the embed:

<fluid-media-widget
  media-id="unboxing-the-starter-kit"
  embed-type="popover"
  cta-options-manual-override='{"type":"link","url":"https://shop.example.com/starter-kits","buttonText":"Shop starter kits"}'
></fluid-media-widget>

Hide the CTA panel on one embed by setting enabled to false. type is still required; cart needs no other fields, so it keeps the override short:

<fluid-media-widget
  media-id="unboxing-the-starter-kit"
  cta-options-manual-override='{"type":"cart","enabled":false}'
></fluid-media-widget>

This hides the whole panel, including the cart and lead-capture controls. The same enabled key works in setDefault, setForPlaylist, and setForMedia. To hide a media item’s CTA everywhere rather than on one embed, switch the CTA off on the media item in the admin instead. FairShare resolves CTA settings in this order:

The embed’s cta-options-manual-override attribute
Settings for the media item
Settings for the playlist
Page defaults

Settings created through the media API are page-scoped and stored in local browser storage. Read or clear the settings for the current page:

const mediaSettings = window.FairShareSDK.media.settings.get();

window.FairShareSDK.media.settings.clear();

Get Started

Core Concepts

Guides

Migration guides

Website & Themes

FairShare SDK

Files SDK

Portal & Widgets

FairShare media

Embed media

Listen for media events

Filter subscriptions

Listen on window

Configure media calls to action

​Embed media

​Listen for media events

​Filter subscriptions

​Listen on window

​Configure media calls to action

Embed media

Listen for media events

Filter subscriptions

Listen on window

Configure media calls to action