ima 类
方法
用于控制 IMA SDK 的全局函数。
disableLogging()
停用 SDK 日志记录。Logging 默认处于开启状态。
getStreamManager()
返回一个数据流管理器(如果有)。
如果数据流管理器尚不可用,则返回 Invalid。
如果创建流管理器时出错,系统会返回错误对象。
返回 object
:数据流管理器或错误对象。
initSdk(settings)
初始化 SDK。
参数 | 类型 | 说明 |
---|---|---|
settings |
object |
可选的 IMA 设置对象。 |
requestStream(streamRequest)
启动异步流请求。调用此方法后,Control 会立即返回到播放器。
返回 object
:一个错误,如果没有错误,
参数 | 类型 | 说明 |
---|---|---|
streamRequest |
object |
ima.AdBreakInfo 类
字段
方法
包含有关广告插播时间点的信息。由 SDK 传递给事件回调函数。
属性
名称 | 类型 | 说明 |
---|---|---|
adPosition |
|
广告插播时间点中广告的索引。如果是独立广告,则为 1。 |
duration |
|
广告插播时长上限(以秒为单位),如果未知,则为 -1。 |
podIndex |
|
对于直播,始终返回 -1。对于视频点播 (VOD),返回广告连播的索引。对于前贴片广告连播,返回 0。对于中贴片广告,会返回 1、2、...、n。对于后贴片广告连播,返回 n+1...n+x。如果此广告不属于广告连播,或者该广告连播不属于播放列表,则默认值为 0。 |
timeOffset |
|
广告连播在内容中的位置(以秒为单位)。 前贴片广告返回 0,后贴片广告返回 -1,中贴片广告返回 Pod 的预定时间。 |
totalAds |
|
此广告插播时间点中包含的广告总数。 如果是独立广告,则为 1。 |
createAdBreakInfo()
返回 ima.AdBreakInfo
:
ima.AdEvent 类
字段
由广告管理器触发的事件。
属性
名称 | 类型 | 说明 |
---|---|---|
AD_PERIOD_ENDED |
|
每当视频流从广告或可选广告切换到内容时触发。 即使广告第二次播放或跳转至相应广告时,也会触发此行为。 |
AD_PERIOD_STARTED |
|
每当视频流从内容切换到广告或可选广告时触发。 即使广告第二次播放或跳转至相应广告时,也会触发此行为。 |
COMPLETE |
|
在广告播放完毕时触发。 |
ERROR |
|
发生错误时触发。 |
FIRST_QUARTILE |
|
在广告的进度条指针已过第一个四分位时触发。 |
MIDPOINT |
|
在广告的进度条指针已过中点时触发。 |
PROGRESS |
|
在广告播放进度有更新时触发。 |
SKIPPABLE_STATE_CHANGED |
|
在广告的可跳过状态发生变化时触发。 |
SKIPPED |
|
在用户跳过广告时触发。 |
START |
|
在广告开始播放时触发。 |
THIRD_QUARTILE |
|
在广告的进度条指针已过第三个四分位时触发。 |
ima.AdInfo 类
字段
方法
包含广告的相关信息。由 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 |
|
执行此广告所需的 API,如果不可用,则为无效 API。 |
creativeType |
|
表示广告素材类型,通常是 MIME 类型。 |
height |
|
随播广告的高度(以像素为单位)。如果不可用,则为 0。 |
trackingEvents |
|
跟踪事件的映射,其中键为事件,其值为要在该事件发生时执行 ping 操作的网址列表。 |
url |
|
此随播广告素材的静态资源的网址。 |
width |
|
随播广告的宽度(以像素为单位)。如果不可用,则为 0。 |
createCompanion()
返回 ima.Companion
:
ima.CuePoint 类
字段
方法
包含有关广告插入点的信息。
属性
名称 | 类型 | 说明 |
---|---|---|
end |
|
广告插入点的结束时间(以秒为单位)。对应于广告插播时间点。 |
hasPlayed |
|
指示广告插入点已播放的布尔值。 |
start |
|
广告插入点的开始时间(以秒为单位)。对应于广告插播时间点。 |
createCuePoint()
返回 ima.CuePoint
:
ima.Error 类
字段
方法
发生错误时,传递给错误处理程序的对象。
属性
名称 | 类型 | 说明 |
---|---|---|
id |
|
错误的 ID。有关错误代码列表,请参阅 ErrorEvent 常量。 |
info |
|
有关错误的更多信息。 |
type |
|
始终设置为“error”,以指明此对象的类型。 |
createError()
返回 ima.Error
:
ima.ErrorEvent 类
字段
SDK 可能发回的所有错误。
属性
名称 | 类型 | 说明 |
---|---|---|
BAD_STREAM_REQUEST |
|
视频流请求未正确填充。 |
COULD_NOT_LOAD_STREAM |
|
无法加载信息流。 |
ERROR |
|
未知错误。 |
INVALID_RESPONSE |
|
服务器响应无效。 |
STREAM_API_KEY_NOT_VALID |
|
服务器不接受所提供的 API 密钥。 |
ima.Player 类
方法
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 |
|
ima.StreamInfo 类
字段
方法
从 SDK 传递到播放器的关于视频流的信息。
属性
名称 | 类型 | 说明 |
---|---|---|
format |
|
视频的格式:hls 或短划线。 在 ima.StreamFormat 中定义。 |
manifest |
|
数据流的网址。 |
streamId |
|
数据流的唯一 ID。 |
streamType |
|
视频类型:直播或点播。 在 ima.StreamType 中定义。 |
subtitles |
|
字幕(如果有)。如果不是,则无效。 |
createStreamInfo()
返回 ima.StreamInfo
:
ima.StreamManager 类
方法
用于管理流播放的对象。
addEventListener(event, callback)
为指定事件添加监听器。如需了解支持的事件,请参阅 AdEvents 常量。
参数 | 类型 | 说明 |
---|---|---|
event |
string |
|
callback |
function |
createStreamManager(streamRequest, streamInitResponse)
参数 | 类型 | 说明 |
---|---|---|
streamRequest |
ima.StreamRequest |
|
streamInitResponse |
ima.StreamInitResponse |
enableInteractiveAds()
不支持。而是直接将数据从随播广告传递到 RAF。
此操作现在可执行空操作。
getContentTime(streamTime)
获取 VOD 流的时间(以毫秒为单位),表示内容中没有广告的时间。
请参阅:https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/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/ad-manager/dynamic-ad-insertion/sdk/roku/faq
返回 Integer
:与指定内容时间对应的在线播放时间。
参数 | 类型 | 说明 |
---|---|---|
contentTime |
Integer |
内容的时间。 |
loadThirdPartyStream(streamManifest, streamSubtitle)
加载广告元数据,并使用提供的 streamManifestUrl
和 streamSubtitle
数据调用 loadUrl
函数。此函数仅在流请求类型为 ima.StreamType.POD_VOD
时有效。
参数 | 类型 | 说明 |
---|---|---|
streamManifest |
string |
拼接广告的视频流清单网址。 |
streamSubtitle |
ifArray |
字幕与视频流相关联,如果没有,则为 |
onMessage(msg)
处理来自 Video 对象的所有消息。
对于通过 roMessagePort 收到的每条消息,都必须调用该方法。
参数 | 类型 | 说明 |
---|---|---|
msg |
object |
来自 roVideo 端口的消息。 |
replaceAdTagParameters(adTagParameters)
替换所有广告代码参数,这些参数将用于直播活动的后续广告请求。请注意,此调用在 VOD 视频流中是空操作。
参数 | 类型 | 说明 |
---|---|---|
adTagParameters |
string |
新的广告代码参数。 |
start()
开始播放流。
ima.StreamRequest 类
字段
方法
用于指定流请求的属性。
属性
名称 | 类型 | 说明 |
---|---|---|
adTagParameters |
|
可选。您可以在视频流请求中替换一组有限的广告代码参数。如需了解更多信息,请参阅向数据流提供定位参数。您还可以使用 dai-ot 和 dai-ov 参数设置数据流变体偏好设置。如需了解详情,请参阅替换数据流变体参数。 |
adUiNode |
|
显示广告界面的场景图节点。IMA 会在广告展示期间在此元素上放置为什么显示该广告和跳过按钮等元素。该元素必须覆盖整个视频元素。 |
apiKey |
|
可选。这些密钥可用于对视频流请求进行身份验证。必须在 DFP 界面中设置 DAI 身份验证密钥。 |
assetKey |
|
直播必填。这用于确定应播放哪个数据流。直播请求素材资源键是一种标识符,可在 DFP 界面中找到。 |
authToken |
|
流请求授权令牌。用于代替 API 密钥,用于实现更严格的内容授权。发布商可以根据此令牌控制各个内容流的授权。 |
contentSourceId |
|
对于按需直播是必需的。cmsid 来自 DFP 界面中的 DFP 视频内容来源。 |
customAssetKey |
|
自定义素材资源键用于确定应播放哪个视频流。必须为广告连播投放数据流请求提供自定义资产键。 |
format |
|
数据流的格式。默认为 |
networkCode |
|
发出视频流请求的发布商的广告联盟代码。对于 Pod 传送流请求,必须提供网络代码。 |
player |
|
播放器接口的实现。 |
ppid |
|
已弃用。使用 adTagParameters。 可选。DFP 受众群体由发布商提供的标识符。 |
streamActivityMonitorId |
|
要通过数据流活动监控工具调试视频流的 ID。 用于为发布商提供便捷的方式,让他们能够在信息流活动监控工具中查找流日志。 |
videoId |
|
对于按需直播为必需项。视频内容来源的标识符。 |
videoObject |
|
在客户端应用上负责播放视频的视频对象(例如 Video roSGNode)。系统将轮询此对象以获取用于正确设置 Live HLS ID3 事件计时的各种数据。 |
createLiveStreamRequest(assetKey, apiKey)
初始化实时 StreamRequest
的必需属性。使用此 API 会导致系统忽略任何其他特定于 StreamType
的属性。
如果任何必需参数是空字符串,则会发生错误日志记录,并且 API 会返回一个通用 StreamRequest
,不忽略任何属性。
返回 ima.StreamRequest
:具有所需 Live 属性的 ima.StreamRequest
对象。
参数 | 类型 | 说明 |
---|---|---|
assetKey |
string |
|
apiKey |
string |
可选参数,将分配给返回的 |
createPodLiveStreamRequest(customAssetKey, networkCode, apiKey)
初始化 Pod Live ima.StreamRequest
的必需属性。使用此 API 会导致系统忽略任何其他特定于 ima.StreamType
的属性。
如果任何必需参数是空字符串,则会发生错误日志记录,并且 API 会返回一个通用 StreamRequest
,不忽略任何属性。
返回 StreamRequest
:具有所需 PodLive 属性的 ima.StreamRequest
对象。
参数 | 类型 | 说明 |
---|---|---|
customAssetKey |
string |
|
networkCode |
string |
|
apiKey |
string |
可选参数,将分配给返回的 |
createPodVodStreamRequest(networkCode)
将 DAI Pod 传送与第三方视频拼接器结合使用时,初始化用于注册 VOD 流的 ima.StreamRequest
的必需属性。此函数将请求类型设置为 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)
初始化视频拼接器 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)
初始化视频拼接器 VOD StreamRequest
的必需属性。使用此 API 会导致系统忽略任何其他特定于 StreamType
的属性。如果任何必需参数是空字符串,则会发生错误日志记录,并且 API 会返回一个通用 StreamRequest
,不忽略任何属性。
返回 ima.StreamRequest
:具有所需 VideoStitcherVod 属性的 ima.StreamRequest
对象。
参数 | 类型 | 说明 |
---|---|---|
adTagUrl |
string |
|
networkCode |
string |
|
contentSourceUrl |
string |
|
region |
string |
|
projectNumber |
string |
|
oAuthToken |
string |
createVodStreamRequest(contentSourceId, videoId, apiKey)
初始化 VOD ima.StreamRequest
的必需属性。使用此 API 会导致系统忽略任何其他特定于 ima.StreamType
的属性。
如果任何必需参数是空字符串,则会发生错误日志记录,并且 API 会返回一个通用 StreamRequest
,不忽略任何属性。
返回 ima.StreamRequest
:具有所需 VOD 属性的 ima.StreamRequest
对象。
参数 | 类型 | 说明 |
---|---|---|
contentSourceId |
string |
|
videoId |
string |
|
apiKey |
string |
可选参数,将分配给返回的 |
ima.StreamType 类
字段
定义要求播放器播放的流的类型。前贴片广告和视频点播 (VOD) 应从直播开始时开始播放。
属性
名称 | 类型 | 说明 |
---|---|---|
LIVE |
|
视频已上线。 |
VOD |
|
此视频是点播视频。 |
ima.封装容器 Info 类
字段
方法
包含有关封装容器的信息。
属性
名称 | 类型 | 说明 |
---|---|---|
adId |
|
广告的 ID;如果未知,则为空字符串。 |
adSystem |
|
广告系统的声明名称;如果未知,则为空字符串。 |
creativeAdId |
|
广告素材上的广告 ID;如果未知,则为空字符串。 |
creativeId |
|
广告素材的 ID,如果未知,则为空字符串。 |
dealId |
|
交易 ID;如果未知,则为空字符串。 |
createWrapperInfo()
返回 ima.WrapperInfo
: