适用于 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 日志记录。日志记录功能默认处于开启状态。

getStreamManager()

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

返回 object:串流管理器或错误对象。

initSdk(settings)

初始化 SDK。

参数 类型 说明
settings object

可选的 IMA 设置对象。

requestStream(streamRequest)

开始异步串流请求。调用此方法后,控制会立即返回给播放器。

返回 object:如果没有错误,则返回错误或无效

参数 类型 说明
streamRequest object

返回页首

类 ima.AdBreakInfo

字段

方法

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

属性

名称 类型 说明
adPosition

广告插播时段中的广告编号。对于独立广告,该索引为 1

duration

广告插播时长上限(以秒为单位),如果未知,则为 -1

podIndex

对于直播,返回广告插播时间点 ID 作为广告连播索引;对于前贴片广告,返回 0。直播中没有后贴片广告。默认值为 -2。对于视频点播 (VOD),返回广告连播的索引。 对于前贴片广告连播,返回 0。对于中贴片广告,返回 12、...、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

在广告播放头超出第三四分位时触发。

返回页首

类 ima.AdInfo

字段

方法

包含广告的相关信息。由 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

执行此广告所需的 API;如果不可用,则为“无效”。

creativeType

表示广告素材类型,通常为 mimetype。

height

配套应用的高度(以像素为单位)。如果不可用,则为 0。

trackingEvents

跟踪事件的映射,其中键是事件,值是该事件发生时要进行 ping 的网址列表。

url

此随播广告素材的静态资源的网址。

width

随播广告的宽度(以像素为单位)。如果不可用,则为 0。

createCompanion()


返回 ima.Companion

返回页首

类 ima.CuePoint

字段

方法

包含有关 cue 点的信息。

属性

名称 类型 说明
end

cue 点的结束时间(以秒为单位)。这对应于广告插播时间点。

hasPlayed

一个布尔值,表示 cue 点已播放。

start

cue 点的开始时间(以秒为单位)。这对应于广告插播时间点。

createCuePoint()


返回 ima.CuePoint

返回页首

类 ima.Error

字段

idinfotype

方法

如果发生错误,则传递给错误处理程序的对象。

属性

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

字段

DASHHLS

定义数据流的格式。

属性

名称 类型 说明
DASH

HLS

返回页首

类 ima.StreamInfo

字段

方法

从 SDK 传递给播放器的有关数据流的信息。

属性

名称 类型 说明
format

视频格式:hls 或 dash。 在 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 串流的时间(以毫秒为单位),表示不含广告的内容中的时间。如需了解详情,请参阅常见问题解答。如需获取当前串流时间的内容时间,请传入 -1

返回 Integer:与给定直播时间对应的内容时间。

参数 类型 说明
streamTime Integer

数据流中的时间。

getCuePoints()

返回与所有广告插播时间点对应的所有 cue 点。此字段仅适用于所有广告插播时间点均已知晓的视频点播内容。所有时间均表示以秒为单位的直播时间。 对于 Cloud Stitching API 串流,每个 ima.CuePointhasPlayed 属性始终为 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)

加载广告元数据,并使用提供的 streamManifestUrlstreamSubtitle 数据调用 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

自定义资产键用于确定应播放哪个串流。若要为 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.StreamRequestima.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.StreamRequestima.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.StreamRequestima.StreamRequest.apiKey 属性的参数。如果没有 API 密钥,请传递空字符串。

networkCode string

发出串流请求的发布商的广告资源网代码。添加影音平台代码并非强制要求,但我们建议您这样做。

返回页首

类 ima.StreamType

字段

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

属性

名称 类型 说明
LIVE

视频已发布。

VOD

该视频是点播视频。

返回页首

类 ima.WrapperInfo

字段

方法

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

属性

名称 类型 说明
adId

广告的 ID;如果未知,则为空字符串。

adSystem

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

creativeAdId

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

creativeId

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

dealId

交易 ID;如果未知,则为空字符串。

createWrapperInfo()


返回 ima.WrapperInfo

返回页首