适用于 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

返回页首

Class ima.AdBreakInfo

字段

adPosition、duration、podIndex、timeOffset、totalAds

方法

createAdBreakInfo

包含有关广告插播的信息。由 SDK 传递给事件回调。

属性

名称	类型	说明
adPosition		广告在广告插播时段中的索引。对于独立广告，该指数为 1。
duration		插播时长的上限（以秒为单位），如果未知，则为 -1。
podIndex		对于直播，返回插播时间点 ID 作为广告连播指数，或返回 0（如果是前贴片广告）。直播中没有后贴片广告。默认值为 -2。对于视频点播 (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、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		在广告播放头到达第三个四分位时触发。

返回页首

类 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：

返回页首

类 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

包含有关 Cue 点的信息。

属性

名称	类型	说明
end		广告插播点的结束时间（以秒为单位）。这对应于广告插播时间点。
hasPlayed		一个布尔值，用于指示相应 Cue 点是否已播放。
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

字段

格式、清单、streamId、streamType、字幕

方法

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：包含 start、end 和 hasPlayed 的对象。如果没有可用的提示点，则返回 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)

处理来自视频对象的所有消息。 必须针对在 roMessagePort 上收到的每条消息进行调用。

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

replaceAdTagParameters(adTagParameters)

替换即将针对直播视频流发出的广告请求使用的所有广告代码参数。请注意，此调用对于 VOD 流是空操作。

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

start()

开始播放数据流。

返回页首

Class 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		展示广告界面的场景图节点。IMA 会在广告播放期间将“为什么显示此广告”和“跳过”按钮等元素放置在此元素上。元素必须覆盖整个视频元素。
apiKey		可选。这些密钥可用于对视频流请求进行身份验证。 必须在 DFP 界面中设置 DAI 身份验证密钥。
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 受众群体发布商提供的标识符。
streamActivityMonitorId		用于通过视频流活动监控工具调试视频流的 ID。 此参数用于提供一种便捷的方式，让发布商能够在直播活动监控工具中找到直播日志。
videoId		对于点播流是必需的。 视频内容来源的标识符。
videoObject		负责在客户端应用上播放视频的视频对象（例如 Video roSGNode）。系统将轮询此对象以获取各种数据，从而正确安排实时 HLS ID3 事件的时间。
videoStitcherSessionOptions		会话选项用于为 VideoStitcher streamRequests 设置视频拼接器专用参数。

createLiveStreamRequest(assetKey, apiKey, networkCode)

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

返回具有必需的 Live 属性的 ima.StreamRequest： 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)

初始化 ima.StreamRequest 的必需属性，以便在使用 DAI Pod 服务和第三方视频拼接器时注册 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)

初始化视频拼接器实时 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)

初始化视频拼接器 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 初始化视频拼接器 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，而不会忽略任何属性。

返回包含必需 VOD 属性的 ima.StreamRequest ima.StreamRequest 对象。

参数	类型	说明
contentSourceId	string
videoId	string
apiKey	string	分配给返回的 ima.StreamRequest 的 ima.StreamRequest.apiKey 属性的形参。如果不存在 API 密钥，则传递一个空字符串。
networkCode	string	发出视频流请求的发布商的广告资源网代码。您可以选择是否添加广告资源网代码，但我们建议您添加。

返回页首

类 ima.StreamType

字段

直播、 视频点播

定义播放器要播放的流的类型。 前贴片广告和 VOD 应从视频流的开头开始播放。

属性

名称	类型	说明
LIVE		视频已发布。
VOD		视频可供点播观看。

返回页首

类 ima.WrapperInfo

字段

adId、 adSystem、 creativeAdId、 creativeId、 dealId

方法

createWrapperInfo

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

属性

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

createWrapperInfo()

返回值 ima.WrapperInfo：

返回页首