API reference

Media API reference

extensionVersion

The extensionVersion() API returns the version of the Media extension that is registered with the Mobile Core extension.

To get the version of the Media extension, use the following code sample:

Java

Copied to your clipboard
String mediaExtensionVersion = Media.extensionVersion();

createTracker

Creates a media tracker instance that tracks the playback session. The tracker created should be used to track the streaming content and it sends periodic pings to the media analytics backend.

The createTracker function returns the instance of MediaTracker for tracking a media session. The createTracker function with callback as a parameter has been deprecated.

If MobileCore.resetIdentities() is called in the implementation, the existing tracker will stop sending pings. You will need to create a new tracker to generate a new media session.

Java

Syntax

Copied to your clipboard
public static MediaTracker createTracker()
// Deprecated
public static void createTracker(AdobeCallback<MediaTracker> callback)

Example

Copied to your clipboard
MediaTracker mediaTracker = Media.createTracker(); // Use the instance for tracking media.
// Deprecated
Media.createTracker(new AdobeCallback<MediaTracker>() {
@Override
public void call(MediaTracker mediaTracker) {
// Use the instance for tracking media.
}
});

createTrackerWithConfig

Creates a media tracker instance based on the configuration to track the playback session.

KeyDescriptionValueRequired
config.channel
Channel name for media. Set this to overwrite the channel name configured from launch for media tracked with this tracker instance.
String
No
config.downloadedcontent
Creates a tracker instance to track downloaded media. Instead of sending periodic pings, the tracker only sends one ping for the entire content.
Boolean
No

Java

Optional configuration about the tracker can be passed to this function. The createTracker function returns the instance of MediaTracker with the configuration for tracking a media session. The createTracker function with callback as a parameter has been deprecated.

Syntax

Copied to your clipboard
public class MediaConstants {
public static final class Config {
public static final String CHANNEL = "config.channel";
public static final String DOWNLOADED_CONTENT = "config.downloadedcontent";
}
}
public static MediaTracker createTracker(Map<String, Object> config)
// Deprecated
public static void createTracker(Map<String, Object> config, final AdobeCallback<MediaTracker> callback)

Example

Copied to your clipboard
HashMap<String, Object> config = new HashMap<String, Object>();
config.put(MediaConstants.Config.CHANNEL, "custom-channel"); // Override channel configured in the Data Collection UI
config.put(MediaConstants.Config.DOWNLOADED_CONTENT, true); // Creates downloaded content tracker
MediaTracker mediaTracker = Media.createTracker(config); // Use the instance for tracking media.
// Deprecated
Media.createTracker(config, new AdobeCallback<MediaTracker>() {
@Override
public void call(MediaTracker mediaTracker) {
// Use the instance for tracking media.
}
});

createMediaObject

Creates an instance of the Media object.

Variable NameDescriptionRequired
name
Media name
Yes
mediaId
Media unique identifier
Yes
length
Media length
Yes
streamType
Yes
mediaType
Yes

Java

Returns a HashMap instance that contains information about the media.

Syntax

Copied to your clipboard
public static HashMap<String, Object> createMediaObject(String name,
String mediaId,
Double length,
String streamType,
MediaType mediaType);

Example

Copied to your clipboard
HashMap<String, Object> mediaInfo = Media.createMediaObject("video-name",
"video-id",
60D,
MediaConstants.StreamType.VOD,
Media.MediaType.Video);

createAdBreakObject

Creates an instance of the AdBreak object.

Variable NameDescriptionRequired
name
Ad break name such as pre-roll, mid-roll, and post-roll.
Yes
position
The number position of the ad break within the content, starting with 1.
Yes
startTime
Playhead value at the start of the ad break.
Yes

Java

Returns a HashMap instance that contains information about the ad break.

Syntax

Copied to your clipboard
public static HashMap<String, Object> createAdBreakObject(String name, Long position, Double startTime);

Example

Copied to your clipboard
HashMap<String, Object> adBreakObject = Media.createAdBreakObject("adbreak-name", 1L, 0D);

createAdObject

Creates an instance of the Ad object.

Variable NameDescriptionRequired
name
Friendly name of the ad.
Yes
adId
Unique identifier for the ad.
Yes
position
The number position of the ad within the ad break, starting with 1.
Yes
length
Ad length
Yes

Java

Returns a HashMap instance that contains information about the ad.

Syntax

Copied to your clipboard
public static HashMap<String, Object> createAdObject(String name, String adId, Long position, Double length);

Example

Copied to your clipboard
HashMap<String, Object> adInfo = Media.createAdObject("ad-name", "ad-id", 1L, 15D);

createChapterObject

Creates an instance of the Chapter object.

