类 ima
方法
用于控制 IMA SDK 的全局函数。
disableLogging()
停用 SDK 日志记录。日志记录功能默认处于开启状态。
getStreamManager()
返回数据流管理器(如果有)。
如果流管理器尚不可用,则返回“无效”。
如果创建数据流管理器时出错,系统会返回一个错误对象。
返回 object
:串流管理器或错误对象。
initSdk(settings)
初始化 SDK。
参数 | 类型 | 说明 |
---|---|---|
settings |
object |
可选的 IMA 设置对象。 |
requestStream(streamRequest)
开始异步串流请求。调用此方法后,控制会立即返回给播放器。
返回 object
:如果没有错误,则返回错误或无效
参数 | 类型 | 说明 |
---|---|---|
streamRequest |
object |
类 ima.AdBreakInfo
字段
方法
包含广告插播的相关信息。由 SDK 传递给事件回调。
属性
名称 | 类型 | 说明 |
---|---|---|
adPosition |
|
广告插播时段中的广告编号。对于独立广告,该索引为 |
duration |
|
广告插播时长上限(以秒为单位),如果未知,则为 |
podIndex |
|
对于直播,返回广告插播时间点 ID 作为广告连播索引;对于前贴片广告,返回 |
timeOffset |
|
广告连播在内容中的位置(以秒为单位)。
前贴片广告会返回 |
totalAds |
|
此广告插播中包含的广告总数。
对于独立广告,此值为 |
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
字段
方法
如果发生错误,则传递给错误处理程序的对象。
属性
名称 | 类型 | 说明 |
---|---|---|
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 或 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)
参数 | 类型 | 说明 |
---|---|---|
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 |
查询时间, |
getStreamTime(contentTime)
从 VOD 的内容时间获取直播时间(以毫秒为单位)。
如需了解详情,请参阅常见问题解答。
返回 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 |
|
自定义资产键用于确定应播放哪个串流。若要为 Pod 分发直播请求,则必须使用自定义素材资源键。 |
format |
|
数据流的格式。默认为 |
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 |
分配给返回的 |
networkCode |
string |
发出串流请求的发布商的广告资源网代码。添加影音平台代码并非强制要求,但我们建议您这样做。 |
createPodLiveStreamRequest(customAssetKey, networkCode, apiKey)
初始化 Pod 实时 ima.StreamRequest
的必需属性。使用此 API 会导致忽略任何其他 ima.StreamType
专用属性。如果任何必需参数为空字符串,系统会进行错误日志记录,并且 API 会返回一个通用 StreamRequest
,而不会忽略任何属性。
返回 StreamRequest
:包含所需 PodLive 属性的 ima.StreamRequest
对象。
参数 | 类型 | 说明 |
---|---|---|
customAssetKey |
string |
|
networkCode |
string |
|
apiKey |
string |
分配给返回的 |
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 |
分配给返回的 |
networkCode |
string |
发出串流请求的发布商的广告资源网代码。添加影音平台代码并非强制要求,但我们建议您这样做。 |
类 ima.StreamType
字段
定义系统要求播放器播放的串流类型。前贴片广告和视频点播应从直播开始播放。
属性
名称 | 类型 | 说明 |
---|---|---|
LIVE |
|
视频已发布。 |
VOD |
|
该视频是点播视频。 |
类 ima.WrapperInfo
字段
方法
包含封装容器的相关信息。
属性
名称 | 类型 | 说明 |
---|---|---|
adId |
|
广告的 ID;如果未知,则为空字符串。 |
adSystem |
|
广告系统的声明名称,如果未知,则为空字符串。 |
creativeAdId |
|
广告素材的广告 ID,如果未知,则为空字符串。 |
creativeId |
|
广告素材的 ID,如果未知,则为空字符串。 |
dealId |
|
交易 ID;如果未知,则为空字符串。 |
createWrapperInfo()
返回 ima.WrapperInfo
: