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

启动异步串流请求 在调用此方法后，Control 会立即返回到播放器。

返回 object：如果未出现错误，则返回错误或无效

参数	类型	说明
streamRequest	object

返回页首

ima.AdBreakInfo 类

字段

adPosition、duration、podIndex、timeOffset、totalAds

方法

createAdBreakInfo

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

属性

名称	类型	说明
adPosition		广告插播时间点中的广告的索引。如果是独立广告，则为 1。
duration		中断的最长持续时间（以秒为单位），如果未知，则为 -1。
podIndex		对于直播视频流，始终返回 -1。对于视频点播 (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、MIDPOINT、 SKIPPABLE_STATE_CHANGEDTHIRD_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、currentTime、duration、skipOffset、 skipOffset、 universalAdIDRegistryuniversalAdIDValue

方法

createAdInfo

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

属性

名称	类型	说明
adBreakInfo		与此广告所在的整个插播时间点相关的信息。
adDescription		广告的广告内容描述。
adId		广告的 ID，如果未知，则为空字符串。
adSystem		提供广告素材的广告系统。
adTitle		广告的标题。
advertiserName		由投放方定义的广告客户名称。
companions		VAST 响应中指定的随播广告。
currentTime		广告中的当前时间（以秒为单位），如果未知，则为 -1。
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		表示广告素材类型（通常是 MIME 类型）。
height		随播广告的高度（以像素为单位）。如果不可用，则为 0。
trackingEvents		跟踪事件的映射，其中键是事件，值为要对该事件执行 ping 操作的网址列表。
url		此随播广告的静态资源的网址。
width		随播广告的宽度（以像素为单位）。如果不可用，则为 0。

createCompanion()

返回 ima.Companion：

返回页首

ima.CuePoint 类

字段

end、hasPlayed、start

方法

createCuePoint

包含广告插入点的相关信息。

属性

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

createCuePoint()

返回 ima.CuePoint：

返回页首

ima.Error 类

字段

id、info、type

方法

createError

在出现错误时传递给错误处理程序的对象。

属性

名称	类型	说明
id		错误的 ID。有关错误代码列表，请参阅 ErrorEvent 常量。
info		有关错误的其他信息。
type		始终设置为错误，以指示此对象的类型。

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 或短划线。 以 ima.StreamFormat 进行定义。
manifest		数据流的网址。
streamId		数据流的唯一 ID。
streamType		视频类型：直播或点播。 在 ima.StreamType 中定义。
subtitles		字幕（如果有）。否则无效。

createStreamInfo()

返回 ima.StreamInfo：

返回页首

ima.StreamManager 类

方法

addEventListener、createStreamManager、enableInteractiveAds、getContentTime、getCuePoints、getPreviousCuePoint、getStreamTime、loadThirdPartyStream、onMessage和其他代码 replaceAdTagParameters

用于管理视频流播放的对象。

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、adUiNode、apiKey、assetKey、authToken、contentSourceId、customAssetKey、format、networkCode、networkCode、player, player,ppidstreamActivityMonitorIdvideoIdvideoObjectvideoStitcherSessionOptions

方法

createLiveStreamRequest、createPodLiveStreamRequest、createPodVodStreamRequest、createStreamRequest、createVideoStitcherLiveStreamRequest、createVideoStitcherVodStreamRequest、CreateVideoStitcherVodStreamRequestWithVodConfig、createod14createVodStreamRequest

用于指定流请求的属性。

属性

名称	类型	说明
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 Audience 发布商提供的标识符。
streamActivityMonitorId		用于通过数据流活动监控工具调试数据流的 ID。这为发布商提供了一种便捷的方式，使其能够在数据流活动监控工具中找到数据流日志。
videoId		点播视频流的必填项。 视频内容来源的标识符。
videoObject		负责在客户端应用上播放视频的视频对象（例如视频 roSGNode）。系统会轮询此对象，获取各种数据，以用于为直播 HLS ID3 事件正确计时。
videoStitcherSessionOptions		会话选项用于为 VideoStitcher streamRequest 设置特定于视频的参数。

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)

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

初始化 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 类

字段

直播、视频点播

定义要求播放器播放的视频流的类型。 前贴片广告和视频点播内容应从直播开头播放。

属性

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

返回页首

ima.WrapperInfo 类

字段

adId、adSystem、creativeAdId、creativeId、dealId

方法

createWrapperInfo

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

属性

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

createWrapperInfo()

返回 ima.WrapperInfo：

返回页首