Variable NameDescriptionRequired
name
Chapter name
Yes
position
The number position of the chapter within the content, starting with 1.
Yes
length
Chapter length
Yes
startTime
Playhead value at the start of the chapter
Yes

Java

Returns a HashMap instance that contains information about the chapter.

Syntax

Copied to your clipboard
public static HashMap<String, Object> createChapterObject(String name,
Long position,
Double length,
Double startTime);

Example

Copied to your clipboard
HashMap<String, Object> chapterInfo = Media.createChapterObject("chapter-name", 1L, 60D, 0D);

createQoEObject

Creates an instance of the QoE object.

Variable NameDescriptionRequired
bitrate
Current bitrate
Yes
startupTime
Startup time
Yes
fps
FPS value
Yes
droppedFrames
Number of dropped frames
Yes

Java

Returns a HashMap instance that contains information about the quality of experience.

Syntax

Copied to your clipboard
public static HashMap<String, Object> createQoEObject(Long bitrate,
Double startupTime,
Double fps,
Long droppedFrames);

Example

Copied to your clipboard
HashMap<String, Object> qoeInfo = Media.createQoEObject(10000000L, 2D, 23D, 10D);

createStateObject

Creates an instance of the Player State object.

Variable NameDescriptionRequired
name
State name(Use Player State constants to track standard player states)
Yes

Java

Returns a HashMap instance that contains information about the State.

Syntax

Copied to your clipboard
public static HashMap<String, Object> createStateObject(String stateName);

Example

Copied to your clipboard
HashMap<String, Object> playerStateInfo = Media.createStateObject("fullscreen");

Media tracker API reference

trackSessionStart

Tracks the intention to start playback. This starts a tracking session on the media tracker instance. To learn how to resume a previously closed session, please read the media resume guide

Variable NameDescriptionRequired
mediaInfo
Media information created using the createMediaObject method.
Yes
contextData
Optional Media context data. For standard metadata keys, use standard video constants or standard audio constants.
No

Java

Syntax

Copied to your clipboard
public void trackSessionStart(Map<String, Object> mediaInfo, Map<String, String> contextData);

Example

Copied to your clipboard
HashMap<String, Object> mediaObject = Media.createMediaObject("media-name", "media-id", 60D, MediaConstants.StreamType.VOD, Media.MediaType.Video);
HashMap<String, String> mediaMetadata = new HashMap<String, String>();
// Standard metadata keys provided by adobe.
mediaMetadata.put(MediaConstants.VideoMetadataKeys.EPISODE, "Sample Episode");
mediaMetadata.put(MediaConstants.VideoMetadataKeys.SHOW, "Sample Show");
// Custom metadata keys
mediaMetadata.put("isUserLoggedIn", "false");
mediaMetadata.put("tvStation", "Sample TV Station");
_tracker.trackSessionStart(mediaInfo, mediaMetadata);

trackPlay

Tracks the media play, or resume, after a previous pause.

Java

Syntax

Copied to your clipboard
public void trackPlay();

Example

Copied to your clipboard
_tracker.trackPlay();

trackPause

Tracks the media pause.

Java

Syntax

Copied to your clipboard
public void trackPause();

Example

Copied to your clipboard
_tracker.trackPause();

trackComplete

Tracks media complete. Call this method only when the media has been completely viewed.

Java

Syntax

Copied to your clipboard
public void trackComplete();

Example

Copied to your clipboard
_tracker.trackComplete();

trackSessionEnd

Tracks the end of a viewing session. Call this method even if the user does not view the media to completion.

Java

Syntax

Copied to your clipboard
public void trackSessionEnd();

Example

Copied to your clipboard
_tracker.trackSessionEnd();

trackError

Tracks an error in media playback.

Variable NameDescriptionRequired
errorId
Error Information
Yes

Java

Syntax

Copied to your clipboard
public void trackError(String errorId);

Example

Copied to your clipboard
_tracker.trackError("errorId");

trackEvent

Tracks media events.

Variable NameDescription
event
info
For an AdBreakStart event, the adBreak information is created by using the createAdBreakObject method. For an AdStart event, the Ad information is created by using the createAdObject method. For ChapterStart event, the Chapter information is created by using the createChapterObject method. For StateStart and StateEnd event, the State information is created by using the createStateObject method.
data
Optional context data can be provided for AdStart and ChapterStart events. This is not required for other events.

Java

Syntax

Copied to your clipboard
public void trackEvent(Media.Event event,
Map<String, Object> info,
Map<String, String> data);

Examples

Tracking player states

Copied to your clipboard
// StateStart
HashMap<String, Object> stateObject = Media.createStateObject("fullscreen");
_tracker.trackEvent(Media.Event.StateStart, stateObject, null);
// StateEnd
HashMap<String, Object> stateObject = Media.createStateObject("fullscreen");
_tracker.trackEvent(Media.Event.StateEnd, stateObject, null);

