適用於 Roku 的 IMA DAI SDK

    1. 圖片
    2. ima.AdBreakInfo
    3. ima.AdEvent
    4. ima.AdInfo
    5. ima.Companion
    6. ima.CuePoint
    7. ima.Error
    8. ima.ErrorEvent
    9. ima.Player
    10. ima.StreamFormat
    11. ima.StreamInfo
    12. ima.StreamManager
    13. ima.StreamRequest
    14. ima.StreamType
    15. ima.WrapperInfo

ima

方法

控制 IMA SDK 的全域函式。

disableLogging()

停用 SDK 記錄。記錄功能預設為開啟。

getStreamManager()

傳回串流管理員 (如果有的話)。如果串流管理員尚未播映,則會傳回「無效」。如果建立串流管理員時發生錯誤,則會傳回錯誤物件。

傳回 object串流管理員或錯誤物件。

initSdk(settings)

初始化 SDK。

參數 類型 說明
settings object

選用的 IMA 設定物件。

requestStream(streamRequest)

呼叫此方法後,系統會立即啟動非同步串流要求 Control 返回播放器。

傳回 object錯誤;如果沒有錯誤,則傳回無效

參數 類型 說明
streamRequest object

返回頁首

ima.AdBreakInfo 類別

欄位

方法

包含廣告插播的相關資訊。會傳遞給 SDK 的事件回呼。

屬性

名稱 類型 說明
adPosition

廣告插播中的廣告索引。如果是獨立廣告,則值為 1。

duration

廣告插播的時間長度上限 (以秒為單位),如果不明,則為 -1。

podIndex

如果是直播,請一律傳回 -1。如果是隨選影片 (VOD),會傳回廣告連播的索引。如果是片頭廣告連播,會傳回 0。針對片中廣告,會傳回 1、2、...、n。針對片尾廣告連播,會傳回 n+1...n+x。如果這則廣告不屬於廣告連播,或這個廣告連播不屬於任何播放清單,則預設值為 0。

timeOffset

廣告連播在內容中的位置 (以秒為單位)。片頭廣告會傳回 0,片尾廣告傳回 -1,而片中廣告會傳回廣告連播的排定時間。

totalAds

這個廣告插播中包含的廣告總數。如果是獨立廣告,則值為 1。

createAdBreakInfo()


傳回 ima.AdBreakInfo

返回頁首

ima.AdEvent 類別

欄位

廣告管理系統觸發的事件。

屬性

名稱 類型 說明
AD_PERIOD_ENDED

每次串流從廣告或插入內容切換至內容時觸發。即使廣告再次播放或尋找廣告,系統也會觸發此事件。

AD_PERIOD_STARTED

每次串流從內容切換至廣告或插入畫面時觸發。即使廣告再次播放或尋找廣告,系統也會觸發此事件。

COMPLETE

廣告播放完畢時會啟動。

ERROR

發生錯誤時觸發。

FIRST_QUARTILE

廣告播放頭跨過第一個四分位數時觸發。

MIDPOINT

廣告播放頭跨過中點時觸發。

PROGRESS

在有廣告進度更新時觸發。

SKIPPABLE_STATE_CHANGED

廣告可略過狀態變更時觸發。

SKIPPED

廣告略過時觸發。

START

廣告開始播放時觸發。

THIRD_QUARTILE

廣告播放頭跨過第三個四分位數時觸發。

返回頁首

ima.AdInfo 類別

欄位

方法

包含廣告相關資訊。會傳遞給 SDK 的事件回呼。

屬性

名稱 類型 說明
adBreakInfo

與這則廣告所在整個廣告插播時間點相關的資訊。

adDescription

廣告的說明。

adId

廣告 ID 或空字串 (如果不明)。

adSystem

提供廣告素材的廣告系統。

adTitle

廣告標題。

advertiserName

放送方定義的廣告主名稱。

companions

VAST 回應中指定的隨播廣告。

currentTime

廣告目前的時間 (以秒為單位);如果不明,則為 -1。

duration

此廣告的長度 (以秒為單位) 或 -1 (如果不明)。

universalAdIDRegistry

字串,用於識別登錄網站的網址,也就是將所選廣告素材的通用廣告 ID 編入目錄。

universalAdIDValue

廣告所選廣告素材的通用廣告 ID。

wrappers

ima.WrapperInfo 的陣列,包含此廣告的包裝函式資訊。順序會從外包裝函式到內部。

