feat(analytics): add video analytics pipeline with ingest server, event tracking, and ClickHouse schema by aman051197 · Pull Request #3 · imagekit-developer/imagekit-video-player

aman051197 · 2026-04-16T04:23:19Z

No description provided.

…nt tracking, and ClickHouse schema

…ack first view load

…g in analytics tracker

…config

…in PresentUpcoming component

… player adapter to prevent unintended pause events

…d transport layer improvements

…d size-based flush trigger

…n_fix Enhance analytics tracking with custom dimensions and transport improvements

…g in analytics

Copilot

Pull request overview

This PR introduces a new client-side analytics pipeline for the ImageKit Video Player (event tracking → batching → wire-format encoding → ingest transport), wires it into the player plugin behind an analytics.enabled flag, and adjusts playlist thumbnail handling to avoid mutating shared source objects.

Changes:

Added an analytics subsystem (types, state machine, Video.js adapter, batching/transport, v1 wire format).
Integrated analytics initialization into the core player plugin + added analytics options to the public IKPlayerOptions.
Updated playlist thumbnail generation to avoid mutating the original playlist/source objects when applying default poster transformations.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
packages/video-player/javascript/modules/playlist/thumbnail.ts	Avoids mutating shared playlist item state when preparing poster thumbnails (but needs a `prepared` null-guard fix).
packages/video-player/javascript/modules/playlist/present-upcoming.ts	Clones playlist items before applying default poster transformation for “Next up” UI.
packages/video-player/javascript/modules/playlist/playlist-menu-item.ts	Clones playlist items before applying default poster transformation; caches prepared thumbnail.
packages/video-player/javascript/modules/analytics/wire-format-v1.ts	Defines v1 positional wire schema + context key mapping + encoder/decoder utilities.
packages/video-player/javascript/modules/analytics/video-scale-percentage.ts	Computes up/down-scale percentages from decoded vs displayed video size.
packages/video-player/javascript/modules/analytics/types.ts	Adds analytics event/context types aligned with ingest schema expectations.
packages/video-player/javascript/modules/analytics/transport.ts	Implements gzip→base64url GET transport with conditional `keepalive`.
packages/video-player/javascript/modules/analytics/player-adapter.ts	Adapts Video.js runtime events into normalized analytics signals.
packages/video-player/javascript/modules/analytics/id-factory.ts	Generates/persists session/player/playback/event identifiers.
packages/video-player/javascript/modules/analytics/event-row-encoder.ts	Encodes internal events into canonical/slim shapes for wire encoding.
packages/video-player/javascript/modules/analytics/constants.ts	Adds analytics defaults (ingest URL, batching knobs, thresholds).
packages/video-player/javascript/modules/analytics/batch-queue.ts	Buffers events and flushes on interval/size/lifecycle triggers.
packages/video-player/javascript/modules/analytics/analytics-tracker.ts	Orchestrates state machine + adapter + batching + context capture; hooks into plugin lifecycle.
packages/video-player/javascript/modules/analytics/analytics-state-machine.ts	Enforces valid analytics event sequencing and computes timings.
packages/video-player/javascript/interfaces/Player.ts	Extends public options with `analytics` config + error mapping types.
packages/video-player/javascript/index.ts	Instantiates the analytics tracker when `analytics.enabled` is true.
packages/video-player/astro/IKVideoPlayer.astro	Adds imperative `mapError` wiring support for Astro (functions not serializable).
examples/vue/src/App.vue	Demonstrates enabling analytics in Vue example config.
examples/react/src/App.tsx	Demonstrates enabling analytics in React example config.
examples/javascript/vite.config.ts	Adds a second “try-it-yourself” page entry.
examples/javascript/src/try-it-yourself.ts	Enables analytics via feature toggle in the JS example configurator.
examples/javascript/pages/try-it-yourself-2.html	Adds an internal test page with analytics option in the UI.
examples/astro/src/pages/index.astro	Adds an Astro example showing imperative `mapError` usage.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+        case 'dispose':
+          stateMachine.dispatch({ type: 'dispose' }, captureContext);
+          batchQueue.flush('dispose');
+          break;


+    ingestUrl: config.ingestUrl,
+    flushIntervalMs: config.flushIntervalMs,
+    maxBatchSize: config.maxBatchSize,
+    debug: config.debug,
+  });
+


+  // Flush when page goes hidden (e.g. tab switch, navigation away).
+  if (typeof document !== 'undefined') {
+    const onVisibilityChange = () => {
+      if (document.visibilityState === 'hidden') {
+        batchQueue.flush('visibility_hidden');
+      }
+    };
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    cleanup.register(() => document.removeEventListener('visibilitychange', onVisibilityChange));
+  }


+/**
+ * Batches analytics events and flushes to ingest server.
+ * v1 transport: every flush is a `GET ingestUrl?d=<base64url(gzip(json))>` with `keepalive: true`.
+ * Size-based flush trigger guarantees URL stays under ANALYTICS_URL_SAFE_LIMIT_BYTES.
+ */


+    // Size-based trigger: keep URL safely under the limit.
+    if (projectedBatchJsonLength() >= ANALYTICS_RAW_JSON_FLUSH_THRESHOLD) {
+      doFlush('size_limit');
+    }


+/** Analytics ingest endpoint. */
+export const ANALYTICS_INGEST_URL = 'https://stage-ikedge.imagekit.io/b';


    if (item.prepared.playlistThumbnail) {
      return item.prepared.playlistThumbnail;
    }
