View on GitHub

media-sdks

Adobe Media SDK

MediaSDK API reference

ADB.Media

Static methods

configure

Note: This method is for standalone Media SDK JavaScript v3.x. For Media SDK Javascript v3.x with Tags extension, setup the configuration via Data Collection UI (Tags UI).

Configures MediaSDK for tracking. This method should be called once before creating any tracker instances in a page.

Syntax

ADB.Media.configure(mediaConfig, appMeasurement);
Variable Name Type Description
mediaConfig ADB.MediaConfig Valid media configuration
appMeasurement object AppMeasurement instance

Example

var mediaConfig = new ADB.MediaConfig();
mediaConfig.trackingServer = "company.hb-api.omtrdc.net";
mediaConfig.playerName = "player_name";
mediaConfig.channel = "sample_channel";
mediaConfig.appVersion = "app_version";
mediaConfig.debugLogging = true;
mediaConfig.ssl = true;

ADB.Media.configure(mediaConfig, appMeasurement);

getInstance

Creates an instance of media to track the playback session. Returns null is called before configuring media.

Syntax

ADB.Media.getInstance()

Example

var tracker = ADB.Media.getInstance();
 // create an instance with custom channel example
 // this overrides the channel which was set during the configuration
 var tracker = ADB.Media.getInstance({"media.channel":"custom_channel_name"})

createMediaObject

Creates an object containing media information. Returns empty object if invalid parameters are passed.

Syntax

ADB.Media.createMediaObject(name, id, length, streamType, mediaType)
Variable Name Type Description
name string Non empty string denoting media name
id string Non empty string denoting unique media identifier
length number Positive number denoting length of media in seconds. Use 0 if length is unknown.
streamType string Stream type or non empty string to denote media stream type.
mediaType Media type Type of media (Audio or Video)

Example

var mediaObject = ADB.Media.createMediaObject("video-name",
                                              "video-id",
                                              60.0,
                                              ADB.Media.StreamType.VOD,
                                              ADB.Media.MediaType.Video);

createAdBreakObject

Creates an object containing adbreak information. Returns empty object if invalid parameters are passed.

Syntax

ADB.Media.createAdBreakObject(name, position, startTime);
Variable Name Type Description
name string Non empty string denoting adbreak name (pre-roll, mid-roll, and post-roll)
position number The number position of the ad break within the content, starting with 1
startTime number Playhead value at the start of the ad break.

Example

var adbreakObject = ADB.Media.createAdBreakObject("midroll", 2, 30.0);

createAdObject

Creates an object containing ad information. Returns empty object if invalid parameters are passed.

Syntax

ADB.Media.createAdObject(name, id, position, length);
Variable Name Type Description
name string Non empty string denoting ad name
id string Non empty string denoting ad id
position number The number position of the ad within the adbreak, starting with 1
length number Positive number denoting length of the ad

Example

var adObject = ADB.Media.createAdObject("ad-name", "ad-id", 1, 15.0)

createChapterObject

Creates an object containing chapter information. Returns empty object if invalid parameters are passed.

Syntax

ADB.Media.createChapterObject(name, position, length, startTime)
Variable Name Type Description
name string Non empty string denoting chapter name
position number The position of the chapter within the content, starting with 1
length number Positive number denoting length of the chapter
startTime number Playhead value at start of chapter

Example

var chapterObject = ADB.Media.createChapterObject("name", 1, 30.0, 0)

createStateObject

Creates an object containing state information. Returns empty object if invalid parameters are passed.

Syntax

ADB.Media.createStateObject(name)
Variable Name Type Description
name string Player State or non empty string denoting state name

Example

var stateObject = ADB.Media.createStateObject("customstate");

createQoEObject

Creates an object containing QoE information. Returns empty object if invalid parameters are passed.

Syntax

ADB.Media.createQoEObject(bitrate, startupTime, fps, droppedFrames)
Variable Name Type Description
bitrate number Positive number denoting current bitrate (0 if unknown)
startupTime number Positive number denoting startup time (0 if unknown)
fps number Positive number denoting current fps (0 if unknown)
droppedFrames number Positive number denoting number of dropped frames (0 if unknown)

Example

qoeObject = ADB.Media.createQoEObject(10000000, 2, 23, 10);

version

Returns MediaSDK version

Syntax

ADB.Media.version

Example

console.log(ADB.Media.version);

Instance methods

trackSessionStart

Track the intention to start playback. This starts a tracking session on the media tracker instance. Also see Media Resume.

Syntax

ADB.Media.trackSessionStart(mediaObject, contextData);
Variable Name Description Required
mediaObject 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

Example

var mediaObject = ADB.Media.createMediaObject("media-name", "media-id", 60, ADB.Media.StreamType.VOD, ADB.Media.MediaType.Video);

