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,片中廣告則會傳回 Pod 的排定時間。 |
totalAds |
|
此廣告時段中包含的廣告總數。如果是獨立廣告,則值為 1。 |
createAdBreakInfo()
傳回 ima.AdBreakInfo
:
ima.AdEvent 類別
欄位
Ad Manager 啟動的事件。
屬性
名稱 | 類型 | 說明 |
---|---|---|
AD_PERIOD_ENDED |
|
每當直播從廣告或插入畫面切換到內容時觸發。即使廣告是第二次播放或尋找廣告,也會觸發此動作。 |
AD_PERIOD_STARTED |
|
每次串流從內容切換到廣告或插入畫面時觸發。 即使廣告是第二次播放或尋找廣告,也會觸發此動作。 |
COMPLETE |
|
廣告播放完畢時會啟動。 |
ERROR |
|
發生錯誤時觸發。 |
FIRST_QUARTILE |
|
廣告播放頭跨過第一個四分位數時觸發。 |
ICON_FALLBACK_IMAGE_CLOSED |
|
在使用者關閉圖示備用圖片對話方塊時觸發。 |
ICON_FALLBACK_IMAGE_SHOWN |
|
在顯示圖示備用圖片時觸發。 |
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。 |
skipOffset |
|
略過廣告所需的時間,如果不明,則為 -1。 |
universalAdIDRegistry |
|
此字串用於識別登錄網站的網址 (所選廣告素材的通用廣告 ID 已編入目錄)。 |
universalAdIDValue |
|
廣告所選廣告素材的通用廣告 ID。 |
wrappers |
|
此廣告的 ima.WrapperInfo 陣列。順序將從外部包裝函式變更為內部。 |
createAdInfo()
傳回 ima.AdInfo
:
ima.Companion 類別
欄位
方法
包含廣告的隨播廣告相關資訊。
屬性
名稱 | 類型 | 說明 |
---|---|---|
apiFramework |
|
執行這則廣告所需的 API;如果無法使用,則為無效。 |
creativeType |
|
代表廣告素材類型,通常是 MIME 類型。 |
height |
|
隨播廣告的高度 (以像素為單位)。如果無法使用,則為 0。 |
trackingEvents |
|
追蹤事件對應,鍵為事件,而值則是在該事件發生連線偵測 (ping) 的網址清單。 |
url |
|
此隨播廣告的靜態資源網址。 |
width |
|
隨播廣告的寬度 (以像素為單位)。如果無法使用,則為 0。 |
createCompanion()
傳回 ima.Companion
:
ima.CuePoint 類別
欄位
方法
內含提示點相關資訊。
屬性
名稱 | 類型 | 說明 |
---|---|---|
end |
|
提示點的結束時間,以秒為單位。這會對應至廣告插播。 |
hasPlayed |
|
表示提示點已播放的布林值。 |
start |
|
提示點的開始時間 (以秒為單位)。這會對應至廣告插播。 |
createCuePoint()
傳回 ima.CuePoint
:
ima.Error 類別
欄位
方法
在發生錯誤時傳遞至錯誤處理常式的物件。
屬性
名稱 | 類型 | 說明 |
---|---|---|
id |
|
錯誤的 ID。如需錯誤代碼清單,請參閱 ErrorEvent 常數。 |
info |
|
錯誤的其他相關資訊。 |
type |
|
請一律設為 error ,以指出這個物件的類型。 |
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 或破折號。 以 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、結束和已 Play 的物件。如果沒有可用的提示點,則傳回無效。
參數 | 類型 | 說明 |
---|---|---|
time |
Float |
查詢時間,-1 表示目前時間。 |
getStreamTime(contentTime)
取得內容時間的串流時間 (以毫秒為單位)。
請參閱: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 |
|
選用設定。這些金鑰可用於驗證串流要求。您必須在 DFP 使用者介面中設定 DAI 驗證金鑰。 |
assetKey |
|
直播的必要項目。可用來決定要播放的串流。直播活動要求素材資源金鑰是可在 DFP UI 中找到的 ID。 |
authToken |
|
串流要求授權權杖。用來取代 API 金鑰以執行更嚴格的內容授權。發布者可根據這個權杖控制個別內容串流授權。 |
contentSourceId |
|
隨選串流的必要項目。cmsid 取自 DFP 使用者介面中的 DFP 影片內容來源。 |
customAssetKey |
|
自訂資產金鑰可用來決定要播放的串流。必須提供自訂素材資源金鑰,才能提出廣告連播放送串流請求。 |
format |
|
串流格式。預設值為 |
networkCode |
|
發出串流請求的發布商聯播網代碼。Pod 提供串流要求需要網路代碼。 |
player |
|
播放器介面的實作。 |
ppid |
|
已淘汰,使用 adTagParameters。 選用設定。DFP 目標對象發布商提供的 ID。 |
streamActivityMonitorId |
|
透過串流活動監控器對串流偵錯時使用的 ID。這可讓發布者輕鬆在串流活動監控工具中尋找串流記錄。 |
videoId |
|
隨選串流的必要項目。影片內容來源的 ID。 |
videoObject |
|
負責在用戶端應用程式中播放影片的影片物件 (例如影片 roSGNode)。系統會輪詢這個物件,以便取得各種資料,以便在正確時間的即時 HLS ID3 事件中使用。 |
videoStitcherSessionOptions |
|
工作階段選項可用來為 VideoStitcher streamRequests 設定影片刷卡專用參數。 |
createLiveStreamRequest(assetKey, apiKey)
初始化 Live StreamRequest
的必要屬性。使用這個 API 會導致系統忽略任何其他 StreamType
專屬屬性。如果任何必要參數是空白字串,就會發生錯誤記錄,API 會傳回一般的 StreamRequest
,而不會忽略任何屬性。
傳回 ima.StreamRequest
: ima.StreamRequest
物件包含必要的 Live 屬性。
參數 | 類型 | 說明 |
---|---|---|
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)
初始化影片拼接工具 Live 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 |
CreateVideoStitcherVodStreamRequestWithVodConfig(vodConfigId, networkCode, region, projectNumber, oAuthToken)
使用透過雲端影片併接工具建立的 vodConfigId
,初始化影片拼接工具 VOD StreamRequest
的必要屬性。使用這個 API 會導致系統忽略其他 StreamType
專用屬性。如果任何必要參數是空白字串,就會發生錯誤記錄,API 會傳回一般的 StreamRequest
,而不會忽略任何屬性。
傳回 ima.StreamRequest
: ima.StreamRequest
物件具有必要的 VideoStitcherVod 屬性。
參數 | 類型 | 說明 |
---|---|---|
vodConfigId |
string |
|
networkCode |
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
: