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

方法

disableLogging、getStreamManager、initSdk、requestStream

控制 IMA SDK 的全域函式。

disableLogging()

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

getStreamManager()

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

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

initSdk(settings)

初始化 SDK。

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

requestStream(streamRequest)

開始非同步串流要求。呼叫此方法後，控制權會立即傳回至播放器。

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

參數	類型	說明
streamRequest	object

返回頁首

類別 ima.AdBreakInfo

欄位

adPosition、duration、podIndex、timeOffset、totalAds

方法

createAdBreakInfo

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

屬性

名稱	類型	說明
adPosition		廣告插播中的廣告索引。獨立廣告的索引為 1。
duration		廣告插播的時間長度上限 (以秒為單位)，如果未知則為 -1。
podIndex		如果是直播，系統會傳回廣告插播 ID 做為 Pod 索引，如果是前置廣告，則會傳回 0。直播影片不會顯示後置廣告。預設值為 -2。如果是隨選影片 (VOD)，則會傳回廣告連播的索引。如果是前置廣告連播，則會傳回 0。對於片中廣告，會傳回 1、2、...、n。對於片尾廣告連播，會傳回 n+1...n+x。如果這則廣告不是廣告連播的一部分，或這個廣告連播不是播放清單的一部分，則預設為 0。
timeOffset		廣告連播在內容中的秒數位置。片頭廣告會傳回 0、片尾廣告會傳回 -1，而片中廣告會傳回廣告單元預定的時間。
totalAds		這個廣告插播中包含的廣告總數。獨立廣告的值為 1。

createAdBreakInfo()

傳回 ima.AdBreakInfo：

返回頁首

Class 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 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

欄位

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		用於識別註冊網站的網址，該網站會將所選廣告素材的 Universal Ad ID 編入目錄。
universalAdIDValue		廣告所選廣告素材的通用廣告 ID。
wrappers		這個廣告的包裝函式資訊，為 ima.WrapperInfo 陣列。順序為從外包裝函式到內包裝函式。

createAdInfo()

傳回 ima.AdInfo：

返回頁首

類別 ima.Companion

欄位

apiFramework、creativeType、height、trackingEvents、url、width

方法

createCompanion

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

屬性

名稱	類型	說明
apiFramework		執行這則廣告所需的 API，如果無法使用，則為「Invalid」。
creativeType		代表廣告素材類型，通常為 MIME 類型。
height		隨播廣告的高度 (以像素為單位)。如無法使用，則為 0。
trackingEvents		追蹤事件對應表，其中鍵為事件，值則是事件的 ping 網址清單。
url		這個隨播影片的靜態資源網址。
width		隨播廣告的寬度 (以像素為單位)。如無法使用，則為 0。

createCompanion()

傳回 ima.Companion：

返回頁首

類別 ima.CuePoint

欄位

end、hasPlayed、start

方法

createCuePoint

包含提示點的相關資訊。

屬性

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

createCuePoint()

傳回 ima.CuePoint：

返回頁首

類別 ima.Error

欄位

id、info、type

方法

createError

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

屬性

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

createError()

傳回 ima.Error：

返回頁首

Class 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 金鑰。

返回頁首

類別 ima.Player

方法

adBreakEnded、adBreakStarted、allVideoComplete、createPlayer、loadUrl

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

定義串流的格式。

屬性

名稱	類型	說明
DASH
HLS

返回頁首

類別 ima.StreamInfo

欄位

format、manifest、streamId、streamType、subtitles

方法

createStreamInfo

從 SDK 傳遞至播放器的串流資訊。

屬性

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

createStreamInfo()

傳回 ima.StreamInfo：

返回頁首

類別 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：包含開始、結束和已播放的物件。如果沒有可用的提示點，則會傳回「Invalid」。

參數	類型	說明
time	Float	查詢時間，-1 表示目前時間，並傳回 Invalid 以供所有其他串流使用。

getStreamTime(contentTime)

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

傳回 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)

取代所有即將用於直播廣告請求的廣告代碼參數。請注意，這項呼叫對 VOD 串流而言是無操作。

參數	類型	說明
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 UI 中設定 動態廣告插播驗證金鑰。
assetKey		直播必須使用此參數。用來判斷應播放哪個串流。直播串流要求的素材資源金鑰是 DFP 使用者介面中的識別碼。
authToken		串流要求授權權杖。可取代 API 金鑰，提供更嚴格的內容授權。發布商可以根據這組符記，控管個別內容串流授權。
contentSourceId		如要提供隨選串流，必須填寫這項資訊。cmsid 來自 DFP 使用者介面中的 DFP 影片內容來源。
customAssetKey		自訂素材資源金鑰可用於判斷應播放哪個串流。您必須提供自訂素材資源金鑰，才能使用 Pod 服務串流要求。
format		串流格式。預設值為 ima.StreamFormat.HLS。
networkCode		發布商提出串流要求的聯播網代碼。使用 createPodLiveStreamRequest 或 createPodVodStreamRequest 建立的 Pod 串流要求必須使用網路代碼。使用 createVideoStitcherLiveStreamRequest、createVideoStitcherVodStreamRequest 或 createVideoStitcherVodStreamRequestWithVodConfig 建立的 Cloud Stitching 串流要求也需要這些程式碼。這些代碼為選用項目，建議用於透過 createLiveStreamRequest 或 createVodStreamRequest 提出的全方位服務串流要求。加入聯播網程式碼會套用 Ad Manager UI 中選取的設定，例如啟用程式輔助限制廣告。針對 Pod 服務和 Cloud 拼接，新增網路代碼可定位及播放串流。如要找出聯播網代碼，請參閱這篇文章。
player		影片播放器介面的實作項目。
ppid		已淘汰，使用 adTagParameters。選用設定。DFP 目標對象的發布商提供的 ID。
streamActivityMonitorId		用於透過串流活動監控器偵錯串流的 ID。這項功能可讓發布商在串流活動監控工具中輕鬆找到串流記錄。
videoId		如要提供隨選串流，必須填寫這個值。影片內容來源的 ID。
videoObject		負責在用戶端應用程式上播放影片的影片物件 (例如 Video roSGNode)。系統會對這個物件進行輪詢，以便在適當安排 Live HLS ID3 事件時使用各種資料。
videoStitcherSessionOptions		工作階段選項可用於為 VideoStitcher 串流要求設定影片拼接器專屬參數。

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)

使用由雲端影片拼接工具建立的 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		影片為隨選影片。

返回頁首

類別 ima.WrapperInfo

欄位

adId、adSystem、creativeAdId、creativeId、dealId

方法

createWrapperInfo

包含包裝函式相關資訊。

屬性

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

createWrapperInfo()

傳回 ima.WrapperInfo：

返回頁首