Media Edge API implementation examples

This page provides two examples on how you can structure your API calls to successfully collect a media tracking session.

An API call is made for each action that you want to track. Once the media session ends, all API calls are recompiled into events that Adobe Experience Platform can ingest into a dataset. Expect to send many Media Edge API calls that end up as a smaller number of rows within a dataset. On average, approximately 6 API calls are used per event recorded in a dataset.

Some helpful tips to keep in mind regarding these examples:

• The playhead position (the current position indicated in the horizontal timeline of the video) does not advance during buffering, pausing, or an ad break, even though real time has elapsed. Both playhead position and the passing of real time are measured in seconds.
• The events sent are ordered based on the timestamp at which they were sent. If they are sent at the same second, as illustrated in the examples below, they are still sent with different ascending timestamps.
• For media tracking, you must fire ping events every 10 seconds, tracked in real-time, beginning after 10 seconds have elapsed from the session start. This must happen regardless of other API events that you have sent.
• The timestamp values in the payload examples below are generic for the year, month, and day, but show specific hours, minutes, seconds, and milliseconds. This is to show how the values correspond to the progressing events. The session starts with the following timestamp value: YYYY-MM-DDT02:00:00.000Z.

Prerequisites

Before following these examples, make sure that you have an API environment set up based on the steps outlined on the Getting started overview page, specifically:

• Create a schema (make sure to add the MediaAnalytics Interaction Details field group)
• Create a dataset
• Create a datastream

Example 1: Buffer state and a pause

This example contains the following elements:

• A buffering state.
• The user pressing pause.
• The user closing the app without finishing the content to the end.

The following actions and playhead diagrams show the differences in time during a buffer and a pause:

• Playhead diagram:

  

• Action diagram:

  

The following table shows a timeline of actions to be tracked for this example. Each row summarizes the action and the request endpoint. Each action is described in more detail with payloads below the table. The Client Request column shows the final path parameter and other parameters required to include in the call.

Each timeline action shown in the previous table is described in detail below. Each description includes the payload that is sent as part of a Media Edge API request.

This section provides an example tracking a media session with the Media Edge API service. The example session shown for this use case contains the following elements:

• Two chapters: Chapter 1 and Chapter 2.
• An ad break inserted at the middle of the content that contains two ads: Ad 1 and Ad 2.

The following action and playhead diagrams show the differences in time during an ad break.

• Action diagram:

  

• Playhead diagram:

  

The following diagram shows a timeline of actions for this example session. Each number (1-18) represents an action and its request endpoint. These numbers also correspond to event descriptions in both the Timeline summary table and the Detailed descriptions section below.

The Client request column in the table below shows the final path parameter and the other parameters required to include in the call.

Each timeline action shown in the previous table is described in detail below. Each description includes the payload that is sent as part of a Media Edge API request.