Video analytics

ImageKit video player ships with a built-in analytics module that reports engagement and quality-of-experience metrics for every playback session. Add an analytics object to your IKPlayer options to start collecting data and view results in the ImageKit dashboard under video analytics.

Analytics is opt-in. Set analytics.enabled to true to start. Once enabled, the player automatically collects data across four areas:

• Engagement: Who watches, how long, and how much of each video they complete
• Performance: Page, player, and video startup times plus seek responsiveness
• Reliability: Rebuffering, startup failures, and mid-stream errors
• Quality: Bitrate delivered vs. what the screen actually needed

All data is available in the dashboard with filters by device, browser, OS, country, video, and more. See Metrics for the full list.

Pass an analytics object on ikOptions with enabled: true to start the tracker. All other fields are optional.

import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  analytics: {
    enabled: true,                // required to start the tracker
    userId: 'anon-user-abc123',  // optional anonymized ID, not email/username
    customDimensions: {
      cd_1: '2.1.0',              // playerVersion
      cd_2: 'experiment-b'        // experimentBucket
    }
  }
});

player.src({ src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4' });

import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID',
    analytics: {
      enabled: true,
      userId: 'anon-user-abc123',
      customDimensions: { cd_1: '2.1.0', cd_2: 'experiment-b' }
    }
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={{ src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4' }}
    />
  );
}

<template>
  <IKVideoPlayer :ikOptions="ikOptions" :source="source" />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  analytics: {
    enabled: true,
    userId: 'anon-user-abc123',
    customDimensions: { cd_1: '2.1.0', cd_2: 'experiment-b' }
  }
};

const source = { src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4' };
</script>

---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  analytics: {
    enabled: true,
    userId: 'anon-user-abc123',
    customDimensions: { cd_1: '2.1.0', cd_2: 'experiment-b' }
  }
};

const source = { src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4' };
---

<IKVideoPlayer ikOptions={ikOptions} source={source} />

{
  cd_1: 'string',
  cd_2: 'string',
  // ...
}

(error) => { code?, message?, context? } | null | undefined

All metrics below appear in the dashboard under Video analytics → Metrics, and can be sliced by any of the dimensions listed further down.

These metrics are most meaningful when serving Adaptive Bitrate Streaming (ABS) content (HLS or DASH), where the player switches renditions based on network conditions.

In addition to the time-series metrics above, the dashboard surfaces top-N breakdowns: Top Devices, Top Operating Systems, Top Browsers, Top Countries, and Top Videos.

The metrics above are derived from a stream of playback events the player emits automatically once analytics is enabled. You don't subscribe to or handle these events yourself; they are sent to ImageKit in the background and listed here for transparency about what the player tracks. You can see the full event timeline for any individual playback on the playback detail page.

Events are grouped into sessions and views:

• A session is a viewer's continuous engagement within one browser, shared across all players, tabs, and page loads on the same site. It can span multiple videos and resets after 60 minutes of inactivity or 24 hours, whichever comes first. A different browser, profile, or incognito window gets its own session.
• A view is a single video playback within a session, identified by a playbackId. Most metrics are computed per view.

Every metric can be filtered or grouped by the dimensions below. All dimensions are derived server-side from the request and User-Agent. The only ones you control from the player are User ID (userId) and Custom dimensions (customDimensions).

Custom dimensions let you slice analytics by metadata that's specific to your application. for example, app version, A/B test bucket, content category, or subscription tier.

ImageKit uses a two-step model:

1. Register the dimension in the dashboard under Settings → Video analytics → Custom dimensions. You provide a human-readable label (and optional description); the dashboard assigns a stable dimension key such as cd_1, cd_2, …
2. Send values from the player keyed by the dimension key (not the label).

Pass customDimensions in analytics at player initialization, or update them at any time during a session with setCustomDimensions.

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  analytics: {
    enabled: true,
    customDimensions: {
      cd_1: '2.1.0',          // playerVersion
      cd_2: 'experiment-b',   // experimentBucket
      cd_3: 'premium'         // subscriptionTier
    }
  }
});

// Replace the entire map at runtime (e.g. after the viewer signs in)
player.imagekitVideoPlayer().setCustomDimensions({
  cd_1: '2.1.0',
  cd_2: 'experiment-b',
  cd_3: 'enterprise'
});

// Inspect the currently effective values
player.imagekitVideoPlayer().getCustomDimensions();

1. The number of active custom dimensions per account depends on your plan. See pricing.
2. Values are strings only. Values longer than 256 characters are dropped client-side.
3. Disabling a dimension from the dashboard reserves its key permanently; the same key (cd_N) is never reassigned to a new label. This keeps historical data consistent.
4. Keys you send that are not registered for your account are ignored.

