DocumentationAnalyticsStreaming media services guide

Closed captioning

Last update: June 8, 2026

CREATED FOR:

  • Developer

This page covers data collection for the Closed captioning player state. See Streams impacted by closed captioning, Closed captioning counts, and Closed captioning total duration for the corresponding reporting metrics.

style
shade-box

The closed captioning player state tracks when the viewer turns captions on and off. Fire a state-start event when captions are enabled and a state-end event when captions are disabled. The backend computes three metrics from these events: streams impacted, count of state entries, and total time in state.

Property
Value
Context data variables
a.media.states.closedcaptioning.set, a.media.states.closedcaptioning.count, a.media.states.closedcaptioning.time
XDM collection field
xdm.mediaCollection.statesStart[] and xdm.mediaCollection.statesEnd[] (entries with name: "closedCaptioning")
Audience Manager traits
c_contextdata.a.media.states.closedcaptioning.set, c_contextdata.a.media.states.closedcaptioning.count, c_contextdata.a.media.states.closedcaptioning.time
Required
No
Sent with
State start, state end
Web SDK

Use sendEvent to send a media.statesUpdate event with the state added to statesStart:

code language-javascript 
alloy("sendEvent", {
  xdm: {
    eventType: "media.statesUpdate",
    mediaCollection: {
      statesStart: [{ name: "closedCaptioning" }],
      sessionID: "{sid}",
      playhead: 60
    }
  }
});

When the viewer disables captions, send another event with the state in statesEnd:

code language-javascript 
alloy("sendEvent", {
  xdm: {
    eventType: "media.statesUpdate",
    mediaCollection: {
      statesEnd: [{ name: "closedCaptioning" }],
      sessionID: "{sid}",
      playhead: 90
    }
  }
});
iOS

Use tracker.trackPlayerStateStart() and tracker.trackPlayerStateEnd() with the MediaConstants.PlayerState.CLOSED_CAPTION constant.

code language-swift 
let stateObject = Media.createStateObjectWith(stateName: MediaConstants.PlayerState.CLOSED_CAPTION)

tracker.trackPlayerStateStart(info: stateObject)
tracker.trackPlayerStateEnd(info: stateObject)
Android

Use tracker.trackPlayerStateStart() and tracker.trackPlayerStateEnd() with the MediaConstants.PlayerState.CLOSED_CAPTION constant.

code language-kotlin 
val stateObject = Media.createStateObject(MediaConstants.PlayerState.CLOSED_CAPTION)

tracker.trackPlayerStateStart(stateObject)
tracker.trackPlayerStateEnd(stateObject)
Roku Edge

Use sendMediaEvent to send a media.statesUpdate event with the state added to statesStart:

code language-brightscript 
m.aepSdk.sendMediaEvent({
    "xdm": {
        "eventType": "media.statesUpdate",
        "mediaCollection": {
            "statesStart": [{ "name": "closedCaptioning" }],
            "playhead": 60
        }
    }
})

When the viewer disables captions, send another event with the state in statesEnd:

code language-brightscript 
m.aepSdk.sendMediaEvent({
    "xdm": {
        "eventType": "media.statesUpdate",
        "mediaCollection": {
            "statesEnd": [{ "name": "closedCaptioning" }],
            "playhead": 90
        }
    }
})
Media Edge API

Call the statesUpdate endpoint with closedCaptioning in statesStart (or statesEnd when the viewer disables captions):

code language-json 
{
  "events": [{
    "xdm": {
      "eventType": "media.statesUpdate",
      "mediaCollection": {
        "statesStart": [{ "name": "closedCaptioning" }],
        "sessionID": "{sid}",
        "playhead": 60
      }
    }
  }]
}

Legacy implementation types (Analytics-only)

Media SDK JS 3.x

Use ADB.Media.createStateObject and the ADB.Media.PlayerState.ClosedCaptioning constant:

code language-javascript 
var stateObject = ADB.Media.createStateObject(ADB.Media.PlayerState.ClosedCaptioning);

tracker.trackPlayerStateStart(stateObject);
tracker.trackPlayerStateEnd(stateObject);
Chromecast

Use ADBMobile.media.createStateObject with the "closedCaptioning" string directly, as Chromecast does not have named PlayerState constants:

code language-javascript 
var stateObject = ADBMobile.media.createStateObject("closedCaptioning");
ADBMobile.media.trackEvent(ADBMobile.media.Event.StateStart, stateObject);
// When the viewer disables captions:
ADBMobile.media.trackEvent(ADBMobile.media.Event.StateEnd, stateObject);
Roku 2.x
Player state tracking is not available in the Roku 2.x SDK. To track player states, use the Roku Edge SDK.
Media Collection API

Send a stateStart POST request when captions are enabled, and a stateEnd POST when they are disabled:

code language-json 
{
  "playerTime": { "playhead": 60, "ts": 1699523820000 },
  "eventType": "stateStart",
  "params": {
    "media.state.name": "closedCaptioning"
  }
}

See the Media Collection API events reference for the full request structure.

recommendation-more-help
media-analytics-help