Google IMA DAI SDK Roku 集成指南在 SceneGraph 频道中实现动态广告插入【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本指南以本仓库 ima-dai-sdk 技能中的 Roku StreamManager 指南 为核心系统讲解如何在 Roku SceneGraph 频道中接入 Google IMA DAIDynamic Ad Insertion动态广告插入SDK实现直播流livestream与点播流VOD的广告无缝插播。读完本文你将掌握从 SDK 导入、初始化、发起流请求、启动播放、定时元数据转发到广告事件监听的完整闭环并了解如何支持可跳过广告skippable ads。一、总体流程概览Google full-service DAI 的核心思路是应用不再直接播放内容源而是向 Google Ad Manager 请求一条插播过广告的流地址HLS/DASH manifestSDK 负责在流中注入广告并通过定时元数据timed metadata驱动广告生命周期事件。在 Roku 场景下这一过程通过StreamManager对象串联New_IMASDK()初始化 SDKsdk.createPlayer()创建播放器适配层CreateLiveStreamRequest/CreateVodStreamRequest构造请求requestStream()发起请求最后getStreamManager()拿到流管理器并接管后续播放与事件。仓库中 SKILL.md 给出了跨平台通用工作流导入 SDK → 初始化 SDK → 添加流事件监听 → 设置定时元数据转发 → 发起流请求 → 流失败或用户离开时清理 SDK 资源。本文按此骨架展开 Roku 平台的完整实现。二、导入 IMA DAI SDK2.1 在 manifest 中声明依赖在 Roku 应用的manifest文件中声明 SDK 所需的 BrightScript 库bs_libs_requiredroku_ads_lib,googleima3roku_ads_lib是 Roku 广告库googleima3是 Google IMA SDK 的 BrightScript 实现二者缺一不可。2.2 创建后台 Task 组件加载库SDK 的请求与播放协调工作应在后台线程执行避免阻塞主 UI 线程。创建一个继承自Task的组件components/Sdk.xml用于加载库并运行 SDKcomponent nameimasdk extendsTask script typetext/brightscript ![CDATA[ Library Roku_Ads.brs Library IMA3.brs ]] /script /component这里通过 CDATA 包裹Library指令确保 XML 解析器不会干扰 BrightScript 代码。Task 组件是 Roku SceneGraph 中在独立线程运行的载体SDK 的全部逻辑都在这条后台线程中执行。三、SDK 初始化在 Task 线程中创建 SDK 实例并初始化。用invalid判空实现单例语义避免重复初始化if m.sdk invalid m.sdk New_IMASDK() m.sdk.initSdk() end ifNew_IMASDK()返回 SDK 单例对象initSdk()完成内部状态与网络栈的准备。这一步应在发起任何流请求之前完成与仓库中其他平台指南如 Web 指南要求尽早实例化StreamManager的做法一致目的是让 SDK 有足够时间建立监听与资源。四、Video Player 适配层设置4.1 创建播放器实例通过sdk.createPlayer()创建播放器适配对象并将m.topTask 节点的引用挂载到 player 上以便后续回调能访问场景图节点m.player m.sdk.createPlayer() m.player.top m.top4.2 定义播放控制回调m.player是 SDK 与你的Video节点之间的桥梁需要实现以下回调方法SDK 会在合适的时机调用它们m.player.loadUrl Function(urlData) m.top.video.enableTrickPlay false m.top.urlData urlData End Function m.player.adBreakStarted Function(adBreakInfo as Object) m.top.adPlaying true m.top.video.enableTrickPlay false End Function m.player.adBreakEnded Function(adBreakInfo as Object) m.top.adPlaying false m.top.video.enableTrickPlay true End Function m.player.seek Function(timeSeconds as Double) m.top.video.seekMode accurate m.top.video.seek timeSeconds End Function各回调的职责loadUrl(urlData)SDK 拿到流 manifest 后回调把 manifest 数据通过m.top.urlData暴露给场景同时临时关闭enableTrickPlay禁止快进/快退因为此时尚未进入稳定播放状态。adBreakStarted(adBreakInfo)广告时段开始置m.top.adPlaying true并禁用 trick play防止用户在广告期间拖动进度条。adBreakEnded(adBreakInfo)广告时段结束恢复adPlaying false与 trick play。seek(timeSeconds)广告需要跳转例如可跳过广告的跳过行为时以accurate模式精确 seek 到目标时间点。五、发起流请求Roku 平台支持两种 Google full-service DAI 流直播流CreateLiveStreamRequest与点播流CreateVodStreamRequest。5.1 请求直播流streamRequest m.sdk.CreateLiveStreamRequest( ASSET_KEY_PLACEHOLDER, , // Replace the empty string with a Google DAI API key if the app use one NETWORK_CODE_PLACEHOLDER )参数说明参数含义ASSET_KEY_PLACEHOLDER在 Google Ad Manager 中为直播事件配置的 asset key素材键用于唯一标识一条直播流第二参数Google DAI API key如果应用使用 API key 则填入否则传空字符串NETWORK_CODE_PLACEHOLDERGoogle Ad Manager 的 network code网络代码5.2 请求 VOD 流streamRequest m.sdk.CreateVodStreamRequest( CONTENT_SOURCE_ID_PLACEHOLDER, VIDEO_ID_PLACEHOLDER, , // Replace the empty string with a Google DAI API key if the app use one NETWORK_CODE_PLACEHOLDER )参数说明参数含义CONTENT_SOURCE_ID_PLACEHOLDERGoogle Ad Manager 中的 content source IDCMS ID标识内容来源VIDEO_ID_PLACEHOLDER该内容在 CMS 中的 video ID第三参数Google DAI API key无则传空字符串NETWORK_CODE_PLACEHOLDERGoogle Ad Manager 的 network code测试阶段可以直接使用 Google 官方提供的 DAI 示例流sample streams参数值快速验证整条链路是否打通。5.3 执行流请求请求对象需要绑定两个关键引用后调用requestStream()player即上一步创建的m.player适配对象adUiNode场景中的Video节点引用SDK 依赖它定位广告 UI 与视频节点。streamRequest.player m.player streamRequest.adUiNode m.top.findNode(myVideo) requestResult m.sdk.requestStream(streamRequest) If requestResult Invalid print Error requesting stream ;requestResult Else m.streamManager Invalid While m.streamManager Invalid sleep(50) m.streamManager m.sdk.getStreamManager() End While If m.streamManager Invalid or (m.streamManager[type] Invalid and m.streamManager[type] error) errors CreateObject(roArray, 1, True) print error ;m.streamManager[info] errors.push(m.streamManager[info]) m.top.errors errors Else m.streamManager.start() End If End If这段代码的要点requestStream()返回非Invalid表示请求立即失败例如参数缺失直接打印错误。请求成功后getStreamManager()可能尚未就绪因此用sleep(50)循环轮询最多 50 毫秒间隔直到拿到流管理器。若流管理器类型为error把m.streamManager[info]中的错误信息收集进数组并推送到m.top.errors交由 UI 层展示。一切正常则调用m.streamManager.start()正式启动流会话。六、启动流播放SDK 在后台线程解析流 manifest 后会通过loadUrl回调把数据放到m.top.urlData。在MainScene.xml中观察该字段并驱动Video节点播放m.sdkTask.observeField(urlData, urlLoadRequested) Setting control to run starts the task thread. m.sdkTask.control RUN Sub urlLoadRequested(message as Object) data message.getData() vidContent createObject(RoSGNode, ContentNode) vidContent.url data.manifest vidContent.title m.videoTitle vidContent.streamformat data.format m.video.content vidContent m.video.setFocus(true) m.video.visible true m.video.control play m.video.EnableCookies() End Sub说明observeField(urlData, urlLoadRequested)注册字段观察者将 Task 的control设为RUN启动后台线程。回调中data.manifest是 SDK 重写后的流地址data.format是流格式HLS 等。将二者写入ContentNode后赋给m.video.content随后control play开始播放。调用m.video.EnableCookies()确保播放器在请求流时携带必要的 Cookie对需要鉴权的流尤为重要。七、定时元数据转发Timed Metadata ForwardingDAI 的广告事件完全依赖流中内嵌的定时元数据HLS 的 ID3 帧或 DASH 的自定义事件。Roku 上Video节点默认会解析这些元数据但必须主动把它们转发给StreamManager.onMessage(msg)SDK 才能据此触发广告事件回调。m.top.video.timedMetaDataSelectionKeys [*] m.port CreateObject(roMessagePort) fields m.top.video.getFields() for each field in fields m.top.video.observeField(field, m.port) end for while true msg wait(1000, m.port) if m.top.video invalid exit while end if m.streamManager.onMessage(msg) currentTime m.top.video.position if currentTime 3 and not m.top.adPlaying m.top.video.enableTrickPlay true end if end while关键点timedMetaDataSelectionKeys [*]通配所有定时元数据键让Video节点产生相应的事件通知。创建roMessagePort遍历Video节点所有字段逐一observeField把事件统一投递到该端口。事件循环内wait(1000, m.port)阻塞等待事件把每一条消息交给m.streamManager.onMessage(msg)处理。播放位置超过 3 秒且当前不在广告时段时恢复enableTrickPlay true允许用户操作播放控制。m.top.video invalid时退出循环避免节点销毁后继续访问。八、监听广告事件在m.streamManager上注册事件监听器即可跟踪广告生命周期与错误。仓库指南提供了从广告开始到结束的完整事件族m.streamManager.addEventListener(m.sdk.AdEvent.ERROR, errorCallback) m.streamManager.addEventListener(m.sdk.AdEvent.START, startCallback) m.streamManager.addEventListener(m.sdk.AdEvent.FIRST_QUARTILE, firstQuartileCallback) m.streamManager.addEventListener(m.sdk.AdEvent.MIDPOINT, midpointCallback) m.streamManager.addEventListener(m.sdk.AdEvent.THIRD_QUARTILE, thirdQuartileCallback) m.streamManager.addEventListener(m.sdk.AdEvent.COMPLETE, completeCallback)各回调的签名与职责Function startCallback(ad as Object) as Void print Ad event: START End Function Function firstQuartileCallback(ad as Object) as Void print Ad event: FIRST_QUARTILE End Function Function midpointCallback(ad as Object) as Void print Ad event: MIDPOINT End Function Function thirdQuartileCallback(ad as Object) as Void print Ad event: THIRD_QUARTILE End Function Function completeCallback(ad as Object) as Void print Ad event: COMPLETE End Function Function errorCallback(error as Object) as Void print Ad event: ERROR - ; error m.errorState true End Function事件语义一览事件含义典型用途START广告开始播放记录广告曝光、上报监测FIRST_QUARTILE广告播放至 25%进度监测/结算MIDPOINT广告播放至 50%进度监测THIRD_QUARTILE广告播放至 75%进度监测COMPLETE广告播放完成上报广告完成、恢复内容ERROR广告或流发生错误置m.errorState、触发降级策略这些事件对应 Web/HTML5 指南中的STARTED / FIRST_QUARTILE / MIDPOINT / THIRD_QUARTILE / COMPLETE语义见 web-StreamManager-guide跨平台命名一致便于维护多端逻辑。8.1 可跳过广告支持要支持可跳过广告skippable ads需要满足两个条件实现seek回调跳过动作本质是一次精确跳转m.player.seek必须以accurate模式驱动Video节点在流请求中设置adUiNode确保streamRequest.adUiNode m.top.findNode(myVideo)指向视频节点SDK 才能把跳过 UI 挂载到正确的节点上。m.player.seek Function(timeSeconds as Double) m.top.video.seekMode accurate m.top.video.seek timeSeconds End Function其中seekMode accurate让跳转更精确默认的 fast seek 可能跳过关键帧导致广告切点不准。九、错误处理与资源清理从本文的请求与播放流程可以看到错误处理贯穿始终请求阶段requestStream()立即返回错误对象非Invalid直接打印并终止。流创建阶段getStreamManager()返回类型为error的流管理器时读取m.streamManager[info]收集错误信息。播放阶段AdEvent.ERROR事件回调中置m.errorState true应用可据此切换备用流backup stream。这与仓库中其他平台指南的策略一致Web 指南在ERROR事件中读取errorMessage并切换回退流iOS 指南在failedWith回调中调用playBackupStream()。Roku 实现同样建议在致命错误时展示错误提示或切换到备用内容源并在用户离开流或流结束时按 SKILL.md 中的通用步骤清理 SDK 资源释放监听、终止事件循环、置空流管理器引用避免内存泄漏与重复初始化。十、参考实现与其他平台对照原指南指向的参考实现BasicExample包含两个核心文件components/Sdk.xml即本文第二节创建的 Task 组件负责加载库与运行 SDK与components/MainScene.xml负责观察urlData、装配Video节点、转发元数据与注册广告事件。你可以在自己的 Roku 工程中按本节给出的完整流程复刻这两个文件的结构。本仓库的 ima-dai-sdk 技能还收录了其他平台的同类指南便于多端开发时对照实现Web/HTML5 StreamManager 指南浏览器端 HLS.js / DASH.js 集成CastCAFStreamManager 指南Chromecast Web Receiver 集成iOS/tvOS IMAStreamRequest 指南AVPlayer集成Android ExoPlayer IMA 扩展指南Media3ImaServerSideAdInsertionMediaSource集成。它们共享同一套 Google full-service DAI 概念asset key直播、content source IDvideo ID点播、network code、requestStream()发起请求、定时元数据转发与广告事件监听。Roku 平台的特殊性在于必须借助 SceneGraphTask在后台线程运行 SDK用roMessagePort观察Video节点字段来桥接定时元数据并通过m.player回调适配层把 SDK 的播放控制指令转译成Video节点操作。总结在 Roku 频道中接入 Google IMA DAI SDK 的完整链路可概括为manifest声明库 → Task 组件加载 SDK →New_IMASDK()初始化 →createPlayer()建立适配层 → 按直播/点播构造CreateLiveStreamRequest/CreateVodStreamRequest→requestStream()发起请求 → 轮询getStreamManager()并start()→ 观察urlData驱动Video播放 → 用roMessagePort转发定时元数据 → 注册广告事件与错误处理。掌握这套流程你就能在 Roku 上实现与 Web、iOS、Android、Cast 平台行为一致的动态广告插入体验。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考