Player setup

Support overview

Checked against the latest stable releases, their documentation and source code. We have not run conformance tests on these versions.

Stable means released and documented without an experimental label. Available with limits means released, with documented gaps in keys, events or configuration. Experimental means the project labels the feature experimental, so configuration names can still change. Not available means no implementation in the checked version.

Recommended configuration

For every player that offers the choice, send CMCD as a query parameter, set the session ID and content ID explicitly and use the same values for request and event mode. Send CMCD as a query parameter explains why. Replace the highlighted values in the examples with your own.

hls.js

CMCD is part of the full build, not the light build, and is off until you add a cmcd object. CMCD v2 is available since 1.7.0; the release notes state that not all v2 events and fields are supported yet.

const hls = new Hls({
  cmcd: {
    version: 2,
    useHeaders: false,
    sessionId: '<SESSION_ID>',
    contentId: '<CONTENT_ID>',
    eventTargets: [
      {
        url: '<CMCD_V2_ENDPOINT>',
        events: ['ps', 'e', 't'],
        interval: 30,
        batchSize: 1,
      },
    ],
  },
});

• useHeaders: false is the default and sends the CMCD query parameter.
• Without sessionId, hls.js generates a UUID. There is no default content ID.
• An event target without events sends nothing.
• For CMCD v1, omit version and eventTargets.

hls.js API documentation

dash.js

CMCD v2 support has been available since 5.2.0, with further fields being added; EINBLIQ.IO contributed custom keys and improved timing metrics to dash.js 5.3.0.

player.updateSettings({
  streaming: {
    cmcd: {
      enabled: true,
      version: 2,
      mode: 'query',
      sid: '<SESSION_ID>',
      cid: '<CONTENT_ID>',
      eventTargets: [{
        enabled: true,
        url: '<CMCD_V2_ENDPOINT>',
        events: ['ps', 'e', 't'],
        interval: 30,
        batchSize: 1,
        enabledKeys: ['sid', 'cid', 'sta', 'e', 'msd', 'ts'],
      }],
    },
  },
});

• mode: 'query' is the default. The header mode value is 'headers'; the documentation’s 'header' is not recognised and silently keeps query mode.
• Set cid explicitly. Without sid, dash.js generates a UUID.
• enabledKeys of an event target is empty by default, so list the keys you want to send.

dash.js CMCD documentation

Shaka Player

CMCD v1 is stable. Shaka labels CMCD v2 and its event targets as experimental, and the target’s field names may still change.

player.configure({
  cmcd: {
    enabled: true,
    version: 2,
    useHeaders: false,
    sessionId: '<SESSION_ID>',
    contentId: '<CONTENT_ID>',
    eventTargets: [
      {
        enabled: true,
        url: '<CMCD_V2_ENDPOINT>',
        events: ['ps', 'e', 't'],
        interval: 30,
        batchSize: 1,
      },
    ],
  },
});

• Without sessionId, Shaka generates a new UUID for each load().
• There is no configuration option for custom key values.

Shaka Player CMCD configuration

Media3 (ExoPlayer)

Media3 supports CMCD v1 for DASH, HLS and SmoothStreaming. CMCD v2 is not implemented yet (androidx/media#2732). The default transmission mode is headers, so select query mode explicitly:

val cmcdFactory = CmcdConfiguration.Factory { mediaItem ->
  CmcdConfiguration(
    "<SESSION_ID>",
    mediaItem.mediaId,
    object : CmcdConfiguration.RequestConfig {},
    CmcdConfiguration.MODE_QUERY_PARAMETER,
  )
}

val player = ExoPlayer.Builder(context)
  .setMediaSourceFactory(
    DefaultMediaSourceFactory(context).setCmcdConfigurationFactory(cmcdFactory),
  )
  .build()

• The session ID and content ID are limited to 64 characters. CmcdConfiguration.Factory.DEFAULT uses a random UUID and the media ID instead.
• Custom keys are added by overriding RequestConfig.getCustomData().

Media3 CMCD documentation

Apple AVPlayer

AVPlayer sends CMCD v1 for HLS from iOS 18, iPadOS 18, tvOS 18, macOS 15 and visionOS 2 once you opt in. It only uses headers, so your CDN must log the CMCD headers; the CDN guides show where this works.

let asset = AVURLAsset(url: streamURL)
if #available(iOS 18.0, tvOS 18.0, macOS 15.0, visionOS 2.0, *) {
  asset.resourceLoader.sendsCommonMediaClientDataAsHTTPHeaders = true
}
let player = AVPlayer(playerItem: AVPlayerItem(asset: asset))

• AVPlayer does not send the content ID (cid), requested maximum throughput (rtp) or top bitrate (tb).
• There is no API to set the session ID or switch to query parameters.

AVFoundation API reference

Roku

Roku devices send CMCD v1 by default, without configuration in your channel. We see this in the data we process today. Roku does not document the behaviour and offers no settings to change keys, session ID or transmission mode.

CMCD v2 event targets

EINBLIQ.IO provides a CMCD v2 endpoint for event mode. We send you its address during onboarding; it replaces <CMCD_V2_ENDPOINT> in the examples above.

Event reports reach the endpoint as HTTP POST requests with the content type application/cmcd. Because the session ID and content ID join events to your CDN logs, use the same values in event mode as in request mode.