refactor: video analytics support mux embedded iframe (#1636)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: daniel-graham-amplitude

packages/analytics-core/src/video-analytics/track-video.ts

@@ -1,27 +1,36 @@
-import { VideoHandler, StartVideoEvent, PauseVideoEvent, EndedVideoEvent, MuxElement } from './types';
+import {
+  VideoHandler,
+  StartVideoEvent,
+  PauseVideoEvent,
+  EndedVideoEvent,
+  MuxEmbeddedPlayer,
+  MuxElement,
+} from './types';
 
 function getPlayData(videoEl: HTMLVideoElement | MuxElement) {
   return {
     program_duration: videoEl.duration,
   };
 }
 
-function getPauseData(videoEl: HTMLVideoElement | MuxElement) {
-  const currentTime = videoEl.currentTime;
-  const duration = videoEl.duration;
-
+function calculatePercentCompleted(currentTime: number, duration: number) {
   let percentCompleted = 0;
-
   if (Number.isFinite(currentTime) && Number.isFinite(duration) && duration > 0) {
     const rawPercent = (currentTime / duration) * 100;
     // Clamp to [0, 100] to avoid invalid analytics values.
     percentCompleted = Math.min(100, Math.max(0, rawPercent));
   }
+  return percentCompleted;
+}
+
+function getPauseData(videoEl: HTMLVideoElement | MuxElement) {
+  const currentTime = videoEl.currentTime;
+  const duration = videoEl.duration;
 
   return {
     ...getPlayData(videoEl),
     last_position: currentTime,
-    percent_completed: percentCompleted,
+    percent_completed: calculatePercentCompleted(currentTime, duration),
   };
 }
 
@@ -107,8 +116,96 @@ export function trackMuxHtmlVideo(
   return trackHtmlVideo(videoEl, handlers, customMetadata, 'mux');
 }
 
-export function trackMuxEmbeddedVideo() {
-  throw new Error('Not implemented');
+async function getMuxIframeMetadata(player: MuxEmbeddedPlayer, elem: HTMLIFrameElement) {
+  const [duration, currentTime] = await Promise.all([
+    new Promise<number>((resolve) => player.getDuration(resolve)),
+    new Promise<number>((resolve) => player.getCurrentTime(resolve)),
+  ]);
+
+  let url,
+    metadataVideoTitle = null,
+    metadataVideoId = null,
+    playerId = null;
+  try {
+    url = new URL(elem.getAttribute('src') as string);
+    metadataVideoTitle = url.searchParams.get('metadata-video-title');
+    metadataVideoId = url.searchParams.get('metadata-video-id');
+    playerId = url.pathname.split('/').pop();
+  } catch (error) {
+    // invalid or no src url, skip the header metadata
+  }
+  return {
+    percent_completed: calculatePercentCompleted(currentTime, duration),
+    program_duration: duration,
+    last_position: currentTime,
+    mux_video_title: metadataVideoTitle,
+    mux_video_id: metadataVideoId,
+    mux_playback_id: playerId,
+  };
+}
+
+export function trackMuxEmbeddedVideo(
+  player: MuxEmbeddedPlayer,
+  handlers: VideoHandler,
+  customMetadata: Record<string, string | number | boolean>,
+) {
+  const onUnsubscribe: (() => void)[] = [];
+  const readyHandler = () => {
+    const { elem } = player;
+    const playHandler = () => {
+      getMuxIframeMetadata(player, elem)
+        .then((playerState) => {
+          const startEvent: StartVideoEvent = {
+            ...playerState,
+            ...customMetadata,
+          };
+          handlers.onPlay(startEvent);
+        })
+        .catch((error) => {
+          handlers.onError(`Error getting Mux iframe metadata from 'play' handler: ${error as string}`);
+        });
+    };
+    player.on('play', playHandler);
+    onUnsubscribe.push(() => player.off('play', playHandler));
+
+    const pauseHandler = () => {
+      getMuxIframeMetadata(player, elem)
+        .then((playerState) => {
+          const pauseEvent: PauseVideoEvent = {
+            ...playerState,
+            ...customMetadata,
+          };
+          handlers.onPause(pauseEvent);
+        })
+        .catch((error) => {
+          handlers.onError(`Error getting Mux iframe metadata from 'pause' handler: ${error as string}`);
+        });
+    };
+    player.on('pause', pauseHandler);
+    onUnsubscribe.push(() => player.off('pause', pauseHandler));
+
+    const endedHandler = () => {
+      getMuxIframeMetadata(player, elem)
+        .then((playerState) => {
+          const endedEvent: EndedVideoEvent = {
+            ...playerState,
+            ...customMetadata,
+          };
+          handlers.onEnded(endedEvent);
+        })
+        .catch((error) => {
+          handlers.onError(`Error getting Mux iframe metadata from 'ended' handler: ${error as string}`);
+        });
+    };
+    player.on('ended', endedHandler);
+    onUnsubscribe.push(() => player.off('ended', endedHandler));
+  };
+  player.on('ready', readyHandler);
+
+  return () => {
+    player.off('ready', readyHandler);
+    onUnsubscribe.forEach((unsubscribe) => unsubscribe());
+  };
 }
 
 export function trackYoutubeEmbeddedVideo() {

packages/analytics-core/src/video-analytics/types.ts

@@ -2,6 +2,7 @@ type VideoHandler = {
   onPlay: (startEvent: StartVideoEvent) => void;
   onPause: (pauseEvent: PauseVideoEvent) => void;
   onEnded: (endedEvent: EndedVideoEvent) => void;
+  onError: (error: string) => void;
 };
 
 type BaseVideoEvent = {
@@ -30,6 +31,14 @@ type PauseVideoEvent = BaseVideoEvent &
     percent_completed: number;
   };
 
+type MuxEmbeddedPlayer = {
+  getCurrentTime: (cb: (time: number) => void) => void;
+  getDuration: (cb: (duration: number) => void) => void;
+  on: (event: string, callback: () => void) => void;
+  off: (event: string, callback: () => void) => void;
+  elem: HTMLIFrameElement;
+};
+
 type EndedVideoEvent = PauseVideoEvent; // & { ... }
 
 type MuxElement = EventTarget &
@@ -43,4 +52,5 @@ export {
   PauseVideoEvent,
   EndedVideoEvent,
   MuxElement,
+  MuxEmbeddedPlayer,
 };

packages/analytics-core/test/video-analytics/mock-video.ts

@@ -1,4 +1,77 @@
-import type { VideoHandler } from '../../src/video-analytics/types';
+import type { MuxEmbeddedPlayer, VideoHandler } from '../../src/video-analytics/types';
+
+export type MockMuxEmbeddedPlayer = MuxEmbeddedPlayer & {
+  emit: (event: string) => void;
+  setCurrentTime: (time: number) => void;
+};
+
+/**
+ * Minimal player.js-style mock for {@link trackMuxEmbeddedVideo} tests.
+ */
+export function createMockMuxEmbeddedPlayer(options?: {
+  playbackId?: string;
+  metadataVideoTitle?: string;
+  metadataVideoId?: string;
+}): { player: MockMuxEmbeddedPlayer } {
+  const playbackId = options?.playbackId ?? 'dE02GfTAlJD4RcqNAlgiS2m00LqbdFqlBm';
+  const metadataVideoTitle = options?.metadataVideoTitle ?? 'My Video';
+  const metadataVideoId = options?.metadataVideoId ?? 'video-123';
+
+  const params = new URLSearchParams({
+    'metadata-video-title': metadataVideoTitle,
+    'metadata-video-id': metadataVideoId,
+  });
+  const iframe = document.createElement('iframe');
+  iframe.setAttribute('src', `https://player.mux.com/${playbackId}?${params.toString()}`);
+
+  const listeners = new Map<string, Set<() => void>>();
+  let currentTime = 0;
+  const duration = 10;
+
+  const on = (event: string, callback: () => void) => {
+    let set = listeners.get(event);
+    if (!set) {
+      set = new Set();
+      listeners.set(event, set);
+    }
+    set.add(callback);
+  };
+
+  const off = (event: string, callback: () => void) => {
+    listeners.get(event)?.delete(callback);
+  };
+
+  const emit = (event: string) => {
+    const cbs = listeners.get(event);
+    if (cbs) {
+      [...cbs].forEach((cb) => {
+        cb();
+      });
+    }
+  };
+
+  const getDuration = (cb: (d: number) => void) => {
+    cb(duration);
+  };
+
+  const getCurrentTime = (cb: (t: number) => void) => {
+    cb(currentTime);
+  };
+
+  const player: MockMuxEmbeddedPlayer = {
+    elem: iframe,
+    on,
+    off,
+    getDuration,
+    getCurrentTime,
+    emit,
+    setCurrentTime(t: number) {
+      currentTime = t;
+    },
+  };
+
+  return { player };
+}
 
 export function createMockVideo(options: { isMux: boolean } = { isMux: false }): {
   video: HTMLVideoElement;
@@ -60,6 +133,7 @@ export function createMockVideo(options: { isMux: boolean } = { isMux: false }):
     onPlay: jest.fn(),
     onPause: jest.fn(),
     onEnded: jest.fn(),
+    onError: jest.fn(),
   };
 
   return { video, handler };

packages/analytics-core/test/video-analytics/track-video.test.ts

@@ -12,7 +12,7 @@ import {
   trackYoutubeEmbeddedVideo,
 } from '../../src/video-analytics/track-video';
 import type { VideoHandler } from '../../src/video-analytics/types';
-import { createMockVideo } from './mock-video';
+import { createMockMuxEmbeddedPlayer, createMockVideo } from './mock-video';
 
 describe('trackHtmlVideo', () => {
   let video: HTMLVideoElement;
@@ -111,8 +111,129 @@ describe('trackMuxHtmlVideo', () => {
 });
 
 describe('trackMuxEmbeddedVideo', () => {
-  test('throws until implemented', () => {
-    expect(() => trackMuxEmbeddedVideo()).toThrow('Not implemented');
+  let player: ReturnType<typeof createMockMuxEmbeddedPlayer>['player'];
+  let handler: VideoHandler;
+
+  beforeEach(() => {
+    jest.useFakeTimers();
+    ({ player } = createMockMuxEmbeddedPlayer());
+    handler = {
+      onPlay: jest.fn(),
+      onPause: jest.fn(),
+      onEnded: jest.fn(),
+      onError: jest.fn(),
+    };
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  test('should track play, pause and ended events', async () => {
+    const untrack = trackMuxEmbeddedVideo(player, handler, { hello: 'world' });
+
+    player.emit('ready');
+
+    const muxMetadata = {
+      mux_playback_id: 'dE02GfTAlJD4RcqNAlgiS2m00LqbdFqlBm',
+      mux_video_id: 'video-123',
+      mux_video_title: 'My Video',
+    };
+
+    player.setCurrentTime(0);
+    player.emit('play');
+    await jest.runAllTimersAsync();
+    expect(handler.onPlay).toHaveBeenCalledWith({
+      last_position: 0,
+      percent_completed: 0,
+      program_duration: 10,
+      hello: 'world',
+      ...muxMetadata,
+    });
+
+    player.setCurrentTime(5);
+    player.emit('pause');
+    await jest.runAllTimersAsync();
+    expect(handler.onPause).toHaveBeenCalledWith({
+      last_position: 5,
+      percent_completed: 50,
+      program_duration: 10,
+      hello: 'world',
+      ...muxMetadata,
+    });
+
+    player.setCurrentTime(10);
+    player.emit('ended');
+    await jest.runAllTimersAsync();
+    expect(handler.onEnded).toHaveBeenCalledWith({
+      last_position: 10,
+      percent_completed: 100,
+      program_duration: 10,
+      hello: 'world',
+      ...muxMetadata,
+    });
+
+    untrack();
+    handler.onPlay = jest.fn();
+    player.emit('play');
+    await jest.runAllTimersAsync();
+    expect(handler.onPlay).not.toHaveBeenCalled();
+  });
+
+  test('should work when there is no src url', async () => {
+    player.elem.setAttribute('src', null as unknown as string);
+    const untrack = trackMuxEmbeddedVideo(player, handler, { foo: 'bar' });
+    player.emit('ready');
+    player.emit('play');
+    await jest.runAllTimersAsync();
+    expect(handler.onPlay).toHaveBeenCalledWith({
+      last_position: 0,
+      program_duration: 10,
+      percent_completed: 0,
+      foo: 'bar',
+      mux_playback_id: null,
+      mux_video_id: null,
+      mux_video_title: null,
+    });
+    untrack();
+    handler.onPlay = jest.fn();
+    player.emit('play');
+    await jest.runAllTimersAsync();
+    expect(handler.onPlay).not.toHaveBeenCalled();
+  });
+
+  describe('when there is an error getting the metadata', () => {
+    let originalGetDuration: typeof player.getDuration;
+    beforeEach(() => {
+      originalGetDuration = player.getDuration;
+      player.getDuration = jest.fn().mockImplementation(() => {
+        throw new Error('Error getting duration');
+      });
+      trackMuxEmbeddedVideo(player, handler, { hello: 'world' });
+      player.emit('ready');
+    });
+
+    afterEach(() => {
+      player.getDuration = originalGetDuration;
+    });
+
+    test('should call the error handler (play)', async () => {
+      player.emit('play');
+      await jest.runAllTimersAsync();
+      expect(handler.onError).toHaveBeenCalledTimes(1);
+    });
+
+    test('should call the error handler (pause)', async () => {
+      player.emit('pause');
+      await jest.runAllTimersAsync();
+      expect(handler.onError).toHaveBeenCalledTimes(1);
+    });
+
+    test('should call the error handler (ended)', async () => {
+      player.emit('ended');
+      await jest.runAllTimersAsync();
+      expect(handler.onError).toHaveBeenCalledTimes(1);
+    });
   });
 });