Adobe Experience Platform Launch has been rebranded as a suite of data collection technologies in Adobe Experience Platform. Several terminology changes have rolled out across the product documentation as a result. Please refer to the following document for a consolidated reference of the terminology changes.
Use this documentation for information on installing, configuring, and implementing the Adobe Media Analytics for Audio and Video extension (Media Analytics extension). Included are the options available when using this extension to build a rule, along with examples and links to samples.
The Media Analytics (MA) extension adds the core JavaScript Media SDK (Media 2.x SDK). This extension provides the functionality for adding the MediaHeartbeat
tracker instance to a tag site or project. The MA extension requires two additional extensions:
Audio tracking requires Analytics Extension v1.6 or higher.
After you have included all three of the extensions mentioned above in your tag project, you can proceed in one of two ways:
MediaHeartbeat
APIs from your web appMediaHeartbeat
tracker instance. This instance is exposed through the MA extension.Install - To install the MA extension, open your extension property, select Extensions > Catalog, hover over the Adobe Media Analytics for Audio and Video extension, and select Install.
Configure - To configure the MA extension, open the Extensions tab, hover over the extension, and then select Configure:
Option | Description |
---|---|
Tracking Server | Defines the server for tracking media heartbeats (this is not the same server as your analytics tracking server) |
Application Version | The version of the media player app/SDK |
Player Name | Name of the media player in use (e.g., “AVPlayer”, “HTML5 Player”, “My Custom VideoPlayer”) |
Channel | Channel name property |
Online Video Provider | Name of the online video platform through which content gets distributed |
Debug Logging | Enable or Disable logging |
Enable SSL | Enable or Disable sending pings over HTTPS |
Export APIs to Window Object | Enable or Disable exporting Media Analytics APIs to global scope |
Variable Name | A variable you use to export Media Analytics APIs under the window object |
Reminder: The MA extension requires the Analytics and Experience Cloud ID extensions. You must also add these extensions to your extension property and configure them.
The MA extension exports the MediaHeartbeat APIs in the global window object by enabling the “Export APIs to Window Object” setting in the Configuration page. It exports the APIs under the configured variable name. For example, if the variable name is configured to be ADB
then MediaHeartbeat can be accessed by window.ADB.MediaHeartbeat
.
The MA extension exports the APIs only when window["CONFIGURED_VARIABLE_NAME"]
is undefined and does not override existing variables.
Create MediaHeartbeat Instance: window["CONFIGURED_VARIABLE_NAME"].MediaHeartbeat.getInstance
Params: A valid delegate object exposing these functions.
Method | Description |
---|---|
getQoSObject() |
Returns theMediaObject instance that contains current QoS information. This method will be called multiple times during a playback session. Player implementation must always return the most recently available QoS data. |
getCurrentPlaybackTime() |
Returns the current position of the playhead. For VOD tracking, the value is specified in seconds from the beginning of the media item. For LIVE/LIVE tracking, the value is specified in seconds from the beginning of the program. |
Return Value: A promise which either resolves with a MediaHeartbeat
instance or rejects with an error message.
Access MediaHeartbeat Constants: window["CONFIGURED_VARIABLE_NAME"].MediaHeartbeat
This exposes all of the constants and static methods from the MediaHeartbeat
class.
You can obtain the sample player here: MA Sample Player. The sample player acts as a reference to showcase how to use the MA extension to support Media Analytics directly from a webapp.
Create the MediaHeartbeat tracker instance as follows:
var MediaHeartbeat = window["CONFIGURED_VARIABLE_NAME"].MediaHeartbeat;
var delegate = {
getCurrentPlaybackTime: this._getCurrentPlaybackTime.bind(this),
getQoSObject: this._getQoSObject.bind(this),
};
var config = {
playerName: "Custom Player",
ovp: "Custom OVP",
channel: "Custom Channel"
};
var self = this;
MediaHeartbeat.getInstance(delegate, config).then(function(instance) {
self._mediaHeartbeat = instance;
// Do Tracking using the MediaHeartbeat instance.
}).catch(function(err){
// Getting MediaHeartbeat instance failed.
});
The MA extension exposes the get-instance
and media-heartbeat
shared modules to other extensions. (For additional information on Shared Modules, see Shared Modules documentation.)
Shared Modules can only be accessed from other extensions. That is, a webpage/JS app cannot access the shared modules, or use turbine
(see code sample below) outside of an extension.
Create MediaHeartbeat Instance: get-instance
Shared Module
Params:
A valid delegate object exposing these functions:
Method | Description |
---|---|
getQoSObject() |
Returns the MediaObject instance that contains the current QoS information. This method will be called multiple times during a playback session. The player implementation must always return the most recently available QoS data. |
getCurrentPlaybackTime() |
Returns the current position of the playhead. For VOD tracking, the value is specified in seconds from the beginning of the media item. For LIVE/LIVE tracking, the value is specified in seconds from the beginning of the program. |
An optional config object exposing these properties:
Property | Description | Required |
---|---|---|
Online Video Provider | Name of the online video platform through which content is distributed. | No. If present, overrides the value defined during extension configuration. |
Player Name | Name of the media player in use (e.g., “AVPlayer”, “HTML5 Player”, “My Custom VideoPlayer”) | No. If present, overrides the value defined during extension configuration. |
Channel | Channel name property | No. If present, overrides the value defined during extension configuration. |
Return Value: A promise which either resolves with a MediaHeartbeat
instance or rejects with an error message.
Access MediaHeartbeat Constants: media-heartbeat
Shared Module
This module exposes all of the constants and static methods from this class: https://adobe-marketing-cloud.github.io/media-sdks/reference/javascript/MediaHeartbeat.html.
Create the MediaHeartbeat tracker instance as follows:
var getMediaHeartbeatInstance =
turbine.getSharedModule('adobe-video-analytics', 'get-instance');
var MediaHeartbeat =
turbine.getSharedModule('adobe-video-analytics', 'media-heartbeat');
...
var delegate = {
getCurrentPlaybackTime: this._getCurrentPlaybackTime.bind(this),
getQoSObject: this._getQoSObject.bind(this),
}
var config = {
playerName: "Custom Player",
ovp: "Custom OVP",
channel: "Custom Channel"
}
...
var self = this;
getMediaHeartbeatInstance(delegate, config).then(function(instance) {
self._mediaHeartbeat = instance;
...
// Do Tracking using the MediaHeartbeat instance.
}).catch(function(err){
// Getting MediaHeartbeat instance failed.
});
...
Using the Media Heartbeat instance, follow the Media SDK JS documentation and JS API documentation to implement media tracking.
Testing: For this release, to test your extension you must upload it to Platform, where you have access to all dependent extensions.