適用於 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

Class ima

方法

disableLogging、 getStreamManager、 initSdk、 requestStream

控制 IMA SDK 的全域函式。

disableLogging()

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

getStreamManager()

如果可用，則傳回串流管理員。如果串流管理員尚未提供，系統會傳回「Invalid」。如果建立串流管理員時發生錯誤，系統會傳回錯誤物件。

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

initSdk(settings)

初始化 SDK。

參數	類型	說明
settings	object	選用的 IMA 設定物件。

requestStream(streamRequest)

開始非同步串流要求。呼叫這個方法後，控制項會立即返回播放器。

傳回 object：如果沒有錯誤，則為錯誤或無效

參數	類型	說明
streamRequest	object

返回頁首

Class ima.AdBreakInfo

欄位

adPosition、 duration、 podIndex、 timeOffset、 totalAds

方法

createAdBreakInfo

內含廣告插播的相關資訊。由 SDK 傳遞至事件回呼。

屬性

名稱	類型	說明
adPosition		廣告插播中廣告的索引。索引適用於1獨立廣告。
duration		中斷時間長度上限 (以秒為單位)，或 -1 (如為不明)。
podIndex		如果是直播，則會將廣告插播 ID 做為廣告群組索引，或將 0 做為前置廣告。直播影片不會顯示片尾後廣告。預設值為 -2。如果是隨選影片 (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, ICON_FALLBACK_IMAGE_CLOSED, ICON_FALLBACK_IMAGE_SHOWN, MIDPOINT, PROGRESS, SKIPPABLE_STATE_CHANGED, SKIPPED, START, THIRD_QUARTILE

廣告管理工具觸發的事件。

屬性

名稱	類型	說明
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		廣告播放指標超過第三個四分位時觸發。

返回頁首

Class ima.AdInfo

欄位

adBreakInfo, adDescription, adId, adSystem, adTitle, advertiserName, companions, creativeAdId, creativeId, currentTime, dealId, duration, skipOffset, universalAdIDRegistry, universalAdIDValue, wrappers

方法

createAdInfo

內含廣告相關資訊。由 SDK 傳遞至事件回呼。

屬性

名稱	類型	說明
adBreakInfo		與廣告所屬整個中斷相關的資訊。
adDescription		廣告說明。
adId		廣告 ID，如果不明則為空字串。
adSystem		提供廣告素材的廣告系統。
adTitle		廣告標題。
advertiserName		放送方定義的廣告主名稱。
companions		VAST 回應中指定的隨播廣告。
creativeAdId		廣告的 ISCI (業界標準商業識別碼) 代碼。 這是 VAST 回應中選定廣告素材的 Ad-ID。
creativeId		廣告所選廣告素材的 ID。
currentTime		廣告中的目前時間 (以秒為單位)，如果不明則為 -1。
dealId		傳回目前廣告包裝函式鏈中的第一個交易 ID (從頂端開始)。
duration		這個單一廣告的時間長度 (以秒為單位)，如果不明則為 -1。
skipOffset		廣告可略過的時間，如果不明則為 -1。
universalAdIDRegistry		這個字串用於識別登錄網站的網址，所選廣告素材的通用廣告 ID 會編目於該網站。
universalAdIDValue		廣告所選廣告素材的通用廣告 ID。
wrappers		ima.WrapperInfo 陣列，內含這則廣告的包裝函式資訊。順序為從外層包裝到內層。

createAdInfo()

退貨ima.AdInfo：

返回頁首

Class ima.Companion

欄位

adSlotId, apiFramework, companionClickThrough, creativeType, height, trackingEvents, url, width

方法

createCompanion

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

屬性

名稱	類型	說明
adSlotId		隨播廣告的廣告版位 ID。如果沒有，請留空。
apiFramework		執行這則廣告所需的 API，如果無法使用則為「無效」。
companionClickThrough		隨播廣告的到達網址。
creativeType		代表廣告素材類型，通常是 MIME 類型。
height		隨播廣告的高度 (以像素為單位)。如果無法使用，則為 0。
trackingEvents		追蹤事件的地圖，其中鍵是事件，值則是該事件觸發時要 Ping 的網址清單。
url		這個隨播內容的靜態資源網址。
width		隨播廣告的寬度 (以像素為單位)。如果無法使用，則為 0。

createCompanion()

退貨ima.Companion：

返回頁首

Class ima.CuePoint

欄位

end、 hasPlayed、 start

方法

createCuePoint

內含提示點的相關資訊。

屬性

名稱	類型	說明
end		提示點的結束時間 (以秒為單位)。這會對應到廣告插播。
hasPlayed		布林值，指出提示點是否已播放。
start		提示點的開始時間 (以秒為單位)。這會對應到廣告插播。

createCuePoint()

退貨ima.CuePoint：

返回頁首

類別 ima.Error

欄位

id, info, type

方法

createError

如果發生錯誤，系統會將物件傳遞至錯誤處理常式。

屬性

名稱	類型	說明
id		錯誤的 ID。如需錯誤代碼清單，請參閱 ErrorEvent 常數。
info		錯誤的其他資訊。
type		一律設為「error」，表示這個物件的類型。

createError()

退貨ima.Error：

返回頁首

類別 ima.ErrorEvent

欄位

BAD_STREAM_REQUEST, COULD_NOT_LOAD_STREAM, ERROR, INVALID_RESPONSE, STREAM_API_KEY_NOT_VALID

SDK 可能傳回的所有錯誤。

屬性

名稱	類型	說明
BAD_STREAM_REQUEST		串流要求未正確填入。
COULD_NOT_LOAD_STREAM		無法載入串流。
ERROR		不明錯誤。
INVALID_RESPONSE		伺服器回應無效。
STREAM_API_KEY_NOT_VALID		伺服器不接受提供的 API 金鑰。

返回頁首

Class ima.Player

方法

adBreakEnded、 adBreakStarted、 allVideoComplete、 createPlayer、 loadUrl、 streamInitialized

adBreakEnded(adBreakInfo)

(選用步驟) 廣告插播結束時呼叫。

參數	類型	說明
adBreakInfo	ima.AdBreakInfo	內含廣告插播的相關資訊。

adBreakStarted(adBreakInfo)

(選用步驟) 廣告中斷開始時呼叫。

參數	類型	說明
adBreakInfo	ima.AdBreakInfo	內含廣告插播的相關資訊。

allVideoComplete()

(選用步驟) 所有影片都播放完畢時呼叫。

createPlayer()

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

退貨 ima.Player：

loadUrl(streamInfo)

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

參數	類型	說明
streamInfo	ima.StreamInfo	包含播放內容所需的資訊。

streamInitialized(streamInfo)

在串流初始化時呼叫。

參數	類型	說明
streamInfo	ima.StreamInfo	包含播放內容所需的資訊。

返回頁首

Class ima.StreamFormat

欄位

DASH, HLS

定義串流格式。

屬性

名稱	類型	說明
DASH
HLS

返回頁首

Class ima.StreamInfo

欄位

format、manifest、streamId、streamType、subtitles

方法

createStreamInfo

從 SDK 傳送至播放器的串流相關資訊。

屬性

名稱	類型	說明
format		影片格式：hls 或 dash。 在 ima.StreamFormat 中定義。
manifest		串流的網址。
streamId		串流的專屬 ID。
streamType		影片類型：直播或隨選。 定義於 ima.StreamType。
subtitles		字幕 (如有)。否則為無效。

createStreamInfo()

退貨ima.StreamInfo：

返回頁首

Class ima.StreamManager

方法

addEventListener、 createStreamManager、 enableInteractiveAds、 getContentTime、 getCuePoints、 getPreviousCuePoint、 getStreamTime、 loadThirdPartyStream、 onMessage、 replaceAdTagParameters、 start

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

addEventListener(event, callback)

為指定事件新增監聽器。如要查看支援的事件，請參閱 AdEvents 常數。

參數	類型	說明
event	string
callback	function

createStreamManager(streamRequest, streamInitResponse)

退貨ima.StreamManager：

參數	類型	說明
streamRequest	ima.StreamRequest
streamInitResponse	ima.StreamInitResponse

enableInteractiveAds()

不支援。請改為直接將資料從隨播廣告傳遞至 RAF。這項作業現在已無效。

getContentTime(streamTime)

取得 VOD 串流的時間 (以毫秒為單位)，代表不含廣告的內容時間。詳情請參閱常見問題。 如要取得目前串流時間的內容時間，請傳入 -1。

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

參數	類型	說明
streamTime	Integer	串流中的時間。

getCuePoints()

傳回所有對應廣告插斷的提示點。這項功能僅適用於所有廣告插播時間點都已知的隨選影片內容。所有時間皆以秒為單位，代表串流時間。 如果是 Cloud Stitching API 串流，每個 ima.CuePoint 的 hasPlayed 屬性一律為 false。

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

getPreviousCuePoint(time)

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

傳回 ima.CuePoint：含有開始、結束和 hasPlayed 的物件。如果沒有可用的提示點，則傳回「Invalid」。

參數	類型	說明
time	Float	要查詢的時間，-1 表示目前時間，其他所有串流都會傳回 Invalid。

getStreamTime(contentTime)

從隨選影片的內容時間 (以毫秒為單位) 取得串流時間。詳情請參閱常見問題。

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

參數	類型	說明
contentTime	Integer	內容的時間。

loadThirdPartyStream(streamManifest, streamSubtitle)

載入廣告中繼資料，並使用提供的 streamManifestUrl 和 streamSubtitle 資料呼叫 loadUrl 函式。只有在串流請求類型為 ima.StreamType.POD_VOD 時，這項函式才會運作。

參數	類型	說明
streamManifest	string	已縫合廣告的串流資訊清單網址。
streamSubtitle	ifArray>|Invalid	與串流相關聯的字幕，如果沒有則為 Invalid。

onMessage(msg)

處理來自 Video 物件的所有訊息。 必須針對 roMessagePort 收到的每則訊息呼叫。

參數	類型	說明
msg	object	來自 roVideo 埠的訊息。

replaceAdTagParameters(adTagParameters)

取代近期即將發出的直播廣告請求所使用的所有廣告代碼參數。請注意，這項呼叫不適用於隨選視訊串流。

參數	類型	說明
adTagParameters	string	新的廣告代碼參數。

start()

開始播放串流。

返回頁首

類別 ima.StreamRequest

欄位

adTagParameters, adUiNode, apiKey, assetKey, authToken, contentSourceId, customAssetKey, format, networkCode, player, ppid, streamActivityMonitorId, videoId, videoObject, videoStitcherSessionOptions

方法

createLiveStreamRequest, createPodLiveStreamRequest, createPodVodStreamRequest, createStreamRequest, createVideoStitcherLiveStreamRequest, createVideoStitcherVodStreamRequest, createVideoStitcherVodStreamRequestWithVodConfig, createVodStreamRequest

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

屬性

名稱	類型	說明
adTagParameters		(選用步驟) 您可以在串流請求中覆寫一組有限的廣告代碼參數。詳情請參閱「為串流提供指定目標參數」一文。您也可以使用 dai-ot 和 dai-ov 參數，指定偏好的串流變體。詳情請參閱「覆寫串流變體參數」。
adUiNode		廣告 UI 顯示的場景圖節點。IMA 會在廣告期間，將「為什麼會顯示這則廣告？」和「略過」按鈕等元素放在這個元素上。元素必須疊加在整個影片元素上。
apiKey		(選用步驟) 這些金鑰可用於驗證串流要求。 動態廣告插播驗證金鑰 必須在 DFP 使用者介面中設定。
assetKey		直播影片必須符合這項規定。這項資訊可用於判斷要播放哪個串流。直播串流要求的素材資源金鑰是識別碼，可在 DFP 使用者介面中找到。
authToken		串流要求授權權杖。用來取代 API 金鑰，以進行更嚴格的內容授權。發布者可以根據這個權杖，控管個別內容串流的授權。
contentSourceId		這是隨選串流的必要項目。cmsid 來自 DFP 使用者介面中的 DFP 影片內容來源。
customAssetKey		自訂素材資源金鑰可用於判斷要播放哪個串流。 Pod 放送串流要求必須使用自訂素材資源金鑰。
format		串流格式。預設值為 ima.StreamFormat.HLS。
networkCode		提出串流要求的發布商聯播網代碼。使用 createPodLiveStreamRequest 或 createPodVodStreamRequest 提出廣告連播放送串流要求時，必須提供聯播網代碼。使用 createVideoStitcherLiveStreamRequest、createVideoStitcherVodStreamRequest 或 createVideoStitcherVodStreamRequestWithVodConfig 提出的 Cloud 縫合串流要求，也必須提供這些代碼。這些代碼為選用項目，建議用於透過 createLiveStreamRequest 或 createVodStreamRequest 提出的全方位服務串流要求。加入聯播網代碼會套用在 Ad Manager 使用者介面中選取的設定，例如啟用程式輔助受限制廣告。如果是 Pod 放送和雲端縫合，加入聯播網代碼即可找到並播放串流。如要找出聯播網代碼，請參閱這篇文章。
player		播放器介面的實作項目。
ppid		已淘汰，使用 adTagParameters。 (選用步驟) DFP 目標對象發布商提供的 ID。
streamActivityMonitorId		用於透過串流播放活動監控器偵錯串流的 ID。 發布商可透過這項功能，在串流活動監控工具中輕鬆找到串流記錄。
videoId		這是隨選串流的必要項目。 影片內容來源的 ID。
videoObject		負責在用戶端應用程式上播放影片的影片物件 (例如 Video roSGNode)。系統會輪詢這個物件的各種資料，以便適時觸發 Live HLS ID3 事件。
videoStitcherSessionOptions		工作階段選項可用於為 VideoStitcher streamRequests 設定影片縫合器專屬參數。

createLiveStreamRequest(assetKey, apiKey, networkCode)

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

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

參數	類型	說明
assetKey	string
apiKey	string	指派給傳回 ima.StreamRequest 的 ima.StreamRequest.apiKey 屬性。如果沒有 API 金鑰，請傳遞空白字串。
networkCode	string	提出串流要求的發布商聯播網代碼。網路代碼為選填項目，但建議填寫。

createPodLiveStreamRequest(customAssetKey, networkCode, apiKey)

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

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

參數	類型	說明
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)

