Class CmcdReporter<C>

Creates a new CMCD reporter.

Applies the CMCD request report data to the request. The player calls this method before sending the request.

Creates a new request with the CMCD request report data applied. The player calls this method before sending the request.

A reporter with a concrete C requires the request's customData to satisfy that type. TypeScript therefore rejects a call whose request the configured transform could not read. See CmcdReporterCustomData.

Sends all outstanding event reports, regardless of the batch size or interval. Use this method when the player is destroyed or a playback session ends.

Checks whether request reporting is enabled.

Records an event. The player calls this method when an event occurs.

For state-change events (PLAY_STATE, PLAYBACK_RATE, CONTENT_ID, BACKGROUNDED_MODE, BITRATE_CHANGE), this method:

1. Writes the state field from data (if present) into the reporter's data store, as update() would.
2. Discards the event if the state field has no value after that write (never set, or cleared with update({ field: undefined })).
3. Suppresses the event if the field's current value equals the last reported value (no state transition). CmcdReporter.update describes the bg value that a new session starts with.

The reporter always records all other event types.

For state-change events, prefer CmcdReporter.update, also for context fields in a combined call like update({ sta: 'p', bl: [3000], mtp: [8500] }). After update() auto-fires a state-change event, deduplication suppresses a recordEvent() call for the same event, and that call's data is silently lost.

Call recordEvent() directly for events whose data comes with the event call. Examples: CUSTOM_EVENT with cen, ERROR with ec, ad lifecycle events, MUTE/UNMUTE, PLAYER_EXPAND/PLAYER_COLLAPSE, SKIP. For RESPONSE_RECEIVED, prefer CmcdReporter.recordResponseReceived, which derives the per-response fields automatically.

Records a response-received event. The player calls this method when a media request response has fully arrived.

This method derives these rr event keys automatically:

• url - the original requested URL (before any redirects)
• rc - the HTTP response status code
• ts - the request initiation time (from resourceTiming.startTime)
• ttfb - time to first byte (from resourceTiming.responseStart)
• ttlb - time to last byte (from resourceTiming.duration)

If the player has additional keys like ttfbb, cmsdd, cmsds, and smrt, pass them in the data parameter.

The request's customData is generic, so a player can pass a request with its own keys (for example { requestType: 'segment' }) without a cast. The reporter reads only the provenance record that CmcdReporter.createRequestReport writes there. Every other key stays unchanged and visible to an event target's transform through its request argument.

A reporter with a concrete C requires the request to satisfy that type. TypeScript therefore rejects a call whose request the configured transforms could not read. See CmcdReporterCustomData.

The provenance record that CmcdReporter.createRequestReport stored on the request's customData (under CMCD_REQUEST_PROVENANCE) selects the session by sid. A record that names no retained session drops the response (see CmcdReporterConfig.sessionRetention). A request without a record reports under the current session, as in version 2.4.0. The request-time data then comes from customData.cmcd. A per-call data.sid cannot substitute. The reporter accepts any record whose sid names a retained session. The record may come from another reporter with the same session attributes, or be hand-built. If the request has a record, a response that completes after a sid change reports under its own retained session, with that session's data snapshot and sequence numbers.

With a record, request-time report keys come from the record's encoded per-call data snapshot, which the reporter decodes for each response. The record's cid replaces the session's current cid in the report. A response that completes after a mid-session content change therefore reports its request-time values.

Starts the CMCD reporter. The player calls this method when it enables the reporter.

This method fires an initial time-interval event immediately (synchronously), before the first interval elapses. Populate the CMCD data (sid, cid, and others) before calling start().

Stops the CMCD reporter. The player calls this method when it disables the reporter.

Updates the CMCD data.

The player calls this method when data changes. The tracked state fields are sta, pr, cid, bg, and br. If a new value for one of them differs from the last reported value for that field, the reporter fires the matching state-change event. The comparison uses the last reported value, not the previous persisted value. The first state-change event in a new session therefore always fires, even when the persisted value did not change across the sid boundary.

The bg field is an exception. A session that does not start with bg: true begins with false as its last reported bg value. bg: false therefore fires BACKGROUNDED_MODE only if the session started with bg: true or reported bg: true. CTA-5004-B defines a b event without bg as the exit from backgrounded mode, so the exit report does not carry bg. A target transform can add bg: false to the exit report. The encoder writes that value as ?0.

Multi-field updates fire the events in this order: sta, pr, cid, bg, br. The order of keys in the input object does not affect the firing order.

A state-change event can include context fields, for example bl, mtp, pt, ltc. Those fields must be in the data store before the state field changes. Either pass them with the state field in the same update() call, or persist them with earlier update() calls. An auto-fired event reports the current content of the data store. TIME_INTERVAL events also read the data store, and the caller cannot add per-call data to them. The player must therefore update the fields it wants in periodic reports with this method.

A sid change resets the deduplication baseline.

sid and msd are session-owned. The reporter tracks them itself and writes them into every outgoing report, so this method is the only way to change them. A per-call value on CmcdReporter.recordEvent, CmcdReporter.createRequestReport, or CmcdReporter.recordResponseReceived has no effect. msd must be a finite number of milliseconds between 0 and 999_999_999_999_999 (the RFC 8941 integer maximum). The reporter rounds msd to the nearest integer and ignores invalid values.