Media Stream Analytics by connecting the APIs of Adobe Experience Cloud

[acsarma]

The topic was originally authored and featured at Medium by Myself. Then I realized, it would be beneficial to reach out to the community and share the knowledge. Happy learning everyone

Introduction

Media customers have been dependent on Video Heartbeat Library SDK for measuring Media Playback. Since the release of Media Collection API some months ago, there are efforts by customers and experts in trying to integrate it in to their Media Playback.

This blog outlies the steps to implement a Media Stream AnalyticsData Collection Framework using only the APIs of Experience Cloud ID (ECID) service, Adobe Analytics (Data Insertion API) and Heartbeat Server. Let’s get started with the framework !!

Please note that this a humble effort and looking forward to experts in the Adobe Analytics World to come up with better versions and media application

Some Handy Documentation Links

Experience Cloud ID service API : https://marketing.adobe.com/resources/help/en_US/mcvid/mcvid-direct-integration.html

Adobe Analytics Data Insertion API: https://helpx.adobe.com/in/analytics/kb/data-insertion-api-post-method-adobe-analytics.html

Media Collection API: https://marketing.adobe.com/resources/help/en_US/sc/appmeasurement/hbvideo/mc-api-overview.html

Platform Agnsotic framework

This framework is expected to be platform agnostic. Depending on the platform the appropriate API request/response handling libraries needed to be loaded. Here is a sample list of platforms and API request/response handlers:

1. Web/JS — XMLHttpRequest
2. Android — Retrofit or okhttp3
3. Unity — UnityWebRequest
4. and the list goes on

Across all these platforms, it is necessary to maintain the same sequence of API calls:

1. Identifying the visitor using ECID API
2. Registering the visitor with Adobe Analytics
3. Streaming events in to the Heartbeat API server

1. Identifying the visitor using ECID API

The ECID API is a simple request to the Demdex server of the Adobe Experience Cloud Instance which would return an Identifier for the Visitor or the client.

When to trigger: at the load of a visitor session, independent of the availability of the media content, like load of a page or load of a screen in a mobile app or load of home screen in an OTT device.

Key components of the request would look like:

2. Registering the visitor with Adobe Analytics

Sending the above obtained visitor id (mid) and the Org Id to the Analytics tracking server, would suffice in registering the visitor in the Analytics servers. However for debugging purpose, it is advised to add few more custom variables in the Query String Parameter

When to trigger: At page or screen load complete.

Key components of the request would look like:

3. Streaming events in to the Heartbeat API server

As of the above two steps, we have established a visitor being identified in the Analytics server. Now we would be sending the heartbeat stream events to the heartbeat api server which would server-side forward to the analytics server. As mentioned previously, the Visitor ID will be the primary connecting key between the Analytics server and the Heartbeat server.

There are several stream events for the Heartbeat tracking server. This blog would cover the essential events that are required for tracking a complete media playback. Post practicing these handson, you would be equipped with enough knowledge on how to implement the rest. List of events covered:

1. sessionStart — Initiates a heartbeat/media stream session at heartbeat server
2. play — Sets the event for start of a media content
3. ping — Heartbeats
4. pauseStart — Sets the event for pausing the media content
5. sessionEnd — Sets the event for completion of a media content
6. sessionComplete — Compelte the heartbeat/media stream session

All these events are sent to the heartbeat tracking server, which appears similar to the analytics tracking server, except the “.sc.” would be replaced by “.d2.hb-api”, which points to the heartbeat api tracking server. Example:

1. Analytics server = abc123corp.sc.omtrd.net
2. Heartbeat API server = abc123corp.d2.hb-api.omtrdc.net

Knowledge of the Media player api would be essential for this step. For example a HTML5 player would emit the following events via its API: https://html.spec.whatwg.org/multipage/media.html#mediaevents. It is necessary for the platform developer to tap into these events using the event listener of the platforms.

Now let’s start sending the stream events to the heartbeat server

When to set sessionStart: Begin of a media playback engagement

Key Components for the sessionStart API request:

For the subsequent events, it is suggested to develop an OOPS function which would scale across all the media events and send the API request. The subsequent api request have a similar api request json format

When to set play event: Start of the media playback

Key Components for the play event:

When to set ping event: Once in every 10 second would be ideal for main media content streaming and when the media playback resumes from a pause start or buffering state.

Key components of the ping event:

When to set the pauseStart event: The media playback is paused

Key Components of the pause event:

When to set the sessionEnd event: The media playback ends

Key Components of the sessionEnd event:

When to set the sessionComplete event: The visitor moved to different page or screen of the experience

Key components of the sessionComplete event:

Validation of the Implementation

On successful implementation of the above apis in the mentioned order and manner, the Analytics server will merge the summarized table sent from the heartbeat server. This is a server side forward mechanism. In order to validate this implementation, Analysis workspace and the afore mentioned Adobe Analytics variables would be helpful.

A recap on the data being sent:

1. Visitor ID and behaviour data are sent to Adobe Analytics server
2. Visitor ID and Media Events are sent to Heartbeat Analytics server

We should be able to breakdown Visitor ID variable from Analytics server Hits with Media Name Variable from the Heartbeat server hits and appropriate metrics like Media Initiates, Plays , Pauses etc.. would be reported in the breakdown. This would mark the success of the implementation. Mission Accomplished !!!

Conclusion

As mentioned in the Introduction, this a humble effort and looking forward to experts in the Adobe Analytics World to come up with better versions and media application.

The essentials in implementing an API-only Media Analytics framework, would be the knowledge of the Adobe APIs, the platform libraries and the Media Player events.

There will be new media experiences like VR, Fitness Bands, TV stick etc... that are coming up and it might not be scalable to rely on the SDKs from the Analytics Platforms. It would be beneficial for Adobe Analytics strategist to leverage APIs for onboarding data from the new platforms.

Hope this blog helps you gaining confidence in experimenting with the API-only Media Analytics Implementation.