Tracking ad breaks

Copied to your clipboard
// AdBreakStart
HashMap<String, Object> adBreakObject = Media.createAdBreakObject("adbreak-name", 1L, 0D);
_tracker.trackEvent(Media.Event.AdBreakStart, adBreakObject, null);
// AdBreakComplete
_tracker.trackEvent(Media.Event.AdBreakComplete, null, null);

Tracking ads

Copied to your clipboard
// AdStart
HashMap<String, Object> adObject = Media.createAdObject("ad-name", "ad-id", 1L, 15D);
HashMap<String, String> adMetadata = new HashMap<String, String>();
// Standard metadata keys provided by adobe.
adMetadata.put(MediaConstants.AdMetadataKeys.ADVERTISER, "Sample Advertiser");
adMetadata.put(MediaConstants.AdMetadataKeys.CAMPAIGN_ID, "Sample Campaign");
// Custom metadata keys
adMetadata.put("affiliate", "Sample affiliate");
_tracker.trackEvent(Media.Event.AdStart, adObject, adMetadata);
// AdComplete
_tracker.trackEvent(Media.Event.AdComplete, null, null);
// AdSkip
_tracker.trackEvent(Media.Event.AdSkip, null, null);

Tracking chapters

Copied to your clipboard
// ChapterStart
HashMap<String, Object> chapterObject = Media.createChapterObject("chapter-name", 1L, 60D, 0D);
HashMap<String, String> chapterMetadata = new HashMap<String, String>();
chapterMetadata.put("segmentType", "Sample segment type");
_tracker.trackEvent(Media.Event.ChapterStart, chapterDataInfo, chapterMetadata);
// ChapterComplete
_tracker.trackEvent(Media.Event.ChapterComplete, null, null);
// ChapterSkip
_tracker.trackEvent(Media.Event.ChapterSkip, null, null);

Tracking playback events

Copied to your clipboard
// BufferStart
_tracker.trackEvent(Media.Event.BufferStart, null, null);
// BufferComplete
_tracker.trackEvent(Media.Event.BufferComplete, null, null);
// SeekStart
_tracker.trackEvent(Media.Event.SeekStart, null, null);
// SeekComplete
_tracker.trackEvent(Media.Event.SeekComplete, null, null);

Tracking bitrate changes

Copied to your clipboard
// If the new bitrate value is available provide it to the tracker.
HashMap<String, Object> qoeObject = Media.createQoEObject(2000000L, 2D, 25D, 10D);
_tracker.updateQoEObject(qoeObject);
// Bitrate change
_tracker.trackEvent(Media.Event.BitrateChange, null, null);

updateCurrentPlayhead

Provides a media tracker with the current media playhead. For accurate tracking, call this method multiple times when the playhead changes.

Variable NameDescription
time
Current playhead in seconds. For video-on-demand (VOD), the value is specified in seconds from the beginning of the media item. For live streaming, the value is specified as the number of seconds since midnight UTC on that day.

Java

Syntax

Copied to your clipboard
public void updateCurrentPlayhead(double time);

Example

Copied to your clipboard
_tracker.updateCurrentPlayhead(1);

Live streaming example

Copied to your clipboard
//Calculation for number of seconds since midnight UTC of the day
double timeFromMidnightInSecond = (System.currentTimeMillis()/1000) % 86400;
_tracker.updateCurrentPlayhead(timeFromMidnightInSecond);

updateQoEObject

Provides the media tracker with the current QoE information. For accurate tracking, call this method multiple times when the media player provides the updated QoE information.

Variable nameDescription
qoeObject
Current QoE information that was created by using the createQoEObject method.

Java

Syntax

Copied to your clipboard
public void updateQoEObject(Map<String, Object> qoeObject);

Example

Copied to your clipboard
HashMap<String, Object> qoeObject = Media.createQoEObject(1000000L, 2D, 25D, 10D);
_tracker.updateQoEObject(qoeObject);

Media constants

Media type

Defines the type of a media that is currently tracked.

Copied to your clipboard
public class Media {
public enum MediaType {
/**
* Constant defining media type for Video streams
*/
Video,
/**
* Constant defining media type for Audio streams
*/
Audio
}
}

Stream type

Defines the stream type of the content that is currently tracked.

Copied to your clipboard
public class MediaConstants {
public static final class StreamType {
/**
* Constant defining stream type for VOD streams
*/
public static final String VOD = "vod";
/**
* Constant defining stream type for Live streams
*/
public static final String LIVE = "live";
/**
* Constant defining stream type for Linear streams
*/
public static final String LINEAR = "linear";
/**
* Constant defining stream type for Podcast streams
*/
public static final String PODCAST = "podcast";
/**
* Constant defining stream type for Audiobook streams
*/
public static final String AUDIOBOOK = "audiobook";
/**
* Constant defining stream type for AOD streams
*/
public static final String AOD = "aod";
}
}

Standard video constants

Defines the standard metadata keys for video streams.

Copied to your clipboard
public class MediaConstants {
public static final class VideoMetadataKeys {
public static final String SHOW = "a.media.show";
public static final String SEASON = "a.media.season";
public static final String EPISODE = "a.media.episode";
public static final String ASSET_ID = "a.media.asset";
public static final String GENRE = "a.media.genre";
public static final String FIRST_AIR_DATE = "a.media.airDate";
public static final String FIRST_DIGITAL_DATE = "a.media.digitalDate";
public static final String RATING = "a.media.rating";
public static final String ORIGINATOR = "a.media.originator";
public static final String NETWORK = "a.media.network";
public static final String SHOW_TYPE = "a.media.type";
public static final String AD_LOAD = "a.media.adLoad";
public static final String MVPD = "a.media.pass.mvpd";
public static final String AUTHORIZED = "a.media.pass.auth";
public static final String DAY_PART = "a.media.dayPart";
public static final String FEED = "a.media.feed";
public static final String STREAM_FORMAT = "a.media.format";
}
}

Standard audio constants

Defines the standard metadata keys for audio streams.

Copied to your clipboard
public class MediaConstants {
public static final class AudioMetadataKeys {
public static final String ARTIST = "a.media.artist";
public static final String ALBUM = "a.media.album";
public static final String LABEL = "a.media.label";
public static final String AUTHOR = "a.media.author";
public static final String STATION = "a.media.station";
public static final String PUBLISHER = "a.media.publisher";
}
}

Standard ad constants

Defines the standard metadata keys for ads.

Copied to your clipboard
public class MediaConstants {
public static final class AdMetadataKeys {
public static final String ADVERTISER = "a.media.ad.advertiser";
public static final String CAMPAIGN_ID = "a.media.ad.campaign";
public static final String CREATIVE_ID = "a.media.ad.creative";
public static final String PLACEMENT_ID = "a.media.ad.placement";
public static final String SITE_ID = "a.media.ad.site";
public static final String CREATIVE_URL = "a.media.ad.creativeURL";
}
}

Player state constants

Defines some common Player State constants.

Copied to your clipboard
public class MediaConstants {
public static final class PlayerState {
public static final String FULLSCREEN = "fullscreen";
public static final String PICTURE_IN_PICTURE = "pictureInPicture";
public static final String CLOSED_CAPTION = "closedCaptioning";
public static final String IN_FOCUS = "inFocus";
public static final String MUTE = "mute";
}
}

Media events

Defines the type of a tracking event.

Copied to your clipboard
public class Media {
/**
* These enumeration values define the type of a tracking event
*/
public enum Event {
/**
* Constant defining event type for AdBreak start
*/
AdBreakStart,
/**
* Constant defining event type for AdBreak complete
*/
AdBreakComplete,
/**
* Constant defining event type for Ad start
*/
AdStart,
/**
* Constant defining event type for Ad complete
*/
AdComplete,
/**
* Constant defining event type for Ad skip
*/
AdSkip,
/**
* Constant defining event type for Chapter start
*/
ChapterStart,
/**
* Constant defining event type for Chapter complete
*/
ChapterComplete,
/**
* Constant defining event type for Chapter skip
*/
ChapterSkip,
/**
* Constant defining event type for Seek start
*/
SeekStart,
/**
* Constant defining event type for Seek complete
*/
SeekComplete,
/**
* Constant defining event type for Buffer start
*/
BufferStart,
/**
* Constant defining event type for Buffer complete
*/
BufferComplete,
/**
* Constant defining event type for change in Bitrate
*/
BitrateChange,
/**
* Constant defining event type for State start
*/
StateStart,
/**
* Constant defining event type for State end
*/
StateEnd
}
}

Media resume

Constant to denote that the current tracking session is resuming a previously closed session. This information must be provided when starting a tracking session.

Java

Syntax

Copied to your clipboard
public class MediaConstants {
public static final class MediaObjectKey {
/**
* Constant defining explicit media resumed property. Set this to true on MediaObject if resuming a previously closed session.
*/
public static final String RESUMED;
}
}

Example

Copied to your clipboard
HashMap<String, Object> mediaObject = Media.createMediaObject("media-name", "media-id", 60D, MediaConstants.StreamType.VOD, Media.MediaType.Video);
// Attach media resumed information.
mediaObject.put(MediaConstants.MediaObjectKey.RESUMED, true);
_tracker.trackSessionStart(mediaObject, null);
Was this helpful?