@windstream/react-shared-components 0.2.50 → 0.2.52

package/src/hooks/use-video-analytics.ts

@@ -0,0 +1,126 @@
+import { useRef } from "react";
+
+export type VideoProvider = "youtube" | "vimeo" | "contentful";
+
+export type VideoAnalyticsEventName =
+  | "played"
+  | "paused"
+  | "progress"
+  | "completed"
+  | "fullscreen_toggled"
+  | "closed";
+
+export type VideoAnalyticsPayload = {
+  videoId: string;
+  videoTitle?: string;
+  provider: VideoProvider;
+  position: number;
+  duration: number;
+  percentComplete: number;
+  isFullscreen?: boolean;
+};
+
+export type VideoAnalyticsHandler = (
+  event: VideoAnalyticsEventName,
+  payload: VideoAnalyticsPayload
+) => void;
+
+export type VideoAnalyticsMeta = {
+  videoId: string;
+  videoTitle?: string;
+  provider: VideoProvider;
+};
+
+const PROGRESS_MILESTONES = [25, 50, 75];
+
+// Centralizes progress-milestone/completion dedup so each provider embed
+// only has to report raw play/pause/timeupdate/ended/fullscreen callbacks -
+// none of them know about Segment or the unified event schema.
+export function useVideoAnalytics(onVideoEvent?: VideoAnalyticsHandler) {
+  const firedMilestones = useRef<Set<number>>(new Set());
+  const hasCompleted = useRef(false);
+  const lastPosition = useRef(0);
+  const lastDuration = useRef(0);
+
+  const emit = (
+    meta: VideoAnalyticsMeta,
+    event: VideoAnalyticsEventName,
+    extra?: Partial<VideoAnalyticsPayload>
+  ) => {
+    if (!onVideoEvent) return;
+    onVideoEvent(event, {
+      videoId: meta.videoId,
+      videoTitle: meta.videoTitle,
+      provider: meta.provider,
+      position: lastPosition.current,
+      duration: lastDuration.current,
+      percentComplete:
+        lastDuration.current > 0
+          ? Math.min(
+              100,
+              Math.round((lastPosition.current / lastDuration.current) * 100)
+            )
+          : 0,
+      ...extra,
+    });
+  };
+
+  const reset = () => {
+    firedMilestones.current = new Set();
+    hasCompleted.current = false;
+    lastPosition.current = 0;
+    lastDuration.current = 0;
+  };
+
+  const handlePlay = (meta: VideoAnalyticsMeta) => emit(meta, "played");
+
+  const handlePause = (meta: VideoAnalyticsMeta) => emit(meta, "paused");
+
+  const handleFullscreenToggle = (
+    meta: VideoAnalyticsMeta,
+    isFullscreen: boolean
+  ) => emit(meta, "fullscreen_toggled", { isFullscreen });
+
+  const handleClosed = (meta: VideoAnalyticsMeta) => emit(meta, "closed");
+
+  const handleTimeUpdate = (
+    meta: VideoAnalyticsMeta,
+    position: number,
+    duration: number
+  ) => {
+    const safePosition = Number.isFinite(position) ? position : 0;
+    const safeDuration = Number.isFinite(duration) ? duration : 0;
+    lastPosition.current = safePosition;
+    lastDuration.current = safeDuration;
+    if (safeDuration <= 0) return;
+    const percent = Math.min(100, (safePosition / safeDuration) * 100);
+    PROGRESS_MILESTONES.forEach(milestone => {
+      if (percent >= milestone && !firedMilestones.current.has(milestone)) {
+        firedMilestones.current.add(milestone);
+        emit(meta, "progress");
+      }
+    });
+
+    if (percent >= 99.5 && !hasCompleted.current) {
+      hasCompleted.current = true;
+      emit(meta, "completed");
+    }
+  };
+
+  const handleEnded = (meta: VideoAnalyticsMeta) => {
+    if (hasCompleted.current) return;
+    hasCompleted.current = true;
+    if (lastDuration.current > 0) lastPosition.current = lastDuration.current;
+    emit(meta, "completed");
+  };
+
+  return {
+    handlePlay,
+    handlePause,
+    handleFullscreenToggle,
+    handleClosed,
+    handleTimeUpdate,
+    handleEnded,
+    reset,
+  };
+}

package/src/types/vimeo-player.d.ts

@@ -0,0 +1,11 @@
+declare module "@vimeo/player" {
+  export default class Player {
+    constructor(
+      element: HTMLIFrameElement | HTMLElement | string,
+      options?: any
+    );
+    on(event: string, callback: (data: any) => void): void;
+    off(event: string, callback?: (data: any) => void): void;
+    destroy(): Promise<void>;
+  }
+}