-    if (!item.poster?.transformation) {
-      if (!item.poster) {
-        item.poster = {};
-      }
-      item.poster.transformation = [DEFAULT_TRANSFORMATION]
-
+


… user activity tracking

… and update analytics interfaces

…tics state machine

…sions, and mapError functionality

…ples

Copilot

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 5 comments.

+    // Mint a new playback_id for the rotated view; tracker is the owner of playback ids.
+    const newPlaybackId = createPlaybackId();
+    currentPlaybackId = newPlaybackId;
+    stateMachine.dispatch({
+      type: 'session_rotated',
+      newPlaybackId,
+      previousSessionId,
+      videoSourceUrl: previousVideoSourceUrl ?? undefined,
+    });


+const PLUGIN_NAME = 'imagekit-video-player';
+const PLUGIN_VERSION = '1.0.0-beta.1';
+const PLAYER_SOFTWARE = 'video.js';
+const PLAYER_SOFTWARE_VERSION = '8.20.0';


+  type MapErrorFn = (error: { code: string; message?: string; context?: string }) =>
+    { code?: string; message?: string; context?: string } | null | undefined;


+  function doFlush(reason: FlushReason) {
+    if (events.length === 0 || !lastContext) return;
+    const batch = events.splice(0, events.length);
+    const slim = batch.map(toSlimEvent);
+    const req = buildIngestRequestV1(lastContext, slim, reason ?? '');
+    if (debug) {


aman-imagekit added 6 commits April 16, 2026 09:48

feat(analytics): add video analytics pipeline with ingest server, eve…

948577e

…nt tracking, and ClickHouse schema

feat(analytics): mandatory playback ID to remove duplicate row and tr…

ee93524

…ack first view load

feat(analytics): enhance codec detection and video source URL handlin…

b31088c

…g in analytics tracker

feat(video-player): add new "Try It Yourself 2" page and update Vite …

b00bd4f

…config

feat(video-player): implement default poster transformation handling …

d8ed9df

…in PresentUpcoming component

Merge branch 'dev' into video_analytics

80d7d35

aman051197 had a problem deploying to github-pages April 30, 2026 05:45 — with GitHub Actions Failure

aman051197 temporarily deployed to github-pages April 30, 2026 06:34 — with GitHub Actions Inactive

feat(analytics): improve seek handling in analytics state machine and…

ff2b884

… player adapter to prevent unintended pause events

aman051197 temporarily deployed to github-pages May 19, 2026 05:10 — with GitHub Actions Inactive

aman-imagekit and others added 3 commits May 28, 2026 08:56

feat(analytics): enhance analytics tracking with custom dimensions an…

2f6b966

…d transport layer improvements

feat(analytics): refactor batch processing to use v1 transport and ad…

2066246

…d size-based flush trigger

Merge pull request #7 from imagekit-developer/video_analytis_ingestio…

f232a67

…n_fix Enhance analytics tracking with custom dimensions and transport improvements

aman051197 temporarily deployed to github-pages May 28, 2026 05:01 — with GitHub Actions Inactive

aman-imagekit added 2 commits May 31, 2026 01:24

feat(analytics): add mapError function to remap/enrich error reportin…

444a2a8

…g in analytics

Merge branch 'video_analytis_ingestion_fix' into video_analytics

c904d51

aman051197 temporarily deployed to github-pages May 30, 2026 18:30 — with GitHub Actions Inactive

aman-imagekit added 2 commits June 2, 2026 09:55

Merge branch 'main' into video_analytics

9c9d6ef

feat(analytics): implement imperative mapError for astro support

06da939

aman051197 changed the base branch from dev to main June 2, 2026 03:01

aman051197 had a problem deploying to github-pages June 2, 2026 03:01 — with GitHub Actions Failure

aman051197 requested a review from Copilot June 2, 2026 03:19

Copilot started reviewing on behalf of aman051197 June 2, 2026 03:19 View session

Copilot AI reviewed Jun 2, 2026

View reviewed changes

feat(analytics): implement session rotation and predecessor links for…

803a7a1

… user activity tracking

aman051197 had a problem deploying to github-pages June 2, 2026 13:44 — with GitHub Actions Failure

fix(analytics): build for astro

99f95ff

aman051197 temporarily deployed to github-pages June 3, 2026 00:29 — with GitHub Actions Inactive

aman-imagekit added 2 commits June 4, 2026 00:06

feat(analytics): add reportError method for non-fatal error reporting…

8337565

… and update analytics interfaces

feat(analytics): add support for application-reported errors in analy…

847467b

…tics state machine

feat(analytics): enhance analytics options with user ID, custom dimen…

fa7486f

…sions, and mapError functionality

aman051197 had a problem deploying to github-pages June 3, 2026 17:23 — with GitHub Actions Failure

fix(analytics): standardize user ID property to camelCase across exam…

79ca423

…ples

aman051197 temporarily deployed to github-pages June 4, 2026 00:44 — with GitHub Actions Inactive

fix(analytics): improve batch queue flush logic and cleanup handling

4bf4ff1

aman051197 deployed to github-pages June 4, 2026 03:02 — with GitHub Actions View deployment

aman051197 requested a review from Copilot June 4, 2026 03:06

Copilot started reviewing on behalf of aman051197 June 4, 2026 03:06 View session

Copilot AI reviewed Jun 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(analytics): add video analytics pipeline with ingest server, event tracking, and ClickHouse schema#3

feat(analytics): add video analytics pipeline with ingest server, event tracking, and ClickHouse schema#3
aman051197 wants to merge 21 commits into
mainfrom
video_analytics

aman051197 commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		/** Analytics ingest endpoint. */
		export const ANALYTICS_INGEST_URL = 'https://stage-ikedge.imagekit.io/b';

		type MapErrorFn = (error: { code: string; message?: string; context?: string }) =>
		{ code?: string; message?: string; context?: string } \| null \| undefined;

Conversation

aman051197 commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants