Edit in GitHubLog an issue

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

Syntax

Copied to your clipboard
public static String extensionVersion() {

Example

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

Kotlin

Example

Copied to your clipboard
val mediaExtensionVersion = Media.extensionVersion()

registerExtension

Registers the Media extension with the Mobile Core SDK.

Java

Syntax

Copied to your clipboard
public static void registerExtension()

Example

Copied to your clipboard
Media.registerExtension();

Kotlin

Example

Copied to your clipboard
Media.registerExtension()

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()

Example

Copied to your clipboard
MediaTracker mediaTracker = Media.createTracker();  // Use the instance for tracking media.

Kotlin

Example

Copied to your clipboard
val tracker = Media.createTracker()

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

Syntax

Copied to your clipboard
public static MediaTracker createTracker(Map<String, Object> config)

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.

Kotlin

Example

Copied to your clipboard
val config = mapOf(
                MediaConstants.Config.CHANNEL to "custom-channel",
                MediaConstants.Config.DOWNLOADED_CONTENT to true
            )
val mediaTracker = Media.createTracker(config) // 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
Stream type
Yes
mediaType
Media type
Yes

Java

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);

Kotlin

Example

Copied to your clipboard
var 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

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);

Kotlin

Example

Copied to your clipboard
val 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

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);

Kotlin

Example

Copied to your clipboard
val 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

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);

Kotlin

Example

Copied to your clipboard
val 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

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);

Kotlin

Example

Copied to your clipboard
val 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

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");

Kotlin

Example

Copied to your clipboard
val 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
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);

Kotlin

Example

Copied to your clipboard
val mediaObject = Media.createMediaObject(
                        "media-name",
                        "media-id",
                        60.0,
                        MediaConstants.StreamType.VOD,
                        Media.MediaType.Video
                    )


val mediaMetadata = HashMap<String, String>()
// Standard metadata keys provided by adobe.
mediaMetadata[MediaConstants.VideoMetadataKeys.EPISODE] = "Sample Episode" 
mediaMetadata[MediaConstants.VideoMetadataKeys.SHOW] = "Sample Show"
// Custom metadata keys
mediaMetadata["isUserLoggedIn"] = "false"
mediaMetadata["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();

Kotlin

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();

Kotlin

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();

Kotlin

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();

Kotlin

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");

Kotlin

Example

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

trackEvent

Tracks media events.

Variable NameDescription
event
Media 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);

Kotlin

Examples

Tracking player states

Copied to your clipboard
// StateStart
    val stateObject = Media.createStateObject("fullscreen")
    tracker.trackEvent(Media.Event.StateStart, stateObject, null)


// StateEnd
    val stateObject = Media.createStateObject("fullscreen")
    tracker.trackEvent(Media.Event.StateEnd, stateObject, null)`

Tracking ad breaks

Copied to your clipboard
// AdBreakStart
    val adBreakObject = Media.createAdBreakObject("adbreak-name", 1L, 0.0)
    tracker.trackEvent(Media.Event.AdBreakStart, adBreakObject, null)


// AdBreakComplete
    tracker.trackEvent(Media.Event.AdBreakComplete, null, null)

Tracking ads

Copied to your clipboard
//AdStart
    val adObject = Media.createAdObject("ad-name", "ad-id", 1L, 15.0)


    val adMetadata = HashMap<String, String>()
    // Standard metadata keys provided by adobe.
    adMetadata[MediaConstants.AdMetadataKeys.ADVERTISER] = "Sample Advertiser"
    adMetadata[MediaConstants.AdMetadataKeys.CAMPAIGN_ID] = "Sample Campaign"
    // Custom metadata keys
    adMetadata["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
  val chapterObject = Media.createChapterObject("chapter-name", 1L, 60.0, 0.0)


  val chapterMetadata = HashMap<String, String>()
  chapterMetadata["segmentType"] = "Sample segment type"


  tracker.trackEvent(Media.Event.ChapterStart, chapterObject, 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.
  val 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);

Kotlin

Example

Copied to your clipboard
tracker.updateCurrentPlayhead(1);

Live streaming example

Copied to your clipboard
val timeFromMidnightInSecond = (System.currentTimeMillis() / 1000 % 86400).toDouble()
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);

Kotlin

Example

Copied to your clipboard
val 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);
Praveen
Last updated 4/5/2024
Was this helpful?

Community

Support

Adobe Developer

  • Privacy
  • Terms of Use
  • Do not sell or share my personal information
  • AdChoices
Copyright © 2024 Adobe. All rights reserved.