@scarlett-player/analytics 0.2.0

package/dist/index.js

@@ -0,0 +1,582 @@
+// src/helpers.ts
+function generateId() {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substring(2, 11);
+  return `${timestamp}-${random}`;
+}
+function getSessionId() {
+  const STORAGE_KEY = "sp_session_id";
+  try {
+    let sessionId = sessionStorage.getItem(STORAGE_KEY);
+    if (!sessionId) {
+      sessionId = generateId();
+      sessionStorage.setItem(STORAGE_KEY, sessionId);
+    }
+    return sessionId;
+  } catch (error) {
+    return generateId();
+  }
+}
+function getAnonymousViewerId() {
+  const STORAGE_KEY = "sp_viewer_id";
+  try {
+    let viewerId = localStorage.getItem(STORAGE_KEY);
+    if (!viewerId) {
+      viewerId = generateId();
+      localStorage.setItem(STORAGE_KEY, viewerId);
+    }
+    return viewerId;
+  } catch (error) {
+    try {
+      let viewerId = sessionStorage.getItem(STORAGE_KEY);
+      if (!viewerId) {
+        viewerId = generateId();
+        sessionStorage.setItem(STORAGE_KEY, viewerId);
+      }
+      return viewerId;
+    } catch {
+      return generateId();
+    }
+  }
+}
+function getBrowserInfo() {
+  const ua = navigator.userAgent;
+  if (ua.includes("Edg/")) {
+    const match = ua.match(/Edg\/(\d+)/);
+    return {
+      name: "Edge",
+      version: match ? match[1] : void 0
+    };
+  }
+  if (ua.includes("Chrome/") && !ua.includes("Edg/")) {
+    const match = ua.match(/Chrome\/(\d+)/);
+    return {
+      name: "Chrome",
+      version: match ? match[1] : void 0
+    };
+  }
+  if (ua.includes("Safari/") && !ua.includes("Chrome")) {
+    const match = ua.match(/Version\/(\d+)/);
+    return {
+      name: "Safari",
+      version: match ? match[1] : void 0
+    };
+  }
+  if (ua.includes("Firefox/")) {
+    const match = ua.match(/Firefox\/(\d+)/);
+    return {
+      name: "Firefox",
+      version: match ? match[1] : void 0
+    };
+  }
+  if (ua.includes("OPR/") || ua.includes("Opera/")) {
+    const match = ua.match(/(?:OPR|Opera)\/(\d+)/);
+    return {
+      name: "Opera",
+      version: match ? match[1] : void 0
+    };
+  }
+  return { name: "Unknown" };
+}
+function getOSInfo() {
+  const ua = navigator.userAgent;
+  const platform = navigator.platform || "";
+  if (ua.includes("Windows")) {
+    if (ua.includes("Windows NT 10.0")) return { name: "Windows", version: "10" };
+    if (ua.includes("Windows NT 6.3")) return { name: "Windows", version: "8.1" };
+    if (ua.includes("Windows NT 6.2")) return { name: "Windows", version: "8" };
+    if (ua.includes("Windows NT 6.1")) return { name: "Windows", version: "7" };
+    return { name: "Windows" };
+  }
+  if (ua.includes("Mac OS X")) {
+    const match = ua.match(/Mac OS X (\d+)[._](\d+)/);
+    return {
+      name: "macOS",
+      version: match ? `${match[1]}.${match[2]}` : void 0
+    };
+  }
+  if (ua.includes("iPhone") || ua.includes("iPad") || ua.includes("iPod")) {
+    const match = ua.match(/OS (\d+)[._](\d+)/);
+    return {
+      name: "iOS",
+      version: match ? `${match[1]}.${match[2]}` : void 0
+    };
+  }
+  if (ua.includes("Android")) {
+    const match = ua.match(/Android (\d+(?:\.\d+)?)/);
+    return {
+      name: "Android",
+      version: match ? match[1] : void 0
+    };
+  }
+  if (ua.includes("Linux") || platform.includes("Linux")) {
+    return { name: "Linux" };
+  }
+  if (ua.includes("CrOS")) {
+    return { name: "ChromeOS" };
+  }
+  return { name: "Unknown" };
+}
+function getDeviceType() {
+  const ua = navigator.userAgent;
+  if (ua.includes("TV") || ua.includes("PlayStation") || ua.includes("Xbox") || ua.includes("SmartTV")) {
+    return "tv";
+  }
+  if (ua.includes("iPad") || ua.includes("Android") && !ua.includes("Mobile") || ua.includes("Tablet")) {
+    return "tablet";
+  }
+  if (ua.includes("Mobile") || ua.includes("iPhone") || ua.includes("iPod") || ua.includes("Android") && ua.includes("Mobile")) {
+    return "mobile";
+  }
+  return "desktop";
+}
+function getScreenSize() {
+  return `${window.screen.width}x${window.screen.height}`;
+}
+function getPlayerSize(container) {
+  if (!container) {
+    return `${window.innerWidth}x${window.innerHeight}`;
+  }
+  const rect = container.getBoundingClientRect();
+  return `${Math.round(rect.width)}x${Math.round(rect.height)}`;
+}
+function getConnectionType() {
+  const conn = navigator.connection || navigator.mozConnection || navigator.webkitConnection;
+  if (conn) {
+    return conn.effectiveType || conn.type || "unknown";
+  }
+  return "unknown";
+}
+function calculateQoEScore(params) {
+  const {
+    startupTime,
+    rebufferDuration,
+    watchTime,
+    maxBitrate,
+    exitType,
+    errorCount
+  } = params;
+  let startupScore = 100;
+  if (startupTime !== null) {
+    if (startupTime < 1e3) startupScore = 100;
+    else if (startupTime < 2e3) startupScore = 85;
+    else if (startupTime < 4e3) startupScore = 70;
+    else if (startupTime < 8e3) startupScore = 50;
+    else startupScore = 30;
+  }
+  let smoothnessScore = 100;
+  if (watchTime > 0) {
+    const rebufferRatio = rebufferDuration / watchTime * 100;
+    if (rebufferRatio < 0.1) smoothnessScore = 100;
+    else if (rebufferRatio < 1) smoothnessScore = 85;
+    else if (rebufferRatio < 2) smoothnessScore = 70;
+    else if (rebufferRatio < 5) smoothnessScore = 50;
+    else smoothnessScore = 30;
+  }
+  let successScore = 100;
+  if (exitType === "error") {
+    successScore = 0;
+  } else if (errorCount > 0) {
+    successScore = Math.max(0, 100 - errorCount * 10);
+  }
+  let qualityScore = 80;
+  if (maxBitrate > 4e6) qualityScore = 100;
+  else if (maxBitrate > 2e6) qualityScore = 90;
+  else if (maxBitrate > 1e6) qualityScore = 75;
+  else if (maxBitrate > 5e5) qualityScore = 60;
+  else if (maxBitrate > 0) qualityScore = 40;
+  const qoeScore = successScore * 0.3 + startupScore * 0.25 + smoothnessScore * 0.3 + qualityScore * 0.15;
+  return Math.round(qoeScore);
+}
+function isDevelopment() {
+  return window.location.hostname === "localhost" || window.location.hostname === "127.0.0.1" || window.location.hostname.includes(".local");
+}
+function safeStringify(data) {
+  try {
+    return JSON.stringify(data);
+  } catch (error) {
+    return "{}";
+  }
+}
+
+// src/index.ts
+var PLUGIN_VERSION = "0.1.0";
+var PLUGIN_NAME = "scarlett-player";
+var DEFAULT_CONFIG = {
+  heartbeatInterval: 1e4,
+  errorSampleRate: 1,
+  disableInDev: false
+};
+function createAnalyticsPlugin(config) {
+  if (!config.beaconUrl) {
+    throw new Error("Analytics plugin requires beaconUrl");
+  }
+  if (!config.videoId) {
+    throw new Error("Analytics plugin requires videoId");
+  }
+  const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+  let api = null;
+  let session;
+  let heartbeatTimer = null;
+  let lastHeartbeatTime = 0;
+  let isRebuffering = false;
+  let rebufferStartTime = null;
+  let pauseStartTime = null;
+  let cleanupFns = [];
+  function initSession() {
+    return {
+      viewId: generateId(),
+      sessionId: getSessionId(),
+      viewerId: mergedConfig.viewerId || getAnonymousViewerId(),
+      viewStart: Date.now(),
+      playRequestTime: null,
+      firstFrameTime: null,
+      viewEnd: null,
+      watchTime: 0,
+      playTime: 0,
+      pauseCount: 0,
+      pauseDuration: 0,
+      seekCount: 0,
+      startupTime: null,
+      rebufferCount: 0,
+      rebufferDuration: 0,
+      errorCount: 0,
+      errors: [],
+      bitrateHistory: [],
+      qualityChanges: 0,
+      maxBitrate: 0,
+      avgBitrate: 0,
+      playbackState: "loading",
+      exitType: null
+    };
+  }
+  function sendBeacon(eventType, data = {}) {
+    if (mergedConfig.disableInDev && isDevelopment()) {
+      return;
+    }
+    if (eventType === "error" && Math.random() > (mergedConfig.errorSampleRate ?? 1)) {
+      return;
+    }
+    const payload = {
+      // Event info
+      event: eventType,
+      timestamp: Date.now(),
+      // View context
+      viewId: session.viewId,
+      sessionId: session.sessionId,
+      viewerId: session.viewerId,
+      // Video context
+      videoId: mergedConfig.videoId,
+      videoTitle: mergedConfig.videoTitle,
+      isLive: mergedConfig.isLive ?? api?.getState("live") ?? false,
+      // Player context
+      playerVersion: PLUGIN_VERSION,
+      playerName: PLUGIN_NAME,
+      // Environment
+      browser: getBrowserInfo().name,
+      os: getOSInfo().name,
+      deviceType: getDeviceType(),
+      screenSize: getScreenSize(),
+      playerSize: getPlayerSize(api?.container ?? null),
+      connectionType: getConnectionType(),
+      // Custom dimensions
+      ...mergedConfig.customDimensions,
+      // Event-specific data
+      ...data
+    };
+    if (mergedConfig.customBeacon) {
+      mergedConfig.customBeacon(mergedConfig.beaconUrl, payload);
+      return;
+    }
+    if (navigator.sendBeacon) {
+      const blob = new Blob([safeStringify(payload)], {
+        type: "application/json"
+      });
+      navigator.sendBeacon(mergedConfig.beaconUrl, blob);
+    } else {
+      fetch(mergedConfig.beaconUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...mergedConfig.apiKey ? { "X-API-Key": mergedConfig.apiKey } : {}
+        },
+        body: safeStringify(payload),
+        keepalive: true
+      }).catch(() => {
+      });
+    }
+  }
+  function sendHeartbeat() {
+    if (!api) return;
+    const now = Date.now();
+    const timeSinceLastHeartbeat = now - lastHeartbeatTime;
+    session.watchTime += timeSinceLastHeartbeat;
+    if (session.playbackState === "playing" && !isRebuffering) {
+      session.playTime += timeSinceLastHeartbeat;
+    }
+    if (session.bitrateHistory.length > 0) {
+      const totalBitrateTime = session.bitrateHistory.reduce((sum, b, i, arr) => {
+        const nextTime = i < arr.length - 1 ? arr[i + 1]?.time : now;
+        const duration = nextTime - b.time;
+        return sum + b.bitrate * duration;
+      }, 0);
+      session.avgBitrate = Math.round(totalBitrateTime / session.watchTime);
+    }
+    const state = {
+      currentTime: api.getState("currentTime"),
+      duration: api.getState("duration")
+    };
+    sendBeacon("heartbeat", {
+      watchTime: session.watchTime,
+      playTime: session.playTime,
+      currentTime: state.currentTime,
+      duration: state.duration,
+      rebufferCount: session.rebufferCount,
+      rebufferDuration: session.rebufferDuration,
+      avgBitrate: session.avgBitrate,
+      qoeScore: getQoEScore()
+    });
+    lastHeartbeatTime = now;
+  }
+  function getQoEScore() {
+    return calculateQoEScore({
+      startupTime: session.startupTime,
+      rebufferDuration: session.rebufferDuration,
+      watchTime: session.watchTime,
+      maxBitrate: session.maxBitrate,
+      exitType: session.exitType,
+      errorCount: session.errorCount
+    });
+  }
+  function sendViewEnd() {
+    if (!api) return;
+    session.viewEnd = Date.now();
+    const state = {
+      currentTime: api.getState("currentTime"),
+      duration: api.getState("duration")
+    };
+    const completionRate = state.duration ? state.currentTime / state.duration * 100 : 0;
+    sendBeacon("viewEnd", {
+      watchTime: session.watchTime,
+      playTime: session.playTime,
+      startupTime: session.startupTime,
+      rebufferCount: session.rebufferCount,
+      rebufferDuration: session.rebufferDuration,
+      rebufferRatio: session.watchTime > 0 ? session.rebufferDuration / session.watchTime * 100 : 0,
+      avgBitrate: session.avgBitrate,
+      maxBitrate: session.maxBitrate,
+      qualityChanges: session.qualityChanges,
+      pauseCount: session.pauseCount,
+      pauseDuration: session.pauseDuration,
+      seekCount: session.seekCount,
+      errorCount: session.errorCount,
+      exitType: session.exitType,
+      qoeScore: getQoEScore(),
+      completionRate
+    });
+  }
+  function onPlayRequest() {
+    session.playRequestTime = Date.now();
+    sendBeacon("playRequest");
+  }
+  function onPlaying() {
+    const now = Date.now();
+    if (session.firstFrameTime === null) {
+      session.firstFrameTime = now;
+      session.startupTime = session.playRequestTime ? now - session.playRequestTime : null;
+      sendBeacon("videoStart", {
+        startupTime: session.startupTime
+      });
+    }
+    if (isRebuffering && rebufferStartTime) {
+      const rebufferDuration = now - rebufferStartTime;
+      session.rebufferDuration += rebufferDuration;
+      isRebuffering = false;
+      rebufferStartTime = null;
+      sendBeacon("rebufferEnd", {
+        duration: rebufferDuration,
+        totalRebufferTime: session.rebufferDuration
+      });
+    }
+    if (pauseStartTime) {
+      const pauseDuration = now - pauseStartTime;
+      session.pauseDuration += pauseDuration;
+      pauseStartTime = null;
+    }
+    session.playbackState = "playing";
+  }
+  function onPause() {
+    if (!api) return;
+    session.pauseCount++;
+    session.playbackState = "paused";
+    pauseStartTime = Date.now();
+    sendBeacon("pause", {
+      currentTime: api.getState("currentTime")
+    });
+  }
+  function onWaiting() {
+    if (!api) return;
+    if (session.firstFrameTime !== null && !isRebuffering) {
+      isRebuffering = true;
+      rebufferStartTime = Date.now();
+      session.rebufferCount++;
+      sendBeacon("rebufferStart", {
+        rebufferCount: session.rebufferCount,
+        currentTime: api.getState("currentTime")
+      });
+    }
+  }
+  function onSeeking() {
+    if (!api) return;
+    session.seekCount++;
+    sendBeacon("seeking", {
+      seekCount: session.seekCount,
+      seekTo: api.getState("currentTime")
+    });
+  }
+  function onEnded() {
+    session.playbackState = "ended";
+    session.exitType = "completed";
+    sendViewEnd();
+  }
+  function onError(payload) {
+    const error = payload.error;
+    session.errorCount++;
+    const errorEvent = {
+      time: Date.now(),
+      type: error.name || "Error",
+      message: error.message || "Unknown error",
+      fatal: error.fatal ?? false
+    };
+    session.errors.push(errorEvent);
+    sendBeacon("error", {
+      errorType: errorEvent.type,
+      errorMessage: errorEvent.message,
+      errorCode: error.code,
+      fatal: errorEvent.fatal
+    });
+    if (errorEvent.fatal) {
+      session.playbackState = "error";
+      session.exitType = "error";
+      sendViewEnd();
+    }
+  }
+  function onQualityChange(payload) {
+    if (!api) return;
+    const now = Date.now();
+    session.qualityChanges++;
+    const qualities = api.getState("qualities");
+    const currentQuality = qualities.find((q) => q.id === payload.quality);
+    if (currentQuality) {
+      const bitrateChange = {
+        time: now,
+        bitrate: currentQuality.bitrate,
+        width: currentQuality.width,
+        height: currentQuality.height
+      };
+      session.bitrateHistory.push(bitrateChange);
+      if (currentQuality.bitrate > session.maxBitrate) {
+        session.maxBitrate = currentQuality.bitrate;
+      }
+      sendBeacon("qualityChange", {
+        bitrate: currentQuality.bitrate,
+        width: currentQuality.width,
+        height: currentQuality.height,
+        auto: payload.auto
+      });
+    }
+  }
+  function onVisibilityChange() {
+    if (document.hidden) {
+      session.exitType = "background";
+      sendHeartbeat();
+    }
+  }
+  function onBeforeUnload() {
+    if (!session.exitType) {
+      session.exitType = "abandoned";
+    }
+    sendViewEnd();
+  }
+  return {
+    id: "analytics",
+    name: "Analytics",
+    version: PLUGIN_VERSION,
+    type: "analytics",
+    description: "Quality of Experience and engagement analytics",
+    async init(pluginApi) {
+      api = pluginApi;
+      session = initSession();
+      lastHeartbeatTime = Date.now();
+      sendBeacon("viewStart");
+      const unsubPlay = api.on("playback:play", () => {
+        onPlayRequest();
+        onPlaying();
+      });
+      const unsubPause = api.on("playback:pause", onPause);
+      const unsubWaiting = api.on("media:waiting", onWaiting);
+      const unsubSeeking = api.on("playback:seeking", onSeeking);
+      const unsubEnded = api.on("playback:ended", onEnded);
+      const unsubError = api.on("media:error", onError);
+      const unsubQuality = api.on("quality:change", onQualityChange);
+      cleanupFns.push(
+        unsubPlay,
+        unsubPause,
+        unsubWaiting,
+        unsubSeeking,
+        unsubEnded,
+        unsubError,
+        unsubQuality
+      );
+      document.addEventListener("visibilitychange", onVisibilityChange);
+      window.addEventListener("beforeunload", onBeforeUnload);
+      cleanupFns.push(() => {
+        document.removeEventListener("visibilitychange", onVisibilityChange);
+        window.removeEventListener("beforeunload", onBeforeUnload);
+      });
+      heartbeatTimer = setInterval(
+        sendHeartbeat,
+        mergedConfig.heartbeatInterval || 1e4
+      );
+      api.logger.info("Analytics plugin initialized", {
+        viewId: session.viewId,
+        videoId: mergedConfig.videoId
+      });
+    },
+    async destroy() {
+      if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+      }
+      if (!session.viewEnd) {
+        session.exitType = session.exitType || "abandoned";
+        sendViewEnd();
+      }
+      cleanupFns.forEach((fn) => fn());
+      cleanupFns = [];
+      api?.logger.info("Analytics plugin destroyed");
+      api = null;
+    },
+    // === Public API ===
+    getViewId() {
+      return session.viewId;
+    },
+    getSessionId() {
+      return session.sessionId;
+    },
+    getQoEScore() {
+      return getQoEScore();
+    },
+    getMetrics() {
+      return { ...session };
+    },
+    trackEvent(name, data = {}) {
+      sendBeacon(`custom:${name}`, data);
+    }
+  };
+}
+var index_default = createAnalyticsPlugin;
+export {
+  createAnalyticsPlugin,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@scarlett-player/analytics",
+  "version": "0.2.0",
+  "description": "Analytics Plugin for Scarlett Player - QoE metrics and engagement tracking",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@scarlett-player/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^1.6.0",
+    "jsdom": "^24.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.3.0",
+    "vitest": "^1.6.0",
+    "@scarlett-player/core": "0.2.0"
+  },
+  "keywords": [
+    "video",
+    "player",
+    "analytics",
+    "metrics",
+    "qoe",
+    "tracking",
+    "scarlett"
+  ],
+  "author": "The Stream Platform",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hackney-Enterprises-Inc/scarlett-player.git",
+    "directory": "packages/plugins/analytics"
+  },
+  "bugs": {
+    "url": "https://github.com/Hackney-Enterprises-Inc/scarlett-player/issues"
+  },
+  "homepage": "https://scarlettplayer.com",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest --coverage"
+  }
+}