Google IMA Roku SDK API

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.封装容器信息

ima

方法

disableLogging、getStreamManager、initSdk、requestStream

控制 IMA SDK 的全局函数。

disableLogging()

停用 SDK 日志记录。日志记录功能默认处于开启状态。

getStreamManager()

返回流管理器（如果有）。 如果数据流管理器不可用，则返回无效。 如果创建流管理器时出错，则返回错误对象。

返回 object：数据流管理器或错误对象。

initSdk()

初始化 SDK。

requestStream(streamRequest)

启动异步数据流请求。调用此方法后，控件会立即返回播放器。

返回 object：一个错误，如果没有错误，则无效

参数	类型	说明
streamRequest	object

返回页首

ima.AdBreakInfo 类

字段

adPosition、duration、podIndex、timeOffset、totalAds

方法

createAdBreakInfo

包含广告插播时间点的相关信息。由 SDK 传递给事件回调函数。

属性

名称	类型	说明
adPosition		广告插播时间点中的广告的索引。对于独立广告，该值为 1。
duration		广告插播时长上限（以秒为单位），如果未知，则为 -1。
podIndex		对于直播，始终返回 -1。对于视频点播 (VOD)，返回广告连播的索引。对于前贴片广告 Pod，则返回 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、7% 8%

广告管理器触发的事件。

属性

名称	类型	说明
AD_PERIOD_ENDED		每次视频流从广告或可选广告切换到内容时触发。 即使第二次播放广告或跳转到一个广告，也会触发此事件。
AD_PERIOD_STARTED		每次视频流从内容切换为广告或可选广告时都会触发。 即使第二次播放广告或跳转到一个广告，也会触发此事件。
COMPLETE		在广告播放完毕时触发。
ERROR		出错时触发。
FIRST_QUARTILE		在广告的进度条指针已过第一个四分位时触发。
MIDPOINT		在广告的进度条指针已过中点时触发。
PROGRESS		在广告进度更新时触发。
SKIPPABLE_STATE_CHANGED		在广告可跳过状态发生更改时触发。
SKIPPED		在用户跳过广告时触发。
START		在广告开始播放时触发。
THIRD_QUARTILE		在广告的进度条指针已过第三个四分位时触发。

返回页首

ima.AdInfo 类

字段

adBreakInfo、adDescription、adId、adSystem、adTitle、广告客户名称、companions、currentTime、duration、UniversalAdIDRegistry

方法

createAdInfo

包含某个广告的相关信息。由 SDK 传递给事件回调函数。

属性

名称	类型	说明
adBreakInfo		与此广告所属的整个广告插播时间点相关的信息。
adDescription		广告内容描述。
adId		广告的 ID，如果未知，则为空字符串。
adSystem		提供广告素材的广告系统。
adTitle		广告的标题。
advertiserName		投放方定义的广告客户名称。
companions		在 VAST 响应中指定的随播广告。
currentTime		广告中的当前时间（以秒为单位），如果未知，则为 -1。
duration		该单个广告的持续时间（以秒为单位），如果未知，则为 -1。
universalAdIDRegistry		这是一个字符串，用于标识为所选广告素材的通用广告 ID 编制的注册表网站的网址。
universalAdIDValue		广告的选定广告素材的通用广告 ID。
wrappers		一组 ima.封装容器 Info，其中包含该广告的封装容器信息。顺序为从外层封装容器到内层。

createAdInfo()

返回 ima.AdInfo：

返回页首

ima.Companion 类

字段

apiFramework、creativeType、height、trackingEvents、url、width

方法

createCompanion

包含广告随播广告的相关信息。

属性

名称	类型	说明
apiFramework		执行此广告所需的 API；如果不可用，则为无效。
creativeType		表示广告素材类型，通常为 MIME 类型。
height		随播广告的高度（以像素为单位）。0（如果不可用）。
trackingEvents		跟踪事件的映射，其中键为事件，值为针对该事件执行 ping 操作的网址列表。
url		此随播广告素材的静态资源的网址。
width		随播广告的宽度（以像素为单位）。0（如果不可用）。

createCompanion()

返回 ima.Companion：

返回页首

ima.CuePoint

字段

end、hasPlayed、start

方法

createCuePoint

包含与广告插入点相关的信息。

属性

名称	类型	说明
end		广告插入点的结束时间（以秒为单位）。对应于广告插播时间点。
hasPlayed		指示广告插入点已播放的布尔值。
start		广告插入点的开始时间（以秒为单位）。对应于广告插播时间点。

createCuePoint()

返回 ima.CuePoint：

返回页首

ima.Error 类

字段

id、info、type

方法

createError

出现错误时传递给错误处理程序的对象。

属性

名称	类型	说明
id		错误的 ID。如需查看错误代码列表，请参阅 ErrorEvent 常量。
info		有关错误的其他信息。
type		始终设置为“错误”，以指示此对象的类型。

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 密钥。

返回页首

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 或短划线。在 ima.StreamFormat 中定义。
manifest		数据流的网址。
streamId		数据流的唯一 ID。
streamType		视频类型：直播或点播。 在 ima.StreamType 中定义。
subtitles		字幕（如果有）。如果不是，则无效。

createStreamInfo()

返回 ima.StreamInfo：

返回页首

ima.StreamManager 类

方法

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

用于管理流播放的对象。

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/interactive-media-ads/docs/sdks/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/interactive-media-ads/docs/sdks/roku/faq

返回 Integer：与指定内容时间对应的流时间。

参数	类型	说明
contentTime	Integer	内容的时间。

onMessage(msg)

处理来自 Video 对象的所有消息。必须为 roMessagePort 收到的每条消息调用该方法。

参数	类型	说明
msg	object	来自 roVideo 端口的消息。

replaceAdTagParameters(adTagParameters)

替换所有代码参数，以用于即将进行的直播广告请求。请注意，此调用对于 VOD 视频流是一项空操作。

参数	类型	说明
adTagParameters	string	新的广告代码参数。

start()

开始播放流。

返回页首

ima.StreamRequest 类

字段

adTagParameters、adUiNode、apiKey、assetKey、authToken、contentSourceId、customAssetKey、format、networkCode、stream、、

方法

createLiveStreamRequest、createPodLiveStreamRequest、createStreamRequest、createVodStreamRequest

用于指定流请求的属性。

属性

名称	类型	说明
adTagParameters		（可选）您可以在视频流请求中替换一组数量有限的广告代码参数。 向您的视频流提供定位参数可了解详情。您还可以使用 dai-ot 和 dai-ov 参数指定视频流变体偏好设置。如需了解详情，请参阅替换数据流变体参数。
adUiNode		显示广告界面的场景图节点。IMA 会在广告播放期间在此元素上放置为什么显示该广告和跳过按钮等元素。该元素必须覆盖整个视频元素。
apiKey		（可选）这些密钥可用于验证数据流请求。 必须在 DFP 界面中设置 DAI 身份验证密钥。
assetKey		直播需要。这用于确定应该播放哪个流。直播请求素材资源键是一种标识符，可以在 DFP 界面中找到。
authToken		数据流请求授权令牌。用于替代 API 密钥（用于进行更严格的内容授权）。发布者可以根据此令牌控制各个内容流授权。
contentSourceId		对于按需直播是必需的。cmsid 来自 DFP 界面中的 DFP 视频内容来源。
customAssetKey		自定义资源键用于确定应播放哪个视频流。Pod 传送流请求需要自定义资产键。
format		数据流的格式。默认为 ima.StreamFormat.HLS。
networkCode		发出视频流请求的发布商的广告联盟代码。Pod 处理流请求需要输入网络代码。
player		播放器接口的实现。
ppid		已弃用。使用 adTagParameters。（可选）DFP 受众群体发布商提供的标识符。
streamActivityMonitorId		用于通过数据流活动监控工具调试数据流的 ID。 通过这种便捷方式，发布商可在数据流活动监控工具中找到数据流日志。
videoId		对于按需直播是必需的。视频内容来源的标识符。
videoObject		负责在客户端应用上播放视频的视频对象（如视频 roSGNode）。系统将轮询此对象，以获取用于正确计时 Live HLS ID3 事件的各种数据。

createLiveStreamRequest(assetKey, apiKey)

初始化实时 StreamRequest 的必要属性。使用此 API 会导致忽略任何其他特定于 StreamType 的属性。如果任何必需参数为空字符串，则会发生错误记录，并且 API 会返回一个通用 StreamRequest，并且不会忽略任何属性。

返回 ima.StreamRequest: ima.StreamRequest 对象，其中包含必需的实时属性。

参数	类型	说明
assetKey	string
apiKey	string	将分配给返回的 StreamRequest 的 apiKey 属性的可选参数；默认为空字符串。

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 属性的可选参数；默认为空字符串。

createStreamRequest()

返回 ima.StreamRequest：空 ima.StreamRequest 对象。

createVodStreamRequest(contentSourceId, videoId, apiKey)

初始化 VOD ima.StreamRequest 的必要属性。使用此 API 会导致忽略任何其他特定于 ima.StreamType 的属性。如果任何必需参数为空字符串，则会发生错误记录，并且 API 会返回一个通用 StreamRequest，并且不会忽略任何属性。

返回 ima.StreamRequest：具有所需 VOD 属性的 ima.StreamRequest 对象。

参数	类型	说明
contentSourceId	string
videoId	string
apiKey	string	将分配给返回的 ima.StreamRequest 的 ima.StreamRequest.apiKey 属性的可选参数；默认为空字符串。

返回页首

ima.StreamType 类

字段

直播、VOD

定义播放器要播放的流的类型。 前贴片广告和 VOD 应在直播开始时播放。

属性

名称	类型	说明
LIVE		视频已上线。
VOD		视频点播。

返回页首

ima.封装容器 Info 类

字段

adId、adSystem、creativeAdId、creativeId、dealId

方法

create 封装容器 Info

包含封装容器的相关信息。

属性

名称	类型	说明
adId		广告的 ID，如果未知，则为空字符串。
adSystem		广告系统声明的名称；如果未知，则为空字符串。
creativeAdId		广告素材中的广告 ID 或未知字符串（如果未知）。
creativeId		广告素材的 ID；如果未知，则为空字符串。
dealId		交易 ID；如果未知，则为空字符串。

createWrapperInfo()

返回 ima.WrapperInfo：

返回页首