适用于 Roku 的 IMA DAI SDK

    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 类

方法

用于控制 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、info、type

方法

发生错误时，传递给错误处理程序的对象。

属性

名称 类型 说明
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

定义流的格式。

属性

名称 类型 说明
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)


返回 ima.StreamManager：

参数 类型 说明
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>|Invalid

字幕与视频流相关联，如果没有，则为 Invalid。

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

数据流的格式。默认为 ima.StreamFormat.HLS。
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

可选参数，将分配给返回的 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 属性；默认为空字符串。

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.StreamRequest 的 ima.StreamRequest.apiKey 属性；默认为空字符串。

返回页首

ima.StreamType 类

字段

定义要求播放器播放的流的类型。前贴片广告和视频点播 (VOD) 应从直播开始时开始播放。

属性

名称 类型 说明
LIVE

视频已上线。
VOD

此视频是点播视频。

返回页首

ima.封装容器 Info 类

字段

方法

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

属性

名称 类型 说明
adId

广告的 ID；如果未知，则为空字符串。
adSystem

广告系统的声明名称；如果未知，则为空字符串。
creativeAdId

广告素材上的广告 ID；如果未知，则为空字符串。
creativeId

广告素材的 ID，如果未知，则为空字符串。
dealId

交易 ID；如果未知，则为空字符串。

createWrapperInfo()


返回 ima.WrapperInfo：

返回页首