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

返回数据流管理器（如果有）。 如果流管理器尚不可用，则返回“无效”。 如果创建数据流管理器时出错，系统会返回一个错误对象。

返回 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 作为广告连播索引；对于前贴片广告，返回 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		在广告播放头超出第三四分位时触发。

返回页首

类 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

字段

apiFramework, creativeType, height, trackingEvents, url, width

方法

createCompanion

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

属性

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

createCompanion()

返回 ima.Companion：

返回页首

类 ima.CuePoint

字段

end、hasPlayed、start

方法

createCuePoint

包含有关 cue 点的信息。

属性

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

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

返回页首

类 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()

返回与所有广告插播时间点对应的所有 cue 点。此字段仅适用于所有广告插播时间点均已知晓的视频点播内容。所有时间均表示以秒为单位的直播时间。 对于 Cloud Stitching API 串流，每个 ima.CuePoint 的 hasPlayed 属性始终为 false。

返回 Object：包含所有 cue 点的数组。

getPreviousCuePoint(time)

返回此时间之前的 cue 点。cue 点表示广告插播时间点。所有时间均表示以秒为单位的直播时间。

返回 ima.CuePoint：包含 start、end 和 hasPlayed 的对象。如果没有可用的 cue 点，则返回“无效”。

参数	类型	说明
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		用于显示广告界面的场景图节点。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 投放和 Cloud 拼接，添加网络代码可定位和播放直播。如需查找广告资源网代码，请参阅这篇文章。
player		播放器接口的实现。
ppid		已弃用。使用 adTagParameters。 可选。DFP 受众群体的发布商提供的标识符。
streamActivityMonitorId		用于使用视频流活动监控工具调试视频流的 ID。 这是为了让发布商能够以便捷的方式在直播活动监控工具中查找直播日志。
videoId		对于点播串流，此字段为必填字段。视频内容来源的标识符。
videoObject		负责在客户端应用中播放视频的视频对象（例如 Video roSGNode）。系统会轮询此对象以获取各种数据，以便在正确的时间触发直播 HLS ID3 事件。
videoStitcherSessionOptions		会话选项用于为 VideoStitcher streamRequests 设置视频拼接工具专用参数。

createLiveStreamRequest(assetKey, apiKey, networkCode)

初始化实时 StreamRequest 的必需属性。使用此 API 会导致忽略任何其他 StreamType 专用属性。如果任何必需参数为空字符串，系统会进行错误日志记录，并且 API 会返回一个通用 StreamRequest，而不会忽略任何属性。

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

参数	类型	说明
assetKey	string
apiKey	string	分配给返回的 ima.StreamRequest 的 ima.StreamRequest.apiKey 属性的参数。如果没有 API 密钥，请传递空字符串。
networkCode	string	发出串流请求的发布商的广告资源网代码。添加影音平台代码并非强制要求，但我们建议您这样做。

createPodLiveStreamRequest(customAssetKey, networkCode, apiKey)

初始化 Pod 实时 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)

初始化视频拼接器实时 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 初始化视频拼接器 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	发出串流请求的发布商的广告资源网代码。添加影音平台代码并非强制要求，但我们建议您这样做。

返回页首

类 ima.StreamType

字段

直播、视频点播

定义系统要求播放器播放的串流类型。前贴片广告和视频点播应从直播开始播放。

属性

名称	类型	说明
LIVE		视频已发布。
VOD		该视频是点播视频。

返回页首

类 ima.WrapperInfo

字段

adId、adSystem、creativeAdId、creativeId、dealId

方法

createWrapperInfo

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

属性

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

createWrapperInfo()

返回 ima.WrapperInfo：

返回页首