Request for Comments: CMCD v2 Javascript API for dash.js

[nicolaslevy]

Currently, at Qualabs, we are implementing some functionalities of CMCD v2 in order to provide implementation feedback to the group that is developing the CMCD v2 specification.

In this issue, the goal is to gather comments, recommendations, and viewpoints to help define a JavaScript API that encompasses both CMCD v1 and CMCD v2.

As a reminder, below is the JavaScript API for the CMCD v1 implementation of dash.js (and most players).

cmcd: {
    enabled: true, /* enable or disable */
    sid: "b248658d-1d1a-4039-91d0-8c08ba597da5", /* session id send with each request */
    cid: "21cf726cfe3d937b5f974f72bb5bd06a", /* content id send with each request */
    mode: CMCD_MODE_QUERY,  /* Query or Headers */
    enabledKeys: ["br",  "sf", "sid", "st", "v"], /*Keys to include in the CMCD report*/
}

This JavaScript API proposal for CMCD v2 in dash.js aims to be as backward compatible as possible with the API for version 1, where it's only necessary to change the version field and add the minimum amount of configuration applicable to each report mode. On the other hand, the "request-mode" is the default mode enabled, and the other two new modes can be added through configuration.

cmcd: {
    enabled: true, /* global enable or disable */
    sid: "b248658d-1d1a-4039-91d0-8c08ba597da5", /* session id send with each request */
    cid: "21cf726cfe3d937b5f974f72bb5bd06a", /* content id send with each request */
    mode: CMCD_MODE_QUERY,  /* gobal mode if not specified in each mode */
    enabledKeys: ["br",  "sf", "sid", "st", "v", ], /* optional, gobal keys if not specified in each mode. Note that any mandatory keys for each mode will be automatically added and do not need to be provisioned */
    reporting: {
        requestMode: {
            version: 1 /* version 1 by default for backward compatibility */
            enabled: true, /*by default is always true for this mode for backward compatibility*/
            mode: CMCD_MODE_QUERY /*overrides mode in upper level*/
            enabledKeys: ["br",  "sf", "sid", "st", "v"], /*optional, overrides global keys. Note that any mandatory keys for each mode will be automatically added and do not need to be provisioned */
        },
        responseMode: {
            enabled: false, /*by default is always FALSE for this mode*/
            mode: CMCD_MODE_HEADER /*optional, overrides mode in upper level*/
            requestMethod: "GET", /*optional, GET by defautl*/
            reportingUrl: "http://<url>/endpoint" /*mandatory, URL to send report*/
            enabledKeys: ["br",  "sf", "sid", "st", "v"], /*optional, overrides global keys. Note that any mandatory keys for each mode will be automatically added and do not need to be provisioned*/
        },
        stateIntervalMode: {
            enabled: false, /*by default is always FALSE for this mode*/
            mode: CMCD_MODE_JSON /*optional, overrides mode in upper level*/
            requestMethod: "POST", /*optional, POST by defautl*/
            interval: 30, /*optional, default is 30 seconds*/ 
            reportingUrl: "http://<url>/endpoint" /* mandatory, URL to send report*/
            enabledKeys: ["br",  "sf", "sid", "st", "v"], /*optional, overrides global keys. Note that any mandatory keys for each mode will be automatically added and do not need to be provisioned*/
        },
    }
}

Examples using this proposal:

CMCD v1 configuration (backward compatibility):

cmcd: {
    enabled: true,
    sid: "b248658d-1d1a-4039-91d0-8c08ba597da5",
    cid: "21cf726cfe3d937b5f974f72bb5bd06a", 
    mode: CMCD_MODE_QUERY,  
    enabledKeys: ["br",  "sf", "sid", "st", "v"]
}

Only request mode with CMCD v2:

cmcd: {
    enabled: true,
    sid: "b248658d-1d1a-4039-91d0-8c08ba597da5",
    cid: "21cf726cfe3d937b5f974f72bb5bd06a",
    mode: CMCD_MODE_QUERY, 
    enabledKeys: ["br",  "sf", "sid", "st", "v"], 
    reporting: {
        requestMode: {
            version: 2 
        },
    }
}

Only response-mode:

cmcd: {
    enabled: true,
    sid: "b248658d-1d1a-4039-91d0-8c08ba597da5",
    cid: "21cf726cfe3d937b5f974f72bb5bd06a",
    mode: CMCD_MODE_QUERY, 
    enabledKeys: ["br",  "sf", "sid", "st", "v"],
    reporting: {
        requestMode: {
            enabled: false,
        },
        responseMode: {
            enabled: true, 
            reportingUrl: "http://some.com/endpoint"
        },
    }
}

In particular, it was mentioned during the 8/22 meeting that it might be confusing to have both a global list of keys (enabledKeys) and a separate one in each reporting mode that can override the global one, especially considering that not all keys defined in CMCD v2 can be sent in all modes. For example, the ttfb (Time To First Byte) key only makes sense in the Response Mode.

It was also mentioned that the word "mode" might be confusing when used to refer to both the new modes (request, response, state-interval) and the place and format of data transmission (query, headers, JSON).

[dsilhavy]

Thanks, some comments based on your description:

• If the globally enabled keys include a parameter like br but the mode specific keys do not contain that parameter: Will it still be reported? Or does the mode specific list of keys override the global list completely?
• I would also avoid using the word mode in two different contexts. I suggest removing the word mode e.g. use requestApproach or something similar.
• dash.js has a field includeInRequests to specify the type of requests that shall carry CMCD parameters, e.g. segment requests. This field is missing in the description.

[slhck]

I have some comments more from an outside perspective (we parse CMCD and sometimes consult in adding support for it for various players):

Mode Naming

If you are going to change the type definitions of the configuration object anyway, you might as well change the mode key to dataTransmissionMode or transmissionMode to distinguish it from the reporting. The mode key could be aliased to dataTransmissionMode and become deprecated for some time before being removed evenutally.

My thinking is that if developers update dependencies and choose to use CMCDv2, they might as well change the configuration because you're going to touch the system anyway.

Version

You might add a global version key to the configuration object so that it's clear which version is targeted with the particular set of options, allowing for easier type definitions and more obvious transition to newer versions, should there be any:

// version 1
cmcd: {
    enabled: true,
    sid: "b248658d-1d1a-4039-91d0-8c08ba597da5",
    cid: "21cf726cfe3d937b5f974f72bb5bd06a", 
    mode: CMCD_MODE_QUERY,  
    enabledKeys: ["br",  "sf", "sid", "st", "v"]
}

Only request mode with CMCD v2:

cmcd: {
    version: 2, // --> enables proper parsing of options with V2 semantics
    enabled: true,
    sid: "b248658d-1d1a-4039-91d0-8c08ba597da5",
    cid: "21cf726cfe3d937b5f974f72bb5bd06a",
    mode: CMCD_MODE_QUERY, 
    enabledKeys: ["br",  "sf", "sid", "st", "v"], 
    reporting: {
        requestMode: {
            // version: 2 --> no longer needed
        },
    }
}

Enabled Keys:

Is there a use case where one wants to enable more keys globally but exclude them for particular modes? In that case, having an ignoredKeys property could be added, so you don't have to completely override the enabled keys for a particular reporting mode (and thereby specify some keys twice), thus the final set of keys would be enabledKeys - ignoredKeys - irrelevant keys for that mode.