Media Collection API request parameters

This reference lists the parameters accepted by Streaming Media Collection API requests, grouped by category, and explains how request bodies are validated. Parameters are sent inside the params object of a request body (quality-of-experience parameters are sent in qoeData).

In the tables below, Required indicates whether the parameter is mandatory for the event it is set on, Type is the JSON data type, and Set on is the event type the parameter is sent with.

Analytics data

Visitor data

Content data

Content standard metadata

Ad data

Ad standard metadata

Chapter data

Player state data

Quality data

Quality-of-experience parameters are sent in the qoeData object rather than params.

California Consumer Privacy Act (CCPA) parameters

Additional details

visitor.marketingCloudUserId

Pass the Experience Cloud ID (also known as the MID or MCID) on the sessionStart call by including it in the params map using the key visitor.marketingCloudUserId. This is useful if you already integrate with other Experience Cloud products and have already obtained the ECID.

data-variant=note

data-slots=text

appInstallationId

• If you do not pass an appInstallationId value: The back end no longer generates an ECID and instead relies on Adobe Analytics to do so. Adobe recommends sending either an ECID if available, or an appInstallationId (along with the still-mandatory visitor.marketingCloudOrgId) so that the Media Collection API generates the ECID and sends it on all calls.
• If you do pass an appInstallationId value: The ECID can be generated by the back end when you pass values for both appInstallationId and the required visitor.marketingCloudOrgId. If you pass appInstallationId yourself, you must persist its value on the client side. It must be unique to the app on a device and must persist for as long as the app is not reinstalled.

data-variant=note

data-slots=text

visitor.marketingCloudOrgId

In addition to being necessary for ECID generation when one is not provided, this parameter is also used as the publisher ID, which the Media Collection API uses for federation rule matching.

Legacy and declared user IDs

• analytics.aid: The value must be a string representing the Analytics legacy user ID.

• visitor.customerIDs: The value must be an object of the following format:

  "<<insert your ID name here>>": {
    "id": "<<insert your id here>>",
    "authState": <<insert one of 0, 1, 2>>
  }
  

  The visitor.customerIDs value can contain any number of objects in this format.

visitor.aamLocationHint

This parameter indicates which Adobe Audience Manager (AAM) Edge is used when Adobe Analytics sends the customer data to Audience Manager. If no value is entered, the value is null. This is particularly important when end users tend to use their devices in geographically distant locations (for example US-East, US-West, Europe, Asia). Otherwise, user data is spread across multiple AAM Edges.

media.resume

If the app determines that a session was closed and then resumed later (for example, the user left the video but eventually came back and the player resumed from the playhead where it stopped), send an optional boolean media.resume parameter inside the params object of the sessionStart call.

Request validation

The Media Collection API back end validates each request body against a JSON schema specific to its event type. When validation fails, the response returns a 400 with an error message. These schemas are the authority for which parameters are required or optional for each event, and their data types.

The schemas are publicly accessible:

GET https://{uri}/api/v1/schemas/{event-type}

For example, GET https://{uri}/api/v1/schemas/sessionStart returns the schema for the sessionStart event. Each schema is a standard JSON Schema (draft-04) document. The following excerpt shows its shape:

{
  "$schema": "https://json-schema.org/draft-04/schema#",
  "definitions": {
    "playerTime": {
      "type": "object",
      "properties": {
        "playhead": { "type": "number" },
        "ts": { "type": "integer" }
      },
      "required": ["playhead", "ts"],
      "additionalProperties": false
    },
    "eventType": {
      "type": "string",
      "enum": ["sessionStart", "play", "ping", "..."]
    }
  },
  "type": "object",
  "$ref": "#/definitions/sessionStart"
}

data-variant=note

data-slots=text

For a practical walkthrough of validating requests during implementation, see Validating event requests.