var contextData = {};
contextData[ADB.Media.VideoMetadataKeys.Episode] = "Sample Episode";
contextData[ADB.Media.VideoMetadataKeys.Show] = "Sample Show";
contextData["isUserLoggedIn"] = "false";
contextData["tvStation"] = "Sample TV Station";

tracker.trackSessionStart(mediaObject, contextData);

trackPlay

Track media play or resume after a previous pause.

Syntax

ADB.Media.trackPlay();

Example

tracker.trackPlay();

trackPause

Track media pause.

Syntax

ADB.Media.trackPause();

Example

tracker.trackPause();

trackComplete

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

Syntax

ADB.Media.trackComplete();

Example

tracker.trackComplete();

trackSessionEnd

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

Syntax

ADB.Media.trackSessionEnd();

Example

tracker.trackSessionEnd();

trackError

Track an error in media playback.

Syntax

ADB.Media.trackError(errorId);
Variable Name Description Required
errorId Non empty string containing error information Yes

Example

tracker.trackError("errorId");

trackEvent

Method to track media events.

Variable Name Description
event Media event
info For AdBreakStart event, the adbreak information is created by using the createAdBreakObject method. For 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 events, the state information is created by using the createStateObject method. This is not required for other events.
contextData Optional context data can be provided for AdStart and ChapterStart events. This is not required for other events.

Syntax

ADB.Media.trackEvent(event, info, contextData);

Examples

Tracking AdBreaks

// AdBreakStart
  var adBreakObject = ADB.Media.createAdBreakObject("preroll", 1, 0)
  tracker.trackEvent(ADB.Media.Event.AdBreakStart, adBreakObject);

// AdBreakComplete
  tracker.trackEvent(ADB.Media.Event.AdBreakComplete);

Tracking ads

// AdStart
  var adObject = ADB.Media.createAdObject("ad-name", "ad-id", 1, 15.0);

  var adMetadata = {};
  // Standard metadata keys provided by adobe.
  adMetadata[ADB.Media.AdMetadataKeys.Advertiser]  ="Sample Advertiser";
  adMetadata[ADB.Media.AdMetadataKeys.CampaignId] = "Sample Campaign";
  // Custom metadata keys
  adMetadata["affiliate"] = "Sample affiliate";

  tracker.trackEvent(ADB.Media.Event.AdStart, adObject, adMetadata);

// AdComplete
  tracker.trackEvent(ADB.Media.Event.AdComplete);

// AdSkip
  tracker.trackEvent(ADB.Media.Event.AdSkip);

Tracking chapters

// ChapterStart
  var chapterObject = ADB.Media.createChapterObject("chapter-name", 1, 60.0, 15.0);

  var chapterMetadata = {};
  chapterMetadata["segmentType"] = "Sample segment type";

  tracker.trackEvent(ADB.Media.Event.ChapterStart, chapterObject, chapterMetadata);

// ChapterComplete
  tracker.trackEvent(ADB.Media.Event.ChapterComplete);

// ChapterSkip
  tracker.trackEvent(ADB.Media.Event.ChapterSkip);

Tracking states

// StateStart (ex: Mute is switched on)
  var stateObject = ADB.Media.createStateObject(ADB.Media.PlayerState.Mute);
  tracker.trackEvent(ADB.Media.Event.StateStart, stateObject);

// StateEnd (ex: Mute is switched off)
  tracker.trackEvent(ADB.Media.Event.StateEnd, stateObject);

Tracking playback events

// BufferStart
  tracker.trackEvent(ADB.Media.Event.BufferStart);

// BufferComplete
  tracker.trackEvent(ADB.Media.Event.BufferComplete);

// SeekStart
  tracker.trackEvent(ADB.Media.Event.SeekStart);

// SeekComplete
  tracker.trackEvent(ADB.Media.Event.SeekComplete);

Tracking bitrate changes

// If the new bitrate value is available provide it to the tracker.
  var qoeObject = ADB.Media.createQoEObject(1000000, 2.4, 25, 10);
  tracker.updateQoEObject(qoeObject);

// Bitrate change
  tracker.trackEvent(ADB.Media.Event.BitrateChange);

updatePlayhead

Provides the current media playhead to the media tracker instance. For accurate tracking, call this method everytime the playhead changes. If the player does not notify playhead changes, call this method once every second with the most recent playhead.

Syntax

ADB.Media.updatePlayhead(time);
Variable Name Description
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, if the player does not provide information about the content duration, the value can be specified as the number of seconds since midnight UTC of that day.
Note: When using progress markers,the content duration is required and the playhead needs to be updated as number of seconds from the beginning of the media item, starting with 0.

Example

tracker.updatePlayhead(13.3);

//live streaming case example:
var UTCTimeInSeconds = Math.floor(Date.now() / 1000)
var timeFromMidnightInSecond = UTCTimeInSeconds % 86400
tracker.updatePlayhead(timeFromMidnightInSecond);