• Release impact: Set a key to your player or app version and compare error rates across releases.
• A/B testing: Bucket viewers into experiments and compare quality of experience between groups.
• Content classification: Tag views with content category, genre, or producer to surface which categories perform best.
• Plan-based analysis: Track which tier (free, premium, enterprise) is experiencing issues.

The player automatically reports playback errors with the following fields:

• Error code: the player error code (e.g. Video.js MediaError code)
• Error message: human-readable description from the player
• Error context: JSON-serialized raw error object for debugging

Errors appear in the dashboard under Video analytics → Errors with their full context and contribute to Video Startup Failure Percentage and Playback Failed Percentage.

Use mapError to rewrite the error code, message, or context before it reaches analytics. Common uses:

• Group errors more usefully in dashboards (e.g. extract the specific HLS failure type instead of the generic HTML5 MediaError code). See example below.
• Add your own context like a build version or request ID so you can correlate spikes with releases.
• Redact sensitive data from context if needed.

mapError receives { code, message, context } and may return any subset of those keys. Returning nothing keeps the original values.

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  analytics: {
    enabled: true,
    mapError: (err) => {
      try {
        const ctx = JSON.parse(err.context || '{}');
        // For HLS/DASH errors, ctx.metadata.errorType is something like
        // 'networkrequestfailed' or 'networkrequesttimeout', much more
        // actionable than the generic HTML5 MediaError code.
        if (ctx.metadata?.errorType) {
          return {
            code: ctx.metadata.errorType,
            // You can also enrich `context` to correlate spikes with releases:
            // context: JSON.stringify({ ...ctx, build: window.__BUILD_SHA__ })
          };
        }
      } catch { /* ignore */ }
    }
  }
});

import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID',
    analytics: {
      enabled: true,
      mapError: (err) => {
        try {
          const ctx = JSON.parse(err.context || '{}');
          if (ctx.metadata?.errorType) {
            return { code: ctx.metadata.errorType };
          }
        } catch { /* ignore */ }
      }
    }
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={{ src: 'https://ik.imagekit.io/<your-imagekit-id>/video.m3u8' }}
    />
  );
}

<template>
  <IKVideoPlayer :ikOptions="ikOptions" :source="source" />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  analytics: {
    enabled: true,
    mapError: (err) => {
      try {
        const ctx = JSON.parse(err.context || '{}');
        if (ctx.metadata?.errorType) {
          return { code: ctx.metadata.errorType };
        }
      } catch { /* ignore */ }
    }
  }
};

const source = { src: 'https://ik.imagekit.io/<your-imagekit-id>/video.m3u8' };
</script>

---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  analytics: { enabled: true, userId: 'anon-user-abc123' }
};

const source = { src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4' };
---

<IKVideoPlayer id="player" ikOptions={ikOptions} source={source} />

<script>
  const el = document.querySelector('#player');
  el.mapError = (err) => {
    try {
      const ctx = JSON.parse(err.context || '{}');
      if (ctx.metadata?.errorType) {
        return { code: ctx.metadata.errorType };
      }
    } catch { /* ignore */ }
  };
</script>

Some errors aren't real playback failures. Certain conditions are expected outcomes you don't want polluting your failure metrics.

Classify these in the dashboard under "Error Configuration" in video analytics settings: add the error code (the one reported by the player, or the one you produce via mapError), give it a label, and mark it as a business exception.

• Business-exception codes are excluded by default from Video Startup Failure Percentage and Playback Failed Percentage.
• Toggle "Show excluded errors" on either metric to display business exceptions as a separate line for visibility.

• The standard HTML5 MediaError codes (1–4) are seeded automatically and treated as real errors unless you mark them as exceptions.

The player itself does not classify error severity. Every error reaches the dashboard with the same shape, and classification is applied at query time based on your configuration.

1. Keep userId anonymous. Always pass an opaque, anonymized value (e.g. a hashed internal ID). Never use an email, username, or anything personally identifiable on its own.
2. Use custom dimensions sparingly. High-cardinality values (e.g. unique session tokens) reduce query performance. Prefer low-to-medium cardinality fields like app version, experiment bucket, or content category.
3. Set mapError early so error codes are normalized before they reach the dashboard, keeping your error configuration consistent across releases.
4. Disable in development. Omit the analytics object or set analytics.enabled to false to avoid polluting production metrics with test traffic.
5. No cookies. The analytics module sets no cookies and collects no PII by default.

• Video player overview: Player configuration and source options
• Adaptive Bitrate Streaming: HLS and DASH delivery (enables the Quality metrics above)
• Playlist & recommendations: Sequence videos and show recommendations
• Shoppable videos: Turn videos into shopping experiences
• Subtitles & chapters: Add captions and chapter markers