Playlist Event Listeners

Track user interactions with media items within a specific playlist. All playlist event listeners use the FairShareSDK.media.* API with playlist filtering.

Quick Start

// Subscribe to events for a specific playlist
const unsubscribe = FairShareSDK.media.onStart((payload) => {
  console.log('Playlist media started:', payload.mediaId);
}, { playlistId: 'your-playlist-id' });

// Later, unsubscribe when no longer needed
unsubscribe();

Available Events

Event	Method	Trigger
Load	`onLoad()`	Media metadata has loaded and is ready to play
Start	`onStart()`	Media playback began (first play only)
Pause	`onPause()`	Media playback was paused
Resume	`onResume()`	Media playback resumed after being paused
Complete	`onComplete()`	Media playback finished (reached the end)
CTA Click	`onCtaActionClick()`	User clicked a Call-to-Action button

Filtering by Playlist

Pass a filter object as the second argument to only receive events from a specific playlist:

// Only receive events from this playlist
FairShareSDK.media.onStart((payload) => {
  console.log('Started:', payload.title);
}, { playlistId: 'your-playlist-id' });

Event Payload

All events include the playlistId in the payload:

Property	Type	Description
`mediaId`	string	Unique identifier for the media item
`mediaType`	string	Type: `"video"`, `"image"`, `"pdf"`, or `"website"`
`timestamp`	string	ISO 8601 timestamp
`currentTime`	number	Current playback position in seconds
`duration`	number	Total duration in seconds
`playlistId`	string \| null	The playlist ID this media belongs to
`mediaUrl`	string	URL of the media file
`title`	string	Title of the media item

Examples

Track Playlist Engagement

const playlistId = 'your-playlist-id';

// Track which videos users start watching
FairShareSDK.media.onStart((payload) => {
  console.log('User started watching:', payload.title);
  console.log('Video duration:', payload.duration, 'seconds');
}, { playlistId });

// Track video completions
FairShareSDK.media.onComplete((payload) => {
  console.log('User finished watching:', payload.title);
}, { playlistId });

Track CTA Clicks in Playlist

FairShareSDK.media.onCtaActionClick((payload) => {
  console.log('CTA clicked on:', payload.mediaId);
  console.log('CTA type:', payload.ctaType);

  if (payload.ctaType === 'cart') {
    console.log('Product added to cart:', payload.productId);
  }
}, { playlistId: 'your-playlist-id' });

Track Watch Progress

FairShareSDK.media.onPause((payload) => {
  const percentWatched = (payload.currentTime / payload.duration) * 100;
  console.log(`Paused "${payload.title}" at ${percentWatched.toFixed(1)}%`);
}, { playlistId: 'your-playlist-id' });

Complete Playlist Analytics

document.addEventListener('DOMContentLoaded', () => {
  const playlistId = 'your-playlist-id';
  const subscriptions = [];

  // Track playlist analytics
  const playlistAnalytics = {
    started: [],
    completed: [],
    ctaClicks: []
  };

  subscriptions.push(
    FairShareSDK.media.onStart((payload) => {
      playlistAnalytics.started.push({
        mediaId: payload.mediaId,
        title: payload.title,
        timestamp: payload.timestamp
      });
    }, { playlistId })
  );

  subscriptions.push(
    FairShareSDK.media.onComplete((payload) => {
      playlistAnalytics.completed.push({
        mediaId: payload.mediaId,
        title: payload.title,
        timestamp: payload.timestamp
      });
    }, { playlistId })
  );

  subscriptions.push(
    FairShareSDK.media.onCtaActionClick((payload) => {
      playlistAnalytics.ctaClicks.push({
        mediaId: payload.mediaId,
        ctaType: payload.ctaType,
        productId: payload.productId,
        timestamp: payload.timestamp
      });
    }, { playlistId })
  );

  // Cleanup function
  window.cleanupPlaylistListeners = () => {
    subscriptions.forEach(unsub => unsub());
    subscriptions.length = 0;
  };
});

Unsubscribing

Every subscription returns an unsubscribe function:

const unsubscribe = FairShareSDK.media.onStart((payload) => {
  console.log('Started:', payload);
}, { playlistId: 'your-playlist-id' });

// Stop listening later
unsubscribe();

CTA Types Reference

Type	Description	Payload Fields
`link`	External URL link	`ctaUrl` contains the destination URL
`cart`	Add to cart action	`productId` contains the variant ID
`email`	Email/contact form	`ctaButtonText` contains button label
`phone`	Phone contact	`ctaButtonText` contains button label

Media Event Listeners — Full event listener documentation
Playlist — Display a playlist of media
Media — Display individual media items