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 類別
欄位
方法
傳回錯誤處理常式的物件。
屬性
名稱 | 類型 | 說明 |
---|---|---|
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 類別
欄位
定義串流格式。
屬性
名稱 | 類型 | 說明 |
---|---|---|
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)
參數 | 類型 | 說明 |
---|---|---|
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)
載入廣告中繼資料,並使用提供的 streamManifestUrl
和 streamSubtitle
資料呼叫 loadUrl
函式。串流要求類型為 ima.StreamType.POD_VOD
時,這個函式才會生效。
參數 | 類型 | 說明 |
---|---|---|
streamManifest |
string |
拼接廣告的串流資訊清單網址。 |
streamSubtitle |
ifArray |
字幕與串流相關;如果無字幕,則為 |
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 |
|
串流的格式。預設值為 |
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 |
選用參數,將指派給傳回的 |
createPodLiveStreamRequest(customAssetKey, networkCode, apiKey)
初始化 Pod Live ima.StreamRequest
的必要屬性。使用這個 API 會導致其他 ima.StreamType
專用屬性遭到忽略。如果任何必要參數是空白字串,就會發生錯誤記錄,且 API 會傳回一般 StreamRequest
,且不會忽略任何屬性。
傳回 StreamRequest
: ima.StreamRequest
物件,其中包含必要的 PodLive 屬性。
參數 | 類型 | 說明 |
---|---|---|
customAssetKey |
string |
|
networkCode |
string |
|
apiKey |
string |
選用參數,會指派給傳回的 |
createPodVodStreamRequest(networkCode)
在使用 DAI Pod 放送廣告與第三方影片併接工具時,初始化 ima.StreamRequest
的必要屬性以註冊 VOD 串流。這個函式會將要求類型設為 ima.StreamType.POD_VOD
,並驗證遺漏資料的所有必要屬性。驗證失敗時,系統會在偵錯控制台中記錄錯誤。
傳回 StreamRequest
:ima.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.StreamType 類別
欄位
定義玩家要求播放的串流類型。片頭廣告和 VOD 應從直播一開始就播放。
屬性
名稱 | 類型 | 說明 |
---|---|---|
LIVE |
|
影片已上線。 |
VOD |
|
這部影片可以隨選觀看。 |
ima.WrapperInfo 類別
欄位
方法
包含包裝函式相關資訊。
屬性
名稱 | 類型 | 說明 |
---|---|---|
adId |
|
廣告 ID 或空字串 (如果不明)。 |
adSystem |
|
廣告系統的宣告名稱;如果不明,則為空字串。 |
creativeAdId |
|
廣告素材的廣告 ID 或空白字串 (如果不明)。 |
creativeId |
|
廣告素材的 ID 或空白字串 (如果不明)。 |
dealId |
|
交易 ID 或空白字串 (如果不明)。 |
createWrapperInfo()
傳回 ima.WrapperInfo
: