Session endpoints

Session endpoints handle the session state of a visitor. Once a session is created, it expires if any of the following are met:

• No events are received for 10 minutes
• No playhead movement happens for 30 minutes
• The sessionEnd endpoint is called

data-variant=error

data-slots=text

sessionStart

The sessionstart endpoint creates a media tracking session for a visitor. A successful response includes a session ID, which is required for all other endpoints. Make sure that you follow Getting started to obtain a datastream ID. See Media Edge API implementation examples for more examples calling this endpoint.

POST https://edge.adobedc.net/ee/va/v1/sessionStart?configId={datastream ID}

data-slots=heading, code

data-repeat=2

data-languages=CURL,JSON

curl -X POST "https://edge.adobedc.net/ee/va/v1/sessionStart?configId={datastreamId}" \
--header 'Content-Type: application/json' \
--data '{
  "events": [
    {
      "xdm": {
        "eventType": "media.sessionStart",
        "mediaCollection": {
          "sessionDetails": {
            "name": "Media Analytics API Sample",
            "playerName": "sample-html5-api-player",
            "contentType": "VOD",
            "length": 60,
            "channel": "sample-channel"
          },
          "playhead": 0
        }
      }
    }
  ]
}'

{
  "requestId": "55d4b[...]a219f",
  "handle": [
    {
      "payload": [
        {
          "sessionId": "979a3[...]08505"
        }
      ],
      "type": "media-analytics:new-session",
      "eventIndex": 0
    },
    {
      "payload": [
        {
          "scope": "Target",
          "hint": "35",
          "ttlSeconds": 1800
        },
        {
          "scope": "AAM",
          "hint": "9",
          "ttlSeconds": 1800
        },
        {
          "scope": "EdgeNetwork",
          "hint": "or2",
          "ttlSeconds": 1800
        }
      ],
      "type": "locationHint:result"
    },
    {
      "payload": [
        {
          "key": "kndctr_53A[...]C99_AdobeOrg_identity",
          "value": "CiYyN[...]KmzI=",
          "maxAge": 34128000
        },
        {
          "key": "kndctr_53A[...]C99_AdobeOrg_cluster",
          "value": "or2",
          "maxAge": 1800
        }
      ],
      "type": "state:store"
    }
  ]
}

Request object

This endpoint requires the following payload properties within the xdm object:

The mediaCollection object requires several properties. See Media Collection Details data type in the Experience Data Model guide for more information.

The sessionDetails object requires several properties. See Session Details Collection data type in the Experience Data Model guide for more information.

Response object

If successfully processed, the API returns an object with the following properties:

sessionComplete

The sessionComplete endpoint indicates that the visitor reached the end of the main content. It does not immediately end a session; if you want to immediately end a session, call the sessionEnd endpoint. See Media Edge API implementation examples for more examples calling this endpoint.

Usage of this endpoint requires an active session. Make sure that you call the sessionStart endpoint first to obtain a valid session ID.

POST https://edge.adobedc.net/ee/va/v1/sessionComplete?configId={datastreamID}

data-slots=heading, code

data-repeat=1

data-languages=CURL

curl -X POST "https://edge.adobedc.net/ee/va/v1/sessionComplete?configId={datastreamID}" \
--header 'Content-Type: application/json' \
--data '{
  "events": [
    {
      "xdm": {
        "eventType": "media.sessionComplete",
        "mediaCollection": {
          "sessionID": "ffab5[...]45ec3",
          "playhead": 0
        },
        "timestamp": "YYYY-08-20T22:41:40+00:00"
      }
    }
  ]
}'

If successfully processed, the API returns 204 No Content.

This endpoint requires the following payload properties within the xdm object:

sessionEnd

The sessionEnd endpoint immediately ends a media playback session. Sessions end automatically when no events are received for 10 minutes, or when no playhead movement happens for 30 minutes. You can call this endpoint when you consider a session "done" and do not want any subsequent events tracked as part of the same session. See Media Edge API implementation examples for more examples calling this endpoint.

Usage of this endpoint requires an active session. Make sure that you call the sessionStart endpoint first to obtain a valid session ID. Calling this endpoint immediately ends the session for the given session ID, meaning that you cannot use that same session ID in subsequent API calls. If you want to track additional events after calling this endpoint, call the sessionStart endpoint to obtain a new session ID.

POST https://edge.adobedc.net/ee/va/v1/sessionEnd?configId={datastreamID}

data-slots=heading, code

data-repeat=1

data-languages=CURL

curl -X POST "https://edge.adobedc.net/ee/va/v1/sessionEnd?configId={datastreamID}" \
--header 'Content-Type: application/json' \
--data '{
  "events": [
    {
      "xdm": {
        "eventType": "media.sessionEnd",
        "mediaCollection": {
          "sessionID": "ffab5[...]45ec3",
          "playhead": 0
        },
        "timestamp": "YYYY-08-20T22:41:40+00:00"
      }
    }
  ]
}'

If successfully processed, the API returns 204 No Content.

This endpoint requires the following payload properties within the xdm object: