Timeline 1 - View to end of content
- Topics:
- Media Analytics
CREATED FOR:
- User
- Admin
- Developer
VOD, pre-roll ads, pausing, buffering, viewing content to the end
The following diagrams illustrate the playhead timeline and the corresonding timeline of a user’s actions. The details for each action and its accompanying requests are presented below.
Action details
Action 1 - Start session
/api/v1/sessions
This call signals the user’s intention to play a video.
It returns a Session ID ( {sid}
) to the client that is used to identify all subsequent tracking calls within the session. The player state is not yet “playing”, but is instead “starting”.
Mandatory session parameters must be included in the params
map in the request body. For information about sessions, see the Media Collection API documentation.
On the backend, this call generates an Adobe Analytics initiate call.
{
"playerTime": {
"playhead": 0,
"ts": "<timestamp>"
},
"eventType":"sessionStart, params" {
"media.playerName": "sample-html5-api-player",
"analytics.trackingServer": "[ _YOUR_TS_ ]",
"analytics.reportSuite": "[ _YOUR_RSID_ ]",
"analytics.visitorId": "[ _YOUR_VISITOR_ID_ ]",
"media.contentType": "VOD",
"media.length": 60.3333333333333,
"media.id": "VA API Sample Player",
"visitor.marketingCloudOrgId": "[YOUR_MCID]",
"media.name": "ClickMe",
"media.channel": "sample-channel",
"media.sdkVersion": "va-api-0.0.0",
"analytics.enableSSL": false
}
}
Action 2 - Ping timer start
/api/v1/sessions/{sid}/events
Start your app’s ping timer. First ping event should then fire 1 second in if there are pre-roll ads, 10 seconds in otherwise.
Action 3 - Ad break start
/api/v1/sessions/{sid}/events
Ads can only be tracked within an ad break.
{
"playerTime": {
"playhead": 0,
"ts": "<timestamp>"
},
"eventType":"adBreakStart",
"params": {
"media.ad.podFriendlyName": "ad_pod1",
"media.ad.podIndex": 0,
"media.ad.podSecond": 0
}
}
Action 4 - Ad start
/api/v1/sessions/{sid}/events
Start tracking the first pre-roll ad, which is 15 seconds long. Including custom metadata with this adStart
.
{
"playerTime": {
"playhead": 0,
"ts": "<timestamp>"
},
"eventType":"adStart",
"params": {
"media.ad.podFriendlyName": "ad_pod1",
"media.ad.name": "Ad 1",
"media.ad.id": "001",
"media.ad.length": 15,
"media.ad.podPosition": 1,
"media.ad.playerName": "Sample Player",
"media.ad.advertiser": "Ad Guys",
"media.ad.campaignId": "1",
"media.ad.creativeId": "42",
"media.ad.siteId": "XYZ",
"media.ad.creativeURL": "https://example.com",
"media.ad.placementId": "sample_placement"
},
"customMetadata": {
"myCustomData1": "CustomData1",
"myCustomData2": "CustomData2"
}
}
NOTE: Between AdBreakStart and AdStart events there shouldn’t be any additional playback events.
Action 5 - Ad pings
Action 5.1 - Ad ping 1
/api/v1/sessions/{sid}/events
Ping the backend every 1 second while inside an ad.
{
"playerTime": {
"playhead": 0,
"ts": "<timestamp>"
},
"eventType": "ping"
}
Action 5.2 - Ad ping 2
/api/v1/sessions/{sid}/events
Ping the backend every 1 second while inside an ad.
{
"playerTime": {
"playhead": 0,
"ts": "<timestamp>"
},
"eventType": "ping"
}
Action 5.3 - Ad ping 3
/api/v1/sessions/{sid}/events
Ping the backend every 1 second while inside an ad.
in the interest of brevity…
{
"playerTime": {
"playhead": 0,
"ts": "<timestamp>"
},
"eventType": "ping"
}
Action 6 - Ad complete
/api/v1/sessions/{sid}/events
Track the end of the first pre-roll ad.
{
"playerTime": {
"playhead": 0,
"ts": "<timestamp>"
},
"eventType": "adComplete"
}
Action 7 - Ad start
/api/v1/sessions/{sid}/events
Track the start of the second pre-roll ad, which is 7 seconds long.
{
"playerTime": {
"playhead": 0,
"ts": "<timestamp>"
},
"eventType": "adStart",
"params": {
"media.ad.podFriendlyName": "ad_pod1",
"media.ad.name": "Ad 2",
"media.ad.id": "002",
"media.ad.length": 7,
"media.ad.podPosition": 1,
"media.ad.playerName": "Sample Player",
"media.ad.advertiser": "Ad Guys",
"media.ad.campaignId": "2",
"media.ad.creativeId": "44",
"media.ad.siteId": "XYZ",
"media.ad.creativeURL": "https://example.com",
"media.ad.placementId": "sample_placement2"
},
}
Action 8 - Ad pings
/api/v1/sessions/{sid}/events
Ping the backend every 1 second.
{
"playerTime": {
"playhead": 0,
"ts": "<timestamp>"
},
"eventType": "ping"
}
Action 9 - Ad complete
/api/v1/sessions/{sid}/events
Track the end of the second pre-roll ad.
{
"playerTime": {
"playhead": 0,
"ts": "<timestamp>"
},
"eventType": "adComplete"
}
Action 10 - Ad break complete
/api/v1/sessions/{sid}/events
The ad break is over.
{
"playerTime": {
"playhead": 0,
"ts": "<timestamp>"
},
"eventType": "adBreakComplete"
}
Action 11 - Play content
/api/v1/sessions/{sid}/events
After the adBreakComplete
event, put the player in the “playing” state using the play
event.
{
"playerTime": {
"playhead": 0,
"ts": "<timestamp>"
},
"eventType": "play"
}
Action 12 - Ping
/api/v1/sessions/{sid}/events
Ping the backend every 10 seconds.
{
"playerTime": {
"playhead": 8,
"ts": "<timestamp>"
},
"eventType": "ping"
}
Action 13 - Buffer start
/api/v1/sessions/{sid}/events
Track the player’s move to the “buffering” state.
{
"playerTime": {
"playhead": 11,
"ts": "<timestamp>"
}, "eventType": "bufferStart"
}
Action 14 - Buffer end
/api/v1/sessions/{sid}/events
Buffering ends after 3 seconds, so put the player back to the “playing” state. You must send another track play event coming out of buffering. The play
call after a bufferStart
infers a “bufferEnd” call to the back end, so there is no need for a bufferEnd
event.
{
"playerTime": {
"playhead": 11,
"ts": "<timestamp>"
},
"eventType": "play"
}
Action 15 - Ping
/api/v1/sessions/{sid}/events
Ping the backend every 10 seconds.
{
"playerTime": {
"playhead": 15,
"ts": "<timestamp>"
}, "eventType": "ping"
}
Action 16 - Ad break start
/api/v1/sessions/{sid}/events
Mid-roll ad of 8 seconds duration: send adBreakStart
.
{
"playerTime": {
"playhead": 21,
"ts": "<timestamp>"
},
"eventType": "adBreakStart",
"params": {
"media.ad.podFriendlyName": "ad_pod2",
"media.ad.podIndex": 1,
"media.ad.podSecond": 21
}
}
Action 17 - Ad start
/api/v1/sessions/{sid}/events
Track the mid-roll ad.
{
"playerTime": {
"playhead": 21,
"ts": "<timestamp>"
},
"eventType": "adStart",
"params": {
"media.ad.podFriendlyName": "ad_pod2",
"media.ad.name": "Ad 3",
"media.ad.id": "003",
"media.ad.length": 8,
"media.ad.podPosition": 2,
"media.ad.playerName": "Sample Player",
"media.ad.advertiser": "Ad Guys",
"media.ad.campaignId": "7",
"media.ad.creativeId": "40",
"media.ad.siteId": "XYZ",
"media.ad.creativeURL": "https://example.com",
"media.ad.placementId": "sample_placement2"
},
}
Action 18 - Ad ping
/api/v1/sessions/{sid}/events
Ping the backend every 10 seconds.
{
"playerTime": {
"playhead": 21,
"ts": "<timestamp>"
}, "eventType": "ping"
}
Action 19 - Ad complete
/api/v1/sessions/{sid}/events
The mid-roll ad is complete.
{
"playerTime": {
"playhead": 21,
"ts": "<timestamp>"
},
"eventType": "adComplete"
}
Action 20 - Ad break complete
/api/v1/sessions/{sid}/events
The ad break is complete.
{
"playerTime": {
"playhead": 21,
"ts": "<timestamp>"
},
"eventType": "adBreakComplete"
}
Action 21 - Ping
/api/v1/sessions/{sid}/events
Ping the backend every 10 seconds.
{
"playerTime": {
"playhead": 27,
"ts": "<timestamp>"
},
"eventType": "ping"
}
Action 22 - Pause
/api/v1/sessions/{sid}/events
The user’s action moves the play state to “paused”.
{
"playerTime": {
"playhead": 31,
"ts": "<timestamp>"
},
"eventType": "pauseStart"
}
Action 23 - Ping
/api/v1/sessions/{sid}/events
Ping the backend every 10 seconds. Player is still in the “buffering” state; the user is stuck at 20 seconds of content. Fuming…
{
"playerTime": {
"playhead": 31,
"ts": "<timestamp>"
}, "eventType": "ping"
}
Action 24 - Play
/api/v1/sessions/{sid}/events
Move the play state to “playing”. The play
call after a pauseStart
infers a “resume” call to the back end, so there is no need for a resume
event.
{
"playerTime": {
"playhead": 31,
"ts": "<timestamp>"
}, "eventType": "play"
}
Action 25 - Ping
/api/v1/sessions/{sid}/events
Ping the backend every 10 seconds.
{
"playerTime": {
"playhead": 37,
"ts": "<timestamp>"
}, "eventType": "ping"
}
Action 26 - Session complete
/api/v1/sessions/{sid}/events
Send sessionComplete
to the backend to indicate that the user finished watching the entire content.
{
"playerTime": {
"playhead": 45,
"ts": "<timestamp>"
}, "eventType": "sessionComplete"
}
seekStart
or seekComplete
events. This is because certain players generate a very large number of such events when the end-user is scrubbing, and several hundred users could easily bottleneck the network bandwidth of a backend service. Adobe works around explicit support for seek events by computing heartbeat duration based on device timestamp, rather than playhead position.