初始化 Video Stitcher Live 的必要屬性 StreamRequest。使用此 API 會導致系統忽略任何其他 StreamType 專屬屬性。如果任何必要參數是空字串，系統會記錄錯誤，且 API 會傳回一般 StreamRequest，不會忽略任何屬性。

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

參數	類型	說明
customAssetKey	string
networkCode	string
liveConfigId	string
region	string
projectNumber	string
oAuthToken	string

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

初始化 Video Stitcher VOD StreamRequest 的必要屬性。使用此 API 會導致系統忽略任何其他 StreamType 專屬屬性。如果任何必要參數是空字串，系統會記錄錯誤，且 API 會傳回一般 StreamRequest，不會忽略任何屬性。

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

參數	類型	說明
adTagUrl	string
networkCode	string
contentSourceUrl	string
region	string
projectNumber	string
oAuthToken	string

createVideoStitcherVodStreamRequestWithVodConfig(vodConfigId, networkCode, region, projectNumber, oAuthToken)

使用從 Cloud Video Stitcher 建立的 vodConfigId，初始化 Video Stitcher VOD StreamRequest 的必要屬性。使用此 API 會導致系統忽略任何其他 StreamType 專屬屬性。如果任何必要參數是空字串，系統會記錄錯誤，且 API 會傳回一般 StreamRequest，不會忽略任何屬性。

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