createAdInfo()


傳回 ima.AdInfo

返回頁首

ima.Companion 類別

欄位

方法

包含廣告隨播廣告的相關資訊。

屬性

名稱 類型 說明
apiFramework

執行這則廣告所需的 API;如未提供,則無效。

creativeType

代表廣告素材類型 (通常是 MIME 類型)。

height

隨播廣告的高度 (以像素為單位)。0 表示無法使用。

trackingEvents

追蹤事件對應,其中鍵為事件,值是該事件要連線偵測的網址清單。

url

此隨播廣告的靜態資源網址。

width

隨播廣告的寬度 (以像素為單位)。0 表示無法使用。

createCompanion()


傳回 ima.Companion

返回頁首

ima.CuePoint 類別

欄位

方法

包含提示點相關資訊。

屬性

名稱 類型 說明
end

提示點的結束時間 (以秒為單位)。這對應廣告插播時間點。

hasPlayed

表示提示點已經播放的布林值。

start

提示點的開始時間 (以秒為單位)。這對應廣告插播時間點。

createCuePoint()


傳回 ima.CuePoint

返回頁首

ima.Error 類別

欄位

idinfotype

方法

傳回錯誤處理常式的物件。

屬性

名稱 類型 說明
id

錯誤 ID。如需錯誤代碼清單,請參閱 ErrorEvent 常數。

info

錯誤的其他相關資訊。

type

一律設為錯誤來指出這個物件的類型。

createError()


傳回 ima.Error

返回頁首

ima.ErrorEvent 類別

欄位

SDK 可能傳回的所有錯誤。

屬性

名稱 類型 說明
BAD_STREAM_REQUEST

串流請求未正確填入。

COULD_NOT_LOAD_STREAM

無法載入訊息串。

ERROR

發生不明錯誤。

INVALID_RESPONSE

伺服器回應無效。

STREAM_API_KEY_NOT_VALID

伺服器不接受您提供的 API 金鑰。

返回頁首

ima.Player 類別

方法

adBreakEnded(adBreakInfo)

選用設定。在廣告插播結束時呼叫。

參數 類型 說明
adBreakInfo ima.AdBreakInfo

包含廣告插播的相關資訊。

adBreakStarted(adBreakInfo)

選用設定。廣告插播開始時呼叫。

參數 類型 說明
adBreakInfo ima.AdBreakInfo

包含廣告插播的相關資訊。

allVideoComplete()

選用設定。所有影片都播放完畢時,會呼叫此方法。

createPlayer()

建立空白的 IMA Player 物件。您必須實作 loadUrl 函式才能播放廣告。其他函式則為選用功能。

傳回 ima.Player

loadUrl(streamInfo)

在播放器開始播放網址時呼叫。您必須實作這個方法才能載入串流。

參數 類型 說明
streamInfo ima.StreamInfo

包含播放內容所需的資訊。

返回頁首

ima.StreamFormat 類別

欄位

DASHHLS

定義串流格式。

屬性

名稱 類型 說明
DASH

HLS

返回頁首

ima.StreamInfo 類別

欄位

方法

從 SDK 傳遞給播放器的串流相關資訊。

屬性

名稱 類型 說明
format

影片格式:hl 或 dash。 以 ima.StreamFormat 定義。

manifest

串流的網址。

streamId

串流的專屬 ID。

streamType

影片類型:直播或隨選。 在 ima.StreamType 中定義。

subtitles

字幕 (如有)。設為無效則無效。

createStreamInfo()


傳回 ima.StreamInfo

返回頁首

ima.StreamManager 類別

方法

用於管理串流播放的物件。

addEventListener(event, callback)

新增指定事件的事件監聽器。如要瞭解支援的事件,請參閱 AdEvents 常數。

參數 類型 說明
event string

callback function

createStreamManager(streamRequest, streamInitResponse)


傳回 ima.StreamManager

參數 類型 說明
streamRequest ima.StreamRequest

streamInitResponse ima.StreamInitResponse

enableInteractiveAds()

不支援。請改為將資料從隨播廣告直接傳送至 RAF。這已經是不行。

getContentTime(streamTime)

取得 VOD 串流的時間 (以毫秒為單位),代表無廣告內容中的時間。請參閱:https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/roku/faq 如要取得目前串流時間的內容時間,請見 -1。

傳回 Integer與指定串流時間相對應的內容時間。

參數 類型 說明
streamTime Integer

串流中的時間。

getCuePoints()

傳回與所有廣告插播時間點相對應的提示點。這項功能僅適用於事先得知所有廣告插播時間點的隨選影片內容。所有時間都代表串流時間 (以秒為單位)。

傳回 Object包含所有提示點的陣列。

getPreviousCuePoint(time)

傳回此時間之前的提示點。提示點代表廣告插播。所有時間都代表串流時間 (以秒為單位)。

傳回 ima.CuePoint包含 start、end 和 hasPlayed 的物件。如果沒有提示點,則傳回無效。

參數 類型 說明
time Float

查詢時間,-1 表示目前時間。

getStreamTime(contentTime)

取得 VOD 內容時間的串流時間 (以毫秒為單位)。請參閱:https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/roku/faq

傳回 Integer與指定內容時間相對應的串流時間。

參數 類型 說明
contentTime Integer

內容的時間。

loadThirdPartyStream(streamManifest, streamSubtitle)

載入廣告中繼資料,並使用提供的 streamManifestUrlstreamSubtitle 資料呼叫 loadUrl 函式。串流要求類型為 ima.StreamType.POD_VOD 時,這個函式才會生效。

參數 類型 說明
streamManifest string

拼接廣告的串流資訊清單網址。

streamSubtitle ifArray>|Invalid

字幕與串流相關;如果無字幕,則為 Invalid

onMessage(msg)

處理所有來自影片物件的訊息。 透過 roMessagePort 接收的每則訊息都必須呼叫。

參數 類型 說明
msg object

來自 roVideo 連接埠的訊息。

replaceAdTagParameters(adTagParameters)

取代即將用於直播活動的所有廣告代碼參數。請注意,這項呼叫不適用於 VOD 串流。

參數 類型 說明
adTagParameters string

新的廣告代碼參數。

start()

開始播放串流。

返回頁首

ima.StreamRequest 類別

欄位

方法

用於指定串流要求的屬性。

屬性

名稱 類型 說明
adTagParameters

選用設定。您可以覆寫串流請求中的一組廣告代碼參數。「為串流提供指定參數」一文提供更多資訊。您也可以使用 dai-ot 和 dai-ov 參數做為串流變化版本偏好設定。詳情請參閱「覆寫串流變化版本參數」。

adUiNode

顯示廣告 UI 的場景圖節點。IMA 會在廣告播放期間,將「為什麼會顯示這則廣告」和「略過」按鈕等元素放在這個元素上。該元素必須重疊於整個影片元素。

apiKey

選用設定。這些金鑰可用來驗證串流要求。DAI 驗證金鑰必須在 DFP 使用者介面中設定。

assetKey

直播的必要項目。這會用於決定應播放哪個串流。直播請求資產金鑰是 DFP UI 中可以找到的識別碼。

authToken

串流要求授權權杖。用於取代 API 金鑰,以執行更嚴格的內容授權。發布者可根據這個權杖控制個別內容串流授權。

contentSourceId

隨選串流的必要項目。cmsid 來自 DFP UI 中的 DFP 影片內容來源。

customAssetKey

自訂資產索引鍵的用途是決定要播放哪個串流。廣告連播放送串流請求必須使用自訂素材資源金鑰。

format

串流的格式。預設值為 ima.StreamFormat.HLS

networkCode

提出串流請求的發布商聯播網代碼。必須提供網路代碼,才能發出 Pod 放送串流要求。

player

播放器介面的實作。

ppid

已淘汰,使用 adTagParameters。 選用設定。DFP 目標對象發布商提供的 ID

streamActivityMonitorId

這是要用於透過串流活動監控器對串流進行偵錯的 ID。這可讓發布者輕鬆在串流活動監控工具中尋找串流記錄。

videoId

隨選串流的必要項目。影片內容來源的 ID。

videoObject

負責在用戶端應用程式中播放影片的影片物件 (例如影片 roSGNode)。系統會輪詢這個物件的各種資料,以便適當使用即時 HLS ID3 事件的時間。

createLiveStreamRequest(assetKey, apiKey)

初始化 Live StreamRequest 的必要屬性。使用這個 API 會導致其他 StreamType 特定屬性遭到忽略。如果任何必要參數是空白字串,就會發生錯誤記錄,且 API 會傳回一般 StreamRequest,且不會忽略任何屬性。

傳回 ima.StreamRequest具有必要 Live 屬性的 ima.StreamRequest 物件。

參數 類型 說明
assetKey string

apiKey string

選用參數,將指派給傳回的 StreamRequestapiKey 屬性;預設為空字串。

createPodLiveStreamRequest(customAssetKey, networkCode, apiKey)

初始化 Pod Live ima.StreamRequest 的必要屬性。使用這個 API 會導致其他 ima.StreamType 專用屬性遭到忽略。如果任何必要參數是空白字串,就會發生錯誤記錄,且 API 會傳回一般 StreamRequest,且不會忽略任何屬性。

傳回 StreamRequest ima.StreamRequest 物件,其中包含必要的 PodLive 屬性。

參數 類型 說明
customAssetKey string

networkCode string

apiKey string

選用參數,會指派給傳回的 ima.StreamRequestima.StreamRequest.apiKey 屬性;預設為空字串。

createPodVodStreamRequest(networkCode)

在使用 DAI Pod 放送廣告與第三方影片併接工具時,初始化 ima.StreamRequest 的必要屬性以註冊 VOD 串流。這個函式會將要求類型設為 ima.StreamType.POD_VOD,並驗證遺漏資料的所有必要屬性。驗證失敗時,系統會在偵錯控制台中記錄錯誤。

傳回 StreamRequestima.StreamRequest 物件。如果指定所有必要屬性,要求類型會設為 ima.StreamType.POD_VOD

參數 類型 說明
networkCode string

Google Ad Manager 聯播網代碼

createStreamRequest()


傳回 ima.StreamRequest一個空的 ima.StreamRequest 物件。

createVideoStitcherLiveStreamRequest(customAssetKey, networkCode, liveConfigId, region, projectNumber, oAuthToken)

初始化影片拼接工具即時 StreamRequest 的必要屬性。使用這個 API 會導致其他 StreamType 特定屬性遭到忽略。如果任何必要參數是空白字串,就會發生錯誤記錄,且 API 會傳回一般 StreamRequest,且不會忽略任何屬性。

傳回 ima.StreamRequest ima.StreamRequest 物件,其中包含必要 VideoStitcherLive 屬性。

參數 類型 說明
customAssetKey string

networkCode string

liveConfigId string

region string

projectNumber string

oAuthToken string

createVideoStitcherVodStreamRequest(adTagUrl, networkCode, contentSourceUrl, region, projectNumber, oAuthToken)

初始化影片拼接工具 VOD StreamRequest 的必要屬性。使用這個 API 會導致其他 StreamType 特定屬性遭到忽略。如果任何必要參數是空白字串,就會發生錯誤記錄,且 API 會傳回一般 StreamRequest,且不會忽略任何屬性。

傳回 ima.StreamRequest ima.StreamRequest 物件,其中包含必要 VideoStitcherVod 屬性。

參數 類型 說明
adTagUrl string

networkCode string

contentSourceUrl string

region string

projectNumber string

oAuthToken string

createVodStreamRequest(contentSourceId, videoId, apiKey)

初始化 VOD ima.StreamRequest 的必要屬性。使用這個 API 會導致其他 ima.StreamType 特定屬性遭到忽略。如果任何必要參數是空白字串,就會發生錯誤記錄,且 API 會傳回一般 StreamRequest,且不會忽略任何屬性。

傳回 ima.StreamRequest ima.StreamRequest 物件,其中包含必要 VOD 屬性。

參數 類型 說明
contentSourceId string

videoId string

apiKey string

選用參數,會指派給傳回的 ima.StreamRequestima.StreamRequest.apiKey 屬性;預設為空字串。

返回頁首

ima.StreamType 類別

欄位

定義玩家要求播放的串流類型。片頭廣告和 VOD 應從直播一開始就播放。

屬性

名稱 類型 說明
LIVE

影片已上線。

VOD

這部影片可以隨選觀看。

返回頁首

ima.WrapperInfo 類別

欄位

方法

包含包裝函式相關資訊。

屬性

名稱 類型 說明
adId

廣告 ID 或空字串 (如果不明)。

adSystem

廣告系統的宣告名稱;如果不明,則為空字串。

creativeAdId

廣告素材的廣告 ID 或空白字串 (如果不明)。

creativeId

廣告素材的 ID 或空白字串 (如果不明)。

dealId

交易 ID 或空白字串 (如果不明)。

createWrapperInfo()


傳回 ima.WrapperInfo

返回頁首