Zype Analytics 3: Integrating Third-Party Players (Web, Mobile, OTT)

Overview

Zype Analytics 3 provides unified, first-party streaming analytics across web, mobile, and OTT. If you use non-Zype players (e.g., Video.js, AVPlayer, ExoPlayer, Roku native), you can still send full Analytics 3 beacons by using Zype’s Custom JSON Player responses on web and the Bitmovin Analytics collectors on native platforms.

This guide covers:

• How to request the Custom JSON Player for playback and analytics config (web/JS).
• How to attach Bitmovin Analytics collectors in iOS/tvOS (AVPlayer), Android/Android TV (Media3/ExoPlayer), and Roku.
• A unified field mapping for Analytics 3 custom dimensions.

Important: The Analytics 3 license key provided by Zype is dynamic and is returned in the player response. Do not hardcode it; always read it from the player request response at runtime.

Prerequisites

• Your Zype Account Player API key for testing (web).
• Ability to add/modify player integration code in your apps.
• For native apps, include the Bitmovin Analytics collector dependency per platform.

Step 1 — Get the Player Response (Web & Shared Config)

Configure a Player Rule to return the Zype Custom JSON Player for your target platforms/content types. This exposes stream URLs and an analytics3_config block you’ll use to initialize collectors.

Test request (desktop example)

https://player.zype.com/embed/[video_id].json?api_key=[api_key]&autoplay=true

Replace [video_id] and [api_key] with your values. The response includes stream sources and Analytics 3 configuration.

Step 2 — Map Analytics Fields (Unified)

Use the fields below to populate Analytics 3. Many values come directly from the player response (including license key and customData), and some come from your app (e.g., current user ID).

Tip: Use customData7–customData11 for app and player identification (app ID/name/version, player name/version), and customData12–customData18 for content and playout metadata.

Step 3 — Implement by Platform

A) Web (Video.js, HLS.js, DASH.js, HTML5)

1. Include the Bitmovin Analytics web SDK and initialize the appropriate adapter for your player. You can load the collector via script or install via npm/yarn. Example CDN include:

<script type="text/javascript" src="https://resources.zype.com/bitmovin/analytics/2.48.0/bitmovinanalytics.min.js"></script>

2. Video.js example

import { VideojsAdapter } from 'bitmovin-analytics';

// analyticsConfig comes from analytics3_config in player response
const vjsOptions = {
  title: analytics3Config.title,
  videoId: analytics3Config.videoId,
  customData1: analytics3Config.customData1,
  // ...map other customData as needed
};

const player = videojs('my-video', vjsOptions);
const analytics = new VideojsAdapter(analyticsConfig, player);

3. HLS.js example

const player = new Hls();
const analytics = new HlsAdapter(analyticsConfig, player);

4. dash.js example

const time = Date.now();
const dashjsPlayer = dashjs.MediaPlayer().create();
const analytics = new DashjsAdapter(analyticsConfig, dashjsPlayer, { starttime: time });

5. HTML5 video example

const video = document.getElementById('video');
const analytics = new HTMLVideoElementAdapter(analyticsConfig, video);

B) iOS / tvOS (AVPlayer)

1. Pods

# Podfile
pod 'BitmovinAnalyticsCollector/Core'
pod 'BitmovinAnalyticsCollector/AVPlayer', '3.8.1'

2. Attach collector

let config = AnalyticsConfig(licenseKey: licenseKey) // from player response
let sourceMetadata = SourceMetadata(
  videoId: itemId,
  title: item.displayItemTitle(),
  path: path,
  isLive: item.isLive() || item.isLiveChannel(),
  customData: customData
)
let analyticsCollector = AVPlayerCollectorFactory.create(config: config, defaultMetadata: metadata)
analyticsCollector.sourceMetadata = sourceMetadata
analyticsCollector.attach(to: player)

Detach when done: analyticsCollector.detach()

Custom dimensions 1..25 are supported. Populate from the player response config and your app context.

C) Android / Android TV (Media3 ExoPlayer)

1. Dependency

implementation 'com.bitmovin.analytics:collector-media3-exoplayer:3.18.0'

2. Attach collector

val analyticsConfig = AnalyticsConfig(licenseKeyFromResponse, logLevel = LogLevel.DEBUG)
val analyticsCollector = IMedia3ExoPlayerCollector.Factory.create(context, analyticsConfig)

val sourceMetadata = SourceMetadata(
  title = bitmovinConfig?.title ?: "NA",
  videoId = bitmovinConfig?.videoId ?: "NA",
  path = GoogleAnalyaticHandler.getItemPath(menu),
  isLive = bitmovinConfig?.on_air == true || Constant.LIVE_TYPE_KEY.equals(menu?.type, true)
)

val defaultMetadata = DefaultMetadata(
  customUserId = bitmovinConfig?.customUserId ?: currentUserIdFallback,
  customData = buildCustomDataConfig(/* map customData1..n */)
)

analyticsCollector.sourceMetadata = sourceMetadata
analyticsCollector.defaultMetadata = defaultMetadata
analyticsCollector.attachPlayer(player)

// Detach on teardown:
// analyticsCollector.detachPlayer()

D) Roku

Use the Bitmovin Analytics Roku collector. Initialize once per key change and notify on source changes.

sub setBitMovinConfig(key as String)
  if m.global.kAnalytics3Enabled = false then return
  if m.kBitmovinAnalyticsLicense <> key
    m.isBitmovinInitialized = false
    m.kBitmovinAnalyticsLicense = key
  end if
end sub

sub startBitmovinAnalyticsTask(key as String, videoItem as object)
  if m.isBitmovinInitialized = false
    inititalizeBitmovinAnalytics(key, videoItem)
  else
    analyticsConfig = getBitmovinAnalyticsData(videoItem)
    m.nativePlayerCollector.callfunc("setAnalyticsConfig", analyticsConfig)
  end if
end sub

Populate title, videoId, isLive, optional path, and customData1..23 from the player response and app context.

Platform-Agnostic Best Practices

• Always fetch license key and Analytics 3 config from the player response at playback time; do not hardcode.
• Keep customData consistent across platforms (IDs, names, versions) to enable cross-platform rollups within the Zype Analytics dashboards and APIs.
• Attach the collector before playback starts, and detach when the player is torn down.
• For web integrations, use the Custom JSON Player to get streams plus analytics config in a single request.

Troubleshooting

• No data showing? Confirm the collector is initialized with the dynamic license key from the player response and that videoId/title are set.
• Web: Ensure you’re using the correct adapter (Video.js, HLS.js, DASH.js, HTML5) and that the analytics3_config was passed through.
• Native: Verify dependencies and that sourceMetadata/defaultMetadata are assigned before attach.

Appendix: Example Player Rule Uses (Web)

• Prioritize Zype Custom JSON Player for targeted regions/devices, while keeping stock players for others. Then request the JSON player on desktop to validate the config