參數	類型	說明
vodConfigId	string
networkCode	string
region	string
projectNumber	string
oAuthToken	string

createVodStreamRequest(contentSourceId, videoId, apiKey, networkCode)

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

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

參數	類型	說明
contentSourceId	string
videoId	string
apiKey	string	指派給傳回 ima.StreamRequest 的 ima.StreamRequest.apiKey 屬性。如果沒有 API 金鑰，請傳遞空白字串。
networkCode	string	提出串流要求的發布商聯播網代碼。網路代碼為選填項目，但建議填寫。

返回頁首

Class ima.StreamType

欄位

LIVE, VOD

定義播放器要求播放的串流類型。 前置廣告和隨選影片應從串流的開頭播放。

屬性

名稱	類型	說明
LIVE		影片已上線。
VOD		影片為隨選影片。

返回頁首

類別 ima.WrapperInfo

欄位

adId, adSystem, creativeAdId, creativeId, dealId

方法

createWrapperInfo

內含包裝函式的相關資訊。

屬性

名稱	類型	說明
adId		廣告 ID，如果不明則為空字串。
adSystem		廣告系統的宣告名稱，如果不明則為空字串。
creativeAdId		廣告素材上的廣告 ID，如果不明則為空字串。
creativeId		廣告素材的 ID，或未知時為空字串。
dealId		交易 ID，或不明時為空字串。

createWrapperInfo()

退貨ima.WrapperInfo：

返回頁首