Timeline 1 - View to end of content

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

Implementation Detail

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.

On the backend, this call generates an Adobe Analytics initiate call.

Sample request body

{
    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

Implementation Details

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

Implementation Detail

Ads can only be tracked within an ad break.

Sample request body

{
    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

Implementation Detail

Start tracking the first pre-roll ad, which is 15 seconds long. Including custom metadata with this adStart .

Sample request body

{
    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://xyz_creative.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

Implementation Detail

Ping the backend every 1 second while inside an ad.

Sample request body

{
    playerTime: {
        playhead: 0,
        ts: <timestamp>
    },
    eventType:ping
}

Action 5.2 - Ad ping 2

Implementation Detail

Ping the backend every 1 second while inside an ad.

Sample request body

{
    playerTime: {
        playhead: 0,
        ts: <timestamp>
    },
    eventType:ping
}

Action 5.3 - Ad ping 3

Implementation Detail

Ping the backend every 1 second while inside an ad.

Sample request body

{
    playerTime: {
        playhead: 0,
        ts: <timestamp>
    },
    eventType:ping
}

Action 6 - Ad complete

Implementation Detail

Track the end of the first pre-roll ad.

Sample request body

{
    playerTime: {
        playhead: 0,
        ts: <timestamp>
    },
    eventType:adComplete
}

Action 7 - Ad start

Implementation Detail

Track the start of the second pre-roll ad, which is 7 seconds long.

Sample request body

{
    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://xyz_creative.com",
        "media.ad.placementId": "sample_placement2"
    },
}

Action 8 - Ad pings

Implementation Detail

Ping the backend every 1 second.

Sample request body

{
    playerTime: {
        playhead: 0,
        ts: <timestamp>
    },
    eventType:ping
}

Action 9 - Ad complete

Implementation Detail

Track the end of the second pre-roll ad.

Sample request body

{
    playerTime: {
        playhead: 0,
        ts: <timestamp>
    },
    eventType:adComplete
}

Action 10 - Ad break complete

Implementation Detail

The ad break is over. Throughout the ad break, the play state has remained “playing”.

Sample request body

{
    playerTime: {
        playhead: 0,
        ts: <timestamp>
    },
    eventType:adBreakComplete
}

Action 11 - Play content

Implementation Detail

After the adBreakComplete event, put the player in the “playing” state using the play event.

Sample request body

{
    playerTime: {
        playhead: 0,
        ts: <timestamp>
    },
    eventType:play
}

Action 12 - Ping

Implementation Detail

Ping the backend every 10 seconds.

Sample request body

{
    playerTime: {
        playhead: 8,
        ts: <timestamp>
    },
    eventType:ping
}

Action 13 - Buffer start

Implementation Detail

Track the player’s move to the “buffering” state.

Sample request body

{
    playerTime: {
        playhead: 11,
        ts: <timestamp>
    }, eventType:bufferStart
}

Action 14 - Buffer end

Implementation Detail

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.

Sample request body

{
    playerTime: {
        playhead: 11,
        ts: <timestamp>
    },
    eventType:play
}

Action 15 - Ping

Implementation Detail

Ping the backend every 10 seconds.

Sample request body

{
    playerTime: {
        playhead: 15,
        ts: <timestamp>
    }, eventType:ping
}

Action 16 - Ad break start

Implementation Detail

Mid-roll ad of 8 seconds duration: send adBreakStart .

Sample request body

{
    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

Implementation Detail

Track the mid-roll ad.

Sample request body

{
    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://xyz_creative.com",
        "media.ad.placementId": "sample_placement2"
    },
}

Action 18 - Ad ping

Implementation Detail

Ping the backend every 10 seconds.

Sample request body

{
    playerTime: {
        playhead: 21,
        ts: <timestamp>
    }, eventType:ping
}

Action 19 - Ad complete

Implementation Detail

The mid-roll ad is complete.

Sample request body

{
    playerTime: {
        playhead: 21,
        ts: <timestamp>
    },
    eventType:adComplete
}

Action 20 - Ad break complete

Implementation Detail

The ad break is complete.

Sample request body

{
    playerTime: {
        playhead: 21,
        ts: <timestamp>
    },
    eventType:adBreakComplete
}

Action 21 - Ping

Implementation Detail

Ping the backend every 10 seconds.

Sample request body

{
    playerTime: {
        playhead: 27,
        ts: <timestamp>
    },
    eventType:ping
}

Action 22 - Pause

Implementation Detail

The user’s action moves the play state to “paused”.

Sample request body

{
    playerTime: {
        playhead: 31,
        ts: <timestamp>
    },
    eventType:pauseStart
}

Action 23 - Ping

Implementation Detail

Ping the backend every 10 seconds. Player is still in the “buffering” state; the user is stuck at 20 seconds of content. Fuming…

Sample request body

{
    playerTime: {
        playhead: 31,
        ts: <timestamp>
    }, eventType:ping
}

Action 24 - Play

Implementation Detail

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.

Sample request body

{
    playerTime: {
        playhead: 31,
        ts: <timestamp>
    }, eventType:play
}

Action 25 - Ping

Implementation Detail

Ping the backend every 10 seconds.

Sample request body

{
    playerTime: {
        playhead: 37,
        ts: <timestamp>
    }, eventType:ping
}

Action 26 - Session complete

Implementation Detail

Send sessionComplete to the backend to indicate that the user finished watching the entire content.

Sample request body

{
    playerTime: {
        playhead: 45,
        ts: <timestamp>
    }, eventType:sessionComplete
}