Skip to content

Latest commit

 

History

History
926 lines (707 loc) · 27 KB

media-migration.md

File metadata and controls

926 lines (707 loc) · 27 KB
Raw

Migrate from Adobe Media SDK to Adobe Experience Platform Roku SDK

Follow this guide to migrate from Adobe Media SDK to the latest Adobe Experience Platform Roku SDK.

Table of contents

Sections
Prerequisistes
API comparison between SDKs
Initialize SDK instance
Start Media session
Track Media events

Prerequisites

  1. Experience Data Model (XDM)
  2. Datastreams
  3. Getting Started with implementing Media tracking using AEP Roku SDK
  4. Setup schemas, datastream, dataset, Customer Journey Analytics (CJA) dashboard etc

API comparison

Note

AEP Roku SDK has only two APIs for tracking media createMediaSession() and sendMediaEvent().

Core Plaback APIs:

Media SDK AEP Roku SDK Sample
mediaTrackSessionStart(mediaInfo,mediaContextData) createMediaSession(sessionStartXDM) SessionStart
mediaTrackPlay() sendMediaEvent(playXDM) Play
mediaTrackPause() sendMediaEvent(pauseStartXDM) Pause
mediaTrackComplete() sendMediaEvent(sessionCompleteXDM) SessionComplete
mediaTrackSessionEnd() sendMediaEvent(sessionEndXDM) SessionEnd

Ad Tracking APIs:

Media SDK AEP Roku SDK Sample
mediaTrackEvent(ADBMobile().MEDIA_AD_BREAK_START, adBreakInfo, contextData) sendMediaEvent(adbreakStartXDM) AdBreakStart
mediaTrackEvent(ADBMobile().MEDIA_AD_BREAK_COMPLETE, invalid, invalid) sendMediaEvent(adbreakCompleteXDM) AdBreakComplete
mediaTrackEvent(ADBMobile().MEDIA_AD_START, adInfo, contextData) sendMediaEvent(adStartXDM) AdStart
mediaTrackEvent(ADBMobile().MEDIA_AD_COMPLETE, invalid, invalid) sendMediaEvent(adCompleteXDM) AdComplete
mediaTrackEvent(ADBMobile().MEDIA_AD_SKIP, invalid, invalid) sendMediaEvent(adSkipXDM) AdSkip

Buffer and Seek APIs

Media SDK AEP Roku SDK Sample
mediaTrackEvent(ADBMobile().MEDIA_BUFFER_START, invalid, invalid) sendMediaEvent(bufferStartXDM) BufferStart
mediaTrackEvent(ADBMobile().MEDIA_BUFFER_COMPLETE, invalid, invalid) sendMediaEvent(bufferCompleteXDM) BufferComplete
mediaTrackEvent(ADBMobile().MEDIA_SEEK_START, invalid, invalid) sendMediaEvent(pauseStartXDM) SeekStart
mediaTrackEvent(ADBMobile().MEDIA_SEEK_COMPLETE, invalid, invalid) sendMediaEvent(playXDM) SeekComplete

Note

For tracking seek in AEP Roku SDK, use eventType pauseStart with correct playhead. Media backend will detect seek based on change in playhead and timestamp values.

Chapter APIs

Media SDK AEP Roku SDK Sample
mediaTrackEvent(ADBMobile().MEDIA_CHAPTER_START, chapterInfo, chapterContextData) sendMediaEvent(chapterStartXDM) ChapterStart
mediaTrackEvent(ADBMobile().MEDIA_CHAPTER_COMPLETE, invalid, invalid) sendMediaEvent(chapterCompleteXDM) ChapterComplete
mediaTrackEvent(ADBMobile().MEDIA_CHAPTER_SKIP, invalid, invalid) sendMediaEvent(chapterSkipXDM) ChapterSkip

Quality of Experience (QoE) and Error APIs

Media SDK AEP Roku SDK Sample
mediaUpdateQoS(qosinfo) sendMediaEvent(bitrateChangeXDM) UpdateQoS
mediaTrackEvent(ADBMobile().MEDIA_BITRATE_CHANGE) sendMediaEvent(bitrateChangeXDM) BitrateChange
mediaTrackError(errorId, ADBMobile().ERROR_SOURCE_PLAYER) sendMediaEvent(errorXDM) Error

Note

QoE info has to be attached to the xdmData when calling sendMediaEvent(bitrateChangeXDM) for bitrateChange event. QoE info can also be attached to any other event's xdm data the sendMediaEvent(eventXDM) API. Refer to the QoeDataDetails fieldgroup