updateQoEObject

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

Syntax

ADB.Media.updateQoEObject(qoeObject);
Variable Name Description
qoeObject Current QoE information that was created by using the createQoEObject method.

Example

var qoeObject = ADB.Media.createQoEObject(1000000, 2.4, 25, 10);
tracker.updateQoEObject(qoeObject);

destroy

Destroys the tracker instance.

Syntax

ADB.Media.destroy();

Example

tracker.destroy();

Constants

Media type

This defines the type of a media that is currently tracked.

ADB.Media.MediaType = {
  Video: "video",
  Audio: "audio"
}

Stream type

This defines the stream type of the content that is currently tracked.

ADB.Media.StreamType = {
  VOD: "vod",
  Live: "live",
  Linear: "linear",
  Podcast: "podcast",
  Audiobook: "audiobook",
  AOD: "aod"
}

Standard video constants

This defines the standard metadata keys for video streams.

ADB.Media.VideoMetadataKeys {
  Show: "a.media.show",
  Season: "a.media.season",
  Episode: "a.media.episode",
  AssetId: "a.media.asset",
  Genre: "a.media.genre",
  FirstAirDate: "a.media.airDate",
  FirstDigitalDate: "a.media.digitalDate",
  Rating: "a.media.rating",
  Originator: "a.media.originator",
  Network: "a.media.network",
  ShowType: "a.media.type",
  AdLoad: "a.media.adLoad",
  MVPD: "a.media.pass.mvpd",
  Authorized: "a.media.pass.auth",
  DayPart: "a.media.dayPart",
  Feed: "a.media.feed",
  StreamFormat: "a.media.format"
}

Standard audio constants

This defines the standard metadata keys for audio streams.

ADB.Media.AudioMetadataKeys {
  Artist: "a.media.artist",
  Album: "a.media.album",
  Label: "a.media.label",
  Author: "a.media.author",
  Station: "a.media.station",
  Publisher: "a.media.publisher"
}

Standard ad constants

This defines the standard metadata keys for ads.

ADB.Media.AdMetadataKeys {
  Advertiser: "a.media.ad.advertiser",
  CampaignId: "a.media.ad.campaign",
  CreativeId: "a.media.ad.creative",
  PlacementId: "a.media.ad.placement",
  SiteId: "a.media.ad.site",
  CreativeUrl: "a.media.ad.creativeURL"
}

Media events

This defines the type of a tracking event.

ADB.Media.Event = {
  AdBreakStart: "adBreakStart",
  AdBreakComplete: "adBreakComplete",
  AdStart: "adStart",
  AdComplete: "adComplete",
  AdSkip: "adSkip",
  ChapterStart: "chapterStart",
  ChapterComplete: "chapterComplete",
  ChapterSkip: "chapterSkip",
  SeekStart: "seekStart",
  SeekComplete: "seekComplete",
  BufferStart: "bufferStart",
  BufferComplete: "bufferComplete",
  BitrateChange: "bitrateChange",
  StateStart: "stateStart",
  StateEnd: "stateEnd"
}

Player states

This defines standard values for tracking player state.

ADB.Media.PlayerState = {
  FullScreen: "fullScreen",
  ClosedCaption: "closedCaptioning",
  Mute: "mute",
  PictureInPicture: "pictureInPicture",
  InFocus: "inFocus"
}

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.

Syntax

 ADB.Media.MediaObjectKey = {
    MediaResumed: "media.resumed"
}

Example

var mediaObject = ADB.Media.createMediaObject("media-name", "media-id", 60, ADB.Media.StreamType.VOD, ADB.Media.MediaType.Video);

mediaObject[ADB.Media.MediaObjectKey.MediaResumed] = true;

tracker.trackSessionStart(mediaObject);

Granular ad tracking

Constant to enable 1 second ad tracking. This information must be provided when starting a tracking session.

Note Default ad ping interval is 10 seconds.

Syntax

 ADB.Media.MediaObjectKey = {
    GranularAdTracking: "media.granularadtracking"
}

Example

var mediaObject = ADB.Media.createMediaObject("media-name", "media-id", 60, ADB.Media.StreamType.VOD, ADB.Media.MediaType.Video);

// Enable granular ad tracking
mediaObject[ADB.Media.MediaObjectKey.GranularAdTracking] = true;

tracker.trackSessionStart(mediaObject);

ADB.MediaConfig

Key Required Description
trackingServer Yes Type the name of the media collection API server to which the downloaded media tracking data should be sent. Contact your Adobe account representative to receive this information.
channel No Channel name property
playerName No Name of the media player in use
appVersion No Type the version of the media player application/SDK
debugLogging No Enables or disables Media SDK logs (Default value : false)
ssl No Sends pings over SSL (Default value : true)