適用於 Roku 的 IMA DAI SDK

1. 1. ima
   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，片中廣告則會傳回 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)

傳回 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、結束和已 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>|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		選用設定。這些金鑰可用於驗證串流要求。您必須在 DFP 使用者介面中設定 DAI 驗證金鑰。
assetKey		直播的必要項目。可用來決定要播放的串流。直播活動要求素材資源金鑰是可在 DFP UI 中找到的 ID。
authToken		串流要求授權權杖。用來取代 API 金鑰以執行更嚴格的內容授權。發布者可根據這個權杖控制個別內容串流授權。
contentSourceId		隨選串流的必要項目。cmsid 取自 DFP 使用者介面中的 DFP 影片內容來源。
customAssetKey		自訂資產金鑰可用來決定要播放的串流。必須提供自訂素材資源金鑰，才能提出廣告連播放送串流請求。
format		串流格式。預設值為 ima.StreamFormat.HLS。
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	選用參數，會指派給傳回的 StreamRequest 的 apiKey 屬性；預設為空字串。

createPodLiveStreamRequest(customAssetKey, networkCode, apiKey)

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

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

參數	類型	說明
customAssetKey	string
networkCode	string
apiKey	string	選用參數，會指派給傳回的 ima.StreamRequest 的 ima.StreamRequest.apiKey 屬性；預設為空字串。

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.StreamRequest 的 ima.StreamRequest.apiKey 屬性；預設為空字串。

返回頁首

ima.StreamType 類別

欄位

定義系統要求播放器播放的串流類型。片頭廣告和 VOD 應從串流開頭播放。

屬性

名稱	類型	說明
LIVE		影片已上線，
VOD		影片是隨選的，

返回頁首

ima.WrapperInfo 類別

欄位

方法

包含包裝函式相關資訊。

屬性

名稱	類型	說明
adId		廣告 ID；如果不知道的話，則為空白字串。
adSystem		廣告系統的宣告名稱；如果不明，則為空白字串。
creativeAdId		廣告素材中的廣告 ID，如果不明，則為空白字串。
creativeId		廣告素材 ID 或空白字串 (如果不知道)。
dealId		如果不知道，交易 ID 或空白字串。

createWrapperInfo()

傳回 ima.WrapperInfo：

返回頁首