Feature Cmcdv2

[cotid-qualabs]

This Pull Request introduces comprehensive support for CMCD (Common Media Client Data) Version 2, significantly expanding the player's capabilities for media analytics and client-side data reporting. The changes allow for more granular control over what data is sent, how it's sent, and to where, aligning with the latest CMCD specifications.

Key Features & Enhancements:

1. CMCD v2 Specification Adherence:

   • Supported CMCD v2 keys:
     • ltc - rc - bg - sta - ttfb - ttlb - ts - url - ec - msd - e - cmsdd - cmsds - df - sn - pb - tpb - bsd
   • Ensures correct mapping to HTTP headers or query parameters for each new mode.
   • Includes a mechanism to differentiate and handle CMCD v1 and v2 logic based on player settings, with a temporary conversion function to manage the transition or ensure backward compatibility where needed, until main conversion function is merged into the Common Media Library.

2. New CMCD Reporting Modes:

   • Event Mode (event): Enables CMCD data reporting triggered by specific player events (e.g., playback state changes, errors) or at configurable time intervals. This allows for real-time or near real-time feedback on player behavior.
     • Supported CMCD Events:
       • ps - e - t
       • Supported Play State events:
         • s - p - k - r -a - w - e - f
   • Response Mode (response): Facilitates CMCD data reporting after a media segment or manifest response is received. This mode includes response-specific metrics like Time To First Byte (ttfb), Time To Last Byte (ttlb), and response code (rc).

3. Multiple Reporting Targets & Granular Configuration:

   • Introduces a new streaming.cmcd.targets array in the player settings. This allows developers to configure multiple CMCD reporting endpoints.
   • Each target can be independently configured with:
     • url: The destination URL for the CMCD report.
     • mode: The data transmission mode to use for this target (query or header ).
     • cmcdMode: The reporting mode to use for this target (event or response).
     • enabledKeys: A specific list of CMCD keys to include for this target. If not defined, sends all available keys for the target. If the list is empty, no keys are sent.
     • events (for event mode): An array of player events that should trigger a CMCD report. If events is not defined, all available events trigger a CMCD report. If the array is empty, no event-specific CMCD data will be sent.
     • timeInterval (for event mode): The interval in seconds for periodic CMCD reports. If value is 0, periodic reports are disabled.
     • includeInRequests (for request/response modes): Specifies which types of HTTP requests (e.g., manifest, mediaSegmentInit, mediaSegment) should include CMCD data for this target.

4. Refined Orchestration of CMCD data via CmcdController:

   • The CmcdController is responsible for orchestrating all CMCD v2 data collection, formatting, and reporting.

5. Refined State Management via CmcdModel:

   • The CmcdModel has been updated to manage and provide the necessary player and media state for all supported CMCD modes and keys, including new v2 parameters.

6. Request/Response Interceptors:

   • The CMCD logic is now more cleanly integrated using request and response interceptors.
   • _cmcdRequestModeInterceptor injects CMCD data into outgoing requests (for query and header modes).
   • _cmcdResponseModeInterceptor processes incoming responses to gather data for response mode and triggers reports.

7. New Sample Pages

   1. CMCD v2
      • CMCD v2 Reporting sample page showcases how to set up CMCD v2 and its new target configurations for each new mode.
   2. Custom Keys and Callback after server response
      • CMCD v2 Callbacks with Network Interceptors sample page introduces a demonstration of using Interceptors to add custom keys as a callback before a report and also processing CMCD data on a callback after the server response.

8. Batching
   The CmcdBatchController is a new component designed to efficiently manage and send Common Media Client Data (CMCD) reports. Instead of sending each report as a separate HTTP request, this controller aggregates them into batches, reducing network traffic and server load.

   1. Batching Mechanism: The controller collects individual CMCD reports and sends them together in a single POST request. The reports are newline-separated in the request body, as specified by the CMCD standard for batched data.
      • Batching by Time (batchTimer): You can configure a batchTimer (in seconds) for a reporting target. When the first report for a target is received, a timer is started. When the timer expires, all collected reports for that target are sent as a single batch.
      • Batching by Size (batchSize): You can configure a batchSize for a reporting target. The controller tracks the number of reports in the current batch. Once the count reaches the batchSize, the batch is sent immediately, even if the batchTimer has not expired.
   2. Error Handling: CmcdBatchController includes logic to handle specific HTTP error responses
      • 429 (Too Many Requests): If a reporting server responds with a 429 status, the controller will not discard the report. Instead, it will attempt to resend the batch after a delay. It uses a retry mechanism with increasing backoff periods to avoid overwhelming the server.
      • 410 (Gone): If a server responds with a 410 status, it indicates that the endpoint is no longer available. The controller will mark that URL as "gone" and will not attempt to send any further reports to it for the remainder of the session.

9. Unit Testing

   • Expanded the existing unit test suite to cover CMCD v2 scenarios and different configurations.

10. Common Media Library Integration

    • Refactoring of the Common Media Client Data (CMCD) implementation. By updating the @svta/common-media-library dependency and leveraging its enhanced encodeCmcd function, the project centralizes CMCD key filtering, whitelisting, and custom key management within the external library.

Main Files Affected:

• src/streaming/controllers/CmcdController.js: Contains the core logic for CMCD v2, including handling for new modes, multiple targets, key filtering, and integration with the CMCD library.
• src/streaming/models/CmcdModel.js: Updated to store and manage state for new CMCD v2 parameters and reporting modes.
• src/core/Settings.js (implied changes): Updated to include new configuration options for CMCD v2, particularly the streaming.cmcd.targets array and CMCD version selection.

These changes provide a much more flexible and powerful CMCD implementation, enabling richer analytics and better interoperability with CDNs and other services that consume CMCD data.

Future Work

While the current implementation of CMCD v2 in dash.js provides basic functionality, there are several areas identified for future enhancements and development:

• Implement Remaining CMCDv2 Keys: Review the CMCDv2 specification and implement any currently unsupported keys to provide a more complete and spec-compliant CMCD reporting solution. Prioritize implementation based on common use cases and community feedback.

[littlespex]

Instead of DASH specific terms like mpd, should this just be a list of CmcdObjectType values?

[cotid-qualabs]

That is a good observation, the only catch I see is that not all the request types that we need are present on the CmcdObjectType. Here are the values that we use for filtering:

const filtersTypes = {
            [HTTPRequest.INIT_SEGMENT_TYPE]: 'segment',
            [HTTPRequest.MEDIA_SEGMENT_TYPE]: 'segment',
            [HTTPRequest.XLINK_EXPANSION_TYPE]: 'xlink',
            [HTTPRequest.MPD_TYPE]: 'mpd',
            [HTTPRequest.CONTENT_STEERING_TYPE]: 'steering',
            [HTTPRequest.OTHER_TYPE]: 'other',
};

src/streaming/models/CmcdModel.js:607

Some types like xlink or steering seems like are not being mapped into CmcdObjectType, so we would only be able to replace some of the values (like mpd, other and init) for the CmcdObjectType.

[littlespex]

Wouldn't they be listed as CmcdObjectType.OTHER? Steering is an interesting use case. @nicolaslevy Should that be added to spec as another object type?

[littlespex]

The header mapping in CML was updated with the new CMCD v2 keys in version 0.15.1. This function should no longer be needed.