Playhead update API

Media SDK AEP Roku SDK
mediaUpdatePlayhead(position) NA (sent with all the APIs in the xdm data)

PlayerState Tracking API

Media SDK AEP Roku SDK
NA sendMediaEvent(statesUpdateXDM)

Helper APIs

Media SDK AEP Roku SDK
adb_media_init_mediainfo(title, id, length, streamType, mediaType) NA
adb_media_init_adbreakinfo(title, startTime, position) NA
adb_media_init_adinfo(title, id, position, duration) NA
adb_media_init_chapterinfo(title, position, length, startTime) NA
adb_media_init_qosinfo(bitrate, startupTime, fps, droppedFrames) NA

Initialize SDK instance

Media SDK

' Create adbmobileTask node
m.adbmobileTask = createObject("roSGNode","adbmobileTask")
' Create SDK instance
m.adbmobile = ADBMobile().getADBMobileConnectorInstance(m.adbmobileTask)

AEP Roku SDK

' Create SDK instance
m.aepSdk = AdobeAEPSDKInit()

Note

AEP Roku SDK creates the taskNode internally.

Start Media session

trackSessionStart

Media SDK

' Use the helper method to create mediaInfo object
name = "mediaName"
id = "mediaId"
length = 10
streamType = ADBMobile().MEDIA_STREAM_TYPE_VOD
mediaType = ADBMobile().MEDIA_TYPE_VIDEO

mediaInfo = adb_media_init_mediainfo(name, id, length, streamType, mediaType)

' (Optional) Attach standard metadata if any
standardMetadata = {}
standardMetadata[ADBMobile().MEDIA_VideoMetadataKeySHOW] = "sample show"

mediaInfo[ADBMobile().MEDIA_STANDARD_MEDIA_METADATA] = standardMetadata

' (Optional) Create map for custom metadadata if any
mediaContextData = {}
mediaContextData["cmk1"] = "cmv1"

' Call mediaTrackSessionStart API
m.adbmobile.mediaTrackSessionStart(mediaInfo, mediaContextData)

AEP Roku SDK

Important

createMediaSession() API requires sessionDetails fieldgroup with all the required fields present in the request payload.

SessionDetails Fields (Required)
friendlyName
name
length
contentType
streamType
channel
playerName 
sessionDetails = {
    ' (Required)
    "friendlyName": "mediaName",
    "name": "mediaId",
    "length": 10,
    "contentType": "vod",
    "streamType" : "video",

    ' (Required) Auto populated by the SDK based on Media configuration
    "channel": "sampleChannel",
    "playerName": "playerName,

    ' (Optional) Attach Standard metadata if any
    "show": "sample show"
}

' (Optional) Create map for custom data if any
customMetadata = [
  {
  "name" : "cmk1",
  "value" : "cmv1"
  }
]

sessionStartXDM = {
  "xdm": {
    "eventType": "media.sessionStart"
    "mediaCollection": {
      "playhead":  <CURRENT_PLAYHEAD_INTEGER_VALUE>,
      "sessionDetails": sessionDetails,
      "customMetadata": customMetadata
    }
  }
}

m.aepSdk.createMediaSession(sessionStartXDM)

Track Media events

trackPlay

Media SDK

m.adbmobile.mediaTrackPlay()

AEP Roku SDK

playXDM = {
  "xdm": {
    "eventType": "media.play",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>
    }
  }
}

m.aepSdk.sendMediaEvent(playXDM)

trackPause

Media SDK

m.adbmobile.mediaTrackPause()

AEP Roku SDK

pauseStartXDM = {
  "xdm": {
    "eventType": "media.pauseStart",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>,
    }
  }
}

m.aepSdk.sendMediaEvent(pauseStartXDM)

trackComplete

Media SDK

m.adbmobile.mediaTrackComplete()

AEP Roku SDK

sessionCompleteXDM = {
  "xdm": {
    "eventType": "media.sessionComplete",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>,
    }
  }
}

m.aepSdk.sendMediaEvent(sessionCompleteXDM)

trackSessionEnd

Media SDK

m.adbmobile.mediaTrackSessionEnd()

AEP Roku SDK

sessionEndXDM = {
  "xdm": {
    "eventType": "media.sessionEnd",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>,
    }
  }
}

m.aepSdk.sendMediaEvent(sessionEndXDM)

trackEvent

Track Ads

AdBreakStart

Media SDK

name = "adBreakName"
position = 1
startTime = 0

adBreakInfo = adb_media_init_adbreakinfo(name, position, startTime)

m.adbmobile.mediaTrackEvent(ADBMobile().MEDIA_AD_BREAK_START, adBreakInfo, invalid)

AEP Roku SDK

Important

sendMediaEvent() API for event type media.adBreakStart requires advertisingPodDetails fieldgroup with all the required fields present in the request payload.

AdvertisingPodDetails Fields (Required)
friendlyName
index
offset 
advertisingPodDetails = {
  ' (Required)
  "friendlyName": "adBreakName",
  "index": 1,
  "offset": 0
}

adBreakStartXDM = {
  "xdm": {
    "eventType": "media.adBreakStart",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>,
      "advertisingPodDetails": advertisingPodDetails
    }
  }
}

m.aepSdk.sendMediaEvent(adBreakStartXDM)

AdbreakComplete

m.adbmobile.mediaTrackEvent(ADBMobile().MEDIA_AD_BREAK_COMPLETE, invalid, invalid)

AEP Roku SDK

adBreakCompleteXDM = {
  "xdm": {
    "eventType": "media.adBreakComplete",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>
    }
  }
}

m.aepSdk.sendMediaEvent(adBreakCompleteXDM)

AdStart

Media SDK

name = "adName"
position = 1
length = 10
startTime = 0

adInfo = adb_media_init_adinfo(name, position, startTime)

''' (Optional) Attach standard metadata if any
standardAdMetadata = {}
standardAdMetadata[ADBMobile().MEDIA_AdMetadataKeyCAMPAIGN_ID] = "sampleCampaignID"

adInfo[ADBMobile().MEDIA_STANDARD_AD_METADATA] = standardAdMetadata

''' (Optional) Create a map of custom metadata if any
adContextData = {}
adContextData["cmk1"] = "cmv1"

m.adbmobile.mediaTrackEvent(ADBMobile().MEDIA_AD_START, adInfo, adContextData)

AEP Roku SDK

Important

sendMediaEvent() API for event type media.adStart requires advertisingDetails fieldgroup with all the required fields present in the request payload.

AdvertisingDetails Fields (Required)
friendlyName
name
podPosition
length
playerName 
advertisingDetails = {
  ' (Required)
  "friendlyName": "adName",
  "name": "adId",
  "podPosition": 1,
  "length": 10,
  "playerName": "samplePlayerName"

  ' (Optional) Attach Standard metadata if any
  "campaignID": "sampleCampaignID"
}

' (Optional) Create map for custom data if any
customMetadata = [
  {
  "name" : "cmk1",
  "value" : "cmv1"
  }
]

adStartXDM = {
  "xdm": {
    "eventType": "media.adStart",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>,
      "advertisingDetails": advertisingDetails,
      "customMetadata": customMetadata
    }
  }
}

m.aepSdk.sendMediaEvent(adStartXDM)

Note

To learn more refer to the advertisingDetails XDM fieldgroup.

AdComplete

Media SDK

m.adbmobile.mediaTrackEvent(ADBMobile().MEDIA_AD_COMPLETE, invalid, invalid)

AEP Roku SDK

adCompleteXDM = {
  "xdm": {
    "eventType": "media.adComplete",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>
    }
  }
}

m.aepSdk.sendMediaEvent(adCompleteXDM)

AdSkip

Media SDK

m.adbmobile.mediaTrackEvent(ADBMobile().MEDIA_AD_SKIP, invalid, invalid)

AEP Roku SDK

adSkipXDM = {
  "xdm": {
    "eventType": "media.adSkip",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>
    }
  }
}

m.aepSdk.sendMediaEvent(adSkipXDM)

Track Chapters

ChapterStart

Media SDK

name = "chapterName"
position = 1
length = 10
startTime = 0

chapterInfo = adb_media_init_chapterinfo(name, position, length, startTime)

''' (Optional) Create a map of custom metadata if any
chapterContextData = {}
chapterContextData["cmk1"] = "cmv1"

m.adbmobile.mediaTrackEvent(ADBMobile().MEDIA_CHAPTER_START, chapterInfo, chapterContextData)

AEP Roku SDK

Important

sendMediaEvent() API for event type media.chapterStart requires chapterDetails fieldgroup with all the required fields present in the request payload.

ChapterDetails Fields (Required)
friendlyName
index
length
offset 
chapterDetails = {
  "friendlyName": "chapterName",
  "index":1,
  "length": 10,
  "offset": 0
}

' (Optional) Create map for custom data if any
customMetadata = [
  {
  "name" : "cmk1",
  "value" : "cmv1"
  }
]

chapterStartXDM = {
  "xdm": {
    "eventType": "media.chapterStart",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>,
      "chapterDetails": chapterDetails,
      "customMetadata": customMetadata
    }
  }
}

m.aepSdk.sendMediaEvent(chapterStartXDM)

Note

To learn more refer to the chapterDetails XDM fieldgroup.

ChapterComplete

Media SDK

m.adbmobile.mediaTrackEvent(ADBMobile().MEDIA_CHAPTER_COMPLETE, invalid, invalid)

AEP Roku SDK

chapterCompleteXDM = {
  "xdm": {
    "eventType": "media.chapterComplete",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>
    }
  }
}

m.aepSdk.sendMediaEvent(chapterCompleteXDM)
ChapterSkip

Media SDK

m.adbmobile.mediaTrackEvent(ADBMobile().MEDIA_CHAPTER_SKIP, invalid, invalid)

AEP Roku SDK

chapterSkipXDM = {
  "xdm": {
    "eventType": "media.chapterSkip",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>
    }
  }
}

m.aepSdk.sendMediaEvent(chapterSkipXDM)

Track Buffer and Seek

BufferStart

Media SDK

m.adbmobile.mediaTrackEvent(MEDIA_BUFFER_START, invalid, invalid)

AEP Roku SDK

bufferStartXDM = {
  "xdm": {
    "eventType": "media.bufferStart",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>
    }
  }
}

m.aepSdk.sendMediaEvent(bufferStartXDM)
BufferComplete

Media SDK

m.adbmobile.mediaTrackEvent(ADBMobile().MEDIA_BUFFER_COMPLETE, invalid, invalid)

AEP Roku SDK

bufferCompleteXDM = {
  "xdm": {
    "eventType": "media.bufferComplete",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>
    }
  }
}

m.aepSdk.sendMediaEvent(bufferCompleteXDM)
SeekStart

Important

Seeking is detected automatically by the backend using the playhead and timestamp value. So at the seek start, playback pauses and can be tracked as pauseStart and when seek completes, playback resumes and can be tracked as play.

Media SDK

m.adbmobile.mediaTrackEvent(ADBMobile().MEDIA_SEEK_START, invalid, invalid)

AEP Roku SDK

seekStartXDM = {
  "xdm": {
    "eventType": "media.pauseStart",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>
    }
  }
}

m.aepSdk.sendMediaEvent(seekStartXDM)
SeekComplete

Media SDK

m.adbmobile.mediaTrackEvent(ADBMobile().MEDIA_SEEK_COMPLETE, invalid, invalid)

AEP Roku SDK

seekCompleteXDM = {
  "xdm": {
    "eventType": "media.play",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>
    }
  }
}

m.aepSdk.sendMediaEvent(seekCompleteXDM)
BitrateChange

Media SDK

' Use the helper method to create mediaInfo object
bitrate = 200000
fps = 24
droppedFrames = 1
startupTime = 2
qosInfo = m.adbmobile.adb_media_init_qosinfo(bitrate, startupTime, fps, droppedFrames)

m.adbmobile.mediaUpdateQoS(qosInfo)

m.adbmobile.mediaTrackEvent(ADBMobile().MEDIA_BITRATE_CHANGE, invalid, invalid)

AEP Roku SDK

qoeDataDetails = {
  "bitrate" : 200000,
  "framesPerSecond" : 24,
  "droppedFrames" : 1,
  "timeToStart" : 2
}

bitrateChangeXDM = {
  "xdm": {
    "eventType": "media.bitrateChange",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>,
      "qoeDataDetails": qoeDataDetails
    }
  }
}

m.aepSdk.sendMediaEvent(bitrateChangeXDM)

updateCurrentPlayhead

Media SDK

m.adbmobile.updateCurrentPlayhead(<CURRENT_PLAYHEAD_INTEGER_VALUE>)

AEP Roku SDK

Important

Playhead value is expected in the XDM data for all the API calls. AEP Roku SDK requires calling ping event with latest playhead value every second as a proxy for updateCurrentPlayhead API.

playheadUpdatePingXDM = {
  "xdm": {
    "eventType": "media.ping",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>
    }
  }
}


m.aepSdk.sendMediaEvent(playheadUpdatePingXDM)

updateQoS

Media SDK

' Use the helper method to create mediaInfo object
bitrate = 200000
fps = 24
droppedFrames = 1
startupTime = 2
qosInfo = m.adbmobile.adb_media_init_qosinfo(bitrate, startupTime, fps, droppedFrames)

m.adbmobile.mediaUpdateQoS(qosInfo)

AEP Roku SDK

Important

All the QoE field values should be of Integer data type.

qoeDataDetails = {
  "bitrate" : 200000,
  "framesPerSecond" : 24,
  "droppedFrames" : 1,
  "timeToStart" : 2
}

bitrateChangeXDM = {
  "xdm": {
    "eventType": "media.bitrateChange",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>,
      "qoeDataDetails": qoeDataDetails
    }
  }
}

m.aepSdk.sendMediaEvent(bitrateChangeXDM)

Note

To learn more refer to the qoeDataDetails XDM fieldgroup. qoeDataDetails is supported and can be attached to any event going out.

Following is the sample to send qoeDataDetails with play event:

playWithQoeXDM = {
  "xdm": {
    "eventType": "media.play",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>,
      "qoeDataDetails": qoeDataDetails
    }
  }
}

m.aepSdk.sendMediaEvent(playWithQoeXDM)

trackError

Media SDK

m.adbmobile.mediaTrackError("errorId", "video-player-error-code")

AEP Roku SDK

errorDetails = {
  "name": "errorId",
  "source": "video-player-error-code"
}

errorXDM = {
  "xdm": {
    "eventType": "media.error",
    "mediaCollection": {
      "playhead": <CURRENT_PLAYHEAD_INTEGER_VALUE>,
      "errorDetails": errorDetails
    }
  }
}

m.aepSdk.sendMediaEvent(errorXDM)

Note

To learn more refer to the errorDetails XDM fieldgroup.

Public Constants

StreamType

Media SDK AEP Roku SDK
MEDIA_STREAM_TYPE_VOD "vod"
MEDIA_STREAM_TYPE_LIVE "live"
MEDIA_STREAM_TYPE_LINEAR "linear"
MEDIA_STREAM_TYPE_AOD "aod"
MEDIA_STREAM_TYPE_AUDIOBOOK "audiobook"
MEDIA_STREAM_TYPE_PODCAST "podcast"

MediaType

Media SDK AEP Roku SDK
MEDIA_STREAM_TYPE_AUDIO xdm:streamType
MEDIA_STREAM_TYPE_VIDEO xdm:streamType

Standard Video Metadata

Media SDK AEP Roku SDK
MEDIA_VideoMetadataKeyAD_LOAD xdm:adLoad
MEDIA_VideoMetadataKeyASSET_ID xdm:assetID
MEDIA_VideoMetadataKeyAUTHORIZED xdm:authorized
MEDIA_VideoMetadataKeyDAY_PART xdm:dayPart
MEDIA_VideoMetadataKeyEPISODE xdm:episode
MEDIA_VideoMetadataKeyFEED xdm:feed
MEDIA_VideoMetadataKeyFIRST_AIR_DATE xdm:firstAirDate
MEDIA_VideoMetadataKeyFIRST_DIGITAL_DATE xdm:firstDigitalDate
MEDIA_VideoMetadataKeyGENRE xdm:genre
MEDIA_VideoMetadataKeyMVPD xdm:mvpd
MEDIA_VideoMetadataKeyNETWORK xdm:network
MEDIA_VideoMetadataKeyORIGINATOR xdm:originator
MEDIA_VideoMetadataKeyRATING xdm:rating
MEDIA_VideoMetadataKeySEASON xdm:season
MEDIA_VideoMetadataKeySHOW xdm:show
MEDIA_VideoMetadataKeySHOW_TYPE xdm:showType
MEDIA_VideoMetadataKeySTREAM_FORMAT xdm:streamFormat

Standard Audio Metadata

Media SDK AEP Roku SDK
MEDIA_AudioMetadataKeyARTIST xdm:artist
MEDIA_AudioMetadataKeyAUTHOR xdm:author
MEDIA_AudioMetadataKeyLABEL xdm:label
MEDIA_AudioMetadataKeyPUBLISHER xdm:publisher
MEDIA_AudioMetadataKeySTATION xdm:station

Standard Ad Metadata

Media SDK AEP Roku SDK
MEDIA_AdMetadataKeyADVERTISER xdm:advertiser
MEDIA_AdMetadataKeyCAMPAIGN_ID xdm:campaignID
MEDIA_AdMetadataKeyCREATIVE_ID xdm:creativeID
MEDIA_AdMetadataKeyCREATIVE_URL xdm:creativeURL
MEDIA_AdMetadataKeyPLACEMENT_ID xdm:placementID
MEDIA_AdMetadataKeySITE_ID xdm:siteID