借助适用于 Roku 的 Programmatic Access Library (PAL) SDK，获得直接 VAST 调用 (DVC) 批准的发布商可以通过基于 DVC 的 Roku 应用创收。借助 PAL SDK，您可以向 Google 请求 Nonce（加密字符串），以便签署 DVC 请求。每个新串流请求都必须附带新生成的 Nonce。不过，您可以针对同一串流中的多个广告请求重复使用同一个 Nonce。
本指南通过示例介绍了如何将 PAL SDK 纳入 Roku 应用、请求 Nonce 并注册广告展示。
前提条件
在开始本指南之前，您需要执行以下操作：
- Roku 开发环境 - 如需了解详情，请参阅 Roku 开发者环境设置指南。
一个结构如下的项目文件夹：
./ components/ MainScene.xml PALInterface.xml SampleVideoPlayer.xml images/ icon_focus_hd.png icon_focus_sd.png icon_side_hd.png icon_side_sd.png splash_fhd.png splash_hd.png splash_sd.png source/ main.brs manifest
设置项目
在集成 PAL SDK 之前，您需要配置项目文件。
清单
title=PAL for Roku Sample
subtitle=As seen in the PAL for Roku Get Started Guide
major_version=1
minor_version=0
build_version=00001
mm_icon_focus_hd=pkg:/images/icon_focus_hd.png
mm_icon_side_hd=pkg:/images/icon_side_hd.png
mm_icon_focus_sd=pkg:/images/icon_focus_sd.png
mm_icon_side_sd=pkg:/images/icon_side_sd.png
splash_screen_sd=pkg:/images/splash_sd.jpg
splash_screen_hd=pkg:/images/splash_hd.jpg
splash_screen_fhd=pkg:/images/splash_fhd.jpg
splash_color=#000000
splash_min_time=1000
ui_resolutions=hd
source/main.brs
sub Main()
showChannelSGScreen()
end sub
sub showChannelSGScreen()
screen = CreateObject("roSGScreen")
m.port = CreateObject("roMessagePort")
screen.setMessagePort(m.port)
m.scene = screen.CreateScene("MainScene")
screen.show()
while(true)
msg = wait(0, m.port)
msgType = type(msg)
if msgType = "roSGScreenEvent"
if msg.isScreenClosed() then return
end if
end while
end sub
创建示例视频播放器
SampleVideoPlayer 组件只是封装一个视频组件来捕获遥控器按下操作。替换 onKeyEvent，以便在遥控器的焦点转移到视频/广告播放器后，系统会捕获并向上冒泡到 PAL 的任何其他按键操作（向上、向下、向左、向右、点击等）。
components/SampleVideoPlayer.xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="SampleVideoPlayer" extends="Video">
<interface>
<field id="pressedKey" type="String" />
</interface>
<script type="text/brightscript">
<![CDATA[
Function onKeyEvent(key as String, press as Boolean) as Boolean
If press
m.top.pressedKey = key
End If
return True
End Function
]]>
</script>
<children>
<Label text="VIDEO" color="0xFFFFFFFF" font="font:MediumBoldSystemFont" horizAlign="center" vertAlign="center" width="720" height="480" />
</children>
</component>
创建测试接口
实现带有用于执行以下操作的按钮的场景：
- 请求 Nonce。
- 发送广告点击。
- 发送播放开始事件。
- 发送播放结束事件。
- 将焦点转移到视频按钮。
components/MainScene.xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="MainScene" extends="Scene" initialFocus="requestNonceButton">
<children>
<ButtonGroup>
<button text="Request Nonce" id="requestNonceButton" />
<button text="Send Ad Click" id="sendAdClickButton" />
<button text="Send Playback Start" id="sendPlaybackStartButton" />
<button text="Send Playback End" id="sendPlaybackEndButton" />
<button text="Transfer Focus to Video" id="transferFocusToVideoButton" />
</ButtonGroup>
<SampleVideoPlayer id="YourVideoPlayer" width="720" height="480" focusable="true" />
</children>
</component>
创建 SDK 接口组件
如需在主场景和 PAL SDK 之间进行通信，您需要一个包含异步代码的组件。这是必要的，因为 PAL SDK 会发出外部网络请求，而 Roku 应用的主线程无法执行此操作。如需向此组件发送数据，您需要一个接口来定义该组件发送和接收的数据。
components/PALInterface.xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="PALInterface" extends="Task">
<interface>
<!--Commands-->
<field id="requestNonce" type="Boolean" />
<field id="sendAdClick" type="Boolean" />
<field id="sendAdTouchKey" type="String" />
<field id="sendPlaybackStart" type="Boolean" />
<field id="sendPlaybackEnd" type="Boolean" />
<field id="endThread" type="Boolean" />
<!--Responses-->
<field id="errors" type="stringarray" />
<field id="nonce" type="String" />
</interface>
</component>
导入 IMA SDK
如需使用 PAL 库，您需要在应用清单中添加适用于 Roku 的 IMA SDK，并将其导入 PALInterface 组件。
清单
... splash_color=#000000 splash_min_time=1000 ui_resolutions=hd bs_libs_required=googleima3
components/PALInterface.xml
<?xml version = "1.0" encoding = "utf-8" ?> <component name="PALInterface" extends="Task"> <interface> <!-- commands --> <field id="requestNonce" type="Boolean" /> <field id="sendAdClick" type="Boolean" /> <field id="sendAdTouchKey" type="String" /> <field id="sendPlaybackStart" type="Boolean" /> <field id="sendPlaybackEnd" type="Boolean" /> <field id="endThread" type="Boolean" /> <!-- responses --> <field id="errors" type="stringarray" /> <field id="nonce" type="String" /> </interface> <script type = "text/brightscript"> <![CDATA[ Library "IMA3.brs" ]]> </script> </component>
从场景触发界面组件
接下来，添加用于监听用户互动并触发界面组件更改的 BrightScript 代码：
如需从接口组件接收输出，请在与这些输出关联的接口字段上实现字段观察器，并将其附加到主组件中的回调函数。请在首次注册组件时执行此操作。
如需将用户互动发送到界面组件，请在您之前创建的按钮上实现字段观察器，以触发与这些命令关联的界面字段中的更改。
components/MainScene.xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="MainScene" extends="Scene" initialFocus="requestNonceButton">
<children>
<ButtonGroup>
<button text="Request Nonce" id="requestNonceButton" />
<button text="Send Ad Click" id="sendAdClickButton" />
<button text="Send Ad Touch" id="sendAdTouchButton" />
<button text="Send Playback Start" id="sendPlaybackStartButton" />
<button text="Send Playback End" id="sendPlaybackEndButton" />
</ButtonGroup>
<Video id="YourVideoPlayer" width="720" height="480" focusable="true" />
</children>
<script type="text/brightscript">
<![CDATA[
Function init()
requestNonceButton = m.top.findNode("requestNonceButton")
requestNonceButton.observeField("buttonSelected", "requestNonce")
sendAdClickButton = m.top.findNode("sendAdClickButton")
sendAdClickButton.observeField("buttonSelected", "sendAdClick")
sendPlaybackStart = m.top.findNode("sendPlaybackStartButton")
sendPlaybackStart.observeField("buttonSelected", "sendPlaybackStart")
sendPlaybackEnd = m.top.findNode("sendPlaybackEndButton")
sendPlaybackEnd.observeField("buttonSelected", "sendPlaybackEnd")
loadImaSdk()
End Function
' Initialize SDK Interface component and attach callbacks to field observers.
Function loadImaSdk() as Void
m.sdkTask = createObject("roSGNode", "PALInterface")
m.sdkTask.observeField("errors", "onSdkLoadedError")
m.sdkTask.observeField("nonce", "onNonceLoaded")
print "Running load IMA task."
m.sdkTask.control = "RUN"
End Function
Sub onSdkLoadedError(message as Object)
print "----- errors in the sdk loading process --- ";message.getData()
End Sub
' Callback triggered when Nonce is loaded.
Sub onNonceLoaded(message as Object)
nonce = m.sdkTask.nonce
print "onNonceLoaded ";nonce
End Sub
Function requestNonceButtonPressed() As Void
print "Request Nonce"
' Inform the SDK interface component to request a nonce.
m.sdkTask.requestNonce = True
End Function
' Action triggered on player start, either from user action or autoplay.
Function sendPlaybackStart() As Void
m.sdkTask.sendPlaybackStart = True
End Function
' Action triggered on player end, either when content ends or the user exits
' playback of this content.
Function sendPlaybackEnd() As Void
m.sdkTask.sendPlaybackEnd = True
End Function
]]>
</script>
</component>
添加了用于转移焦点的方法
接下来，捕获用户按键操作，以便在视频元素之间转移焦点。
components/MainScene.xml
...
<script type="text/brightscript">
<![CDATA[
Function init()
...
m.sendPlaybackStart = m.top.findNode("sendPlaybackStartButton")
m.sendPlaybackStart.observeField("buttonSelected", "sendPlaybackStart")
m.sendPlaybackEnd = m.top.findNode("sendPlaybackEndButton")
m.sendPlaybackEnd.observeField("buttonSelected", "sendPlaybackEnd")
m.transferFocusToVideoButton = m.top.findNode("transferFocusToVideoButton")
m.transferFocusToVideoButton.observeField("buttonSelected", "transferFocusToVideo")
' Your video player set up to handle key press events.
m.video = m.top.findNode("YourVideoPlayer")
m.video.observeField("pressedKey", "onVideoKeyPress")
loadImaSdk()
End Function
...
' Action triggered on player end, either when content ends or the user exits
' playback of this content.
Function sendPlaybackEnd() As Void
m.sdkTask.sendPlaybackEnd = True
End Function
Function transferFocusToVideo() As Void
m.video.setFocus(true)
End Function
Function onVideoKeyPress() As Void
key = m.video.pressedKey
If key = ""
Return
End If
m.sdkTask.sendAdTouchKey = key
' If back or up is pressed, transfer focus back up to the buttons.
If key = "back" or key = "up"
m.transferFocusToVideoButton.setFocus(true)
End If
' Reset so that we get the next key press, even if it's a repeat of the last
' key.
m.video.pressedKey = ""
End Function
]]>
</script>
</component>
初始化 PAL SDK 并创建 nonceLoader
现在，您可以开始构建 PAL SDK 实现的核心逻辑了。首先，从单独的线程中初始化 SDK。
components/PALInterface.xml
...
<script type = "text/brightscript">
<![CDATA[
Library "IMA3.brs"
Sub init()
' It is not possible to access roUrlTransfer on the main thread. Setting
' functionName to a function and then setting control to "RUN" causes that
'function to run on a separate thread.
m.top.functionName = "runPalThread"
' Loads the SDK on the current thread if it is not yet loaded.
' This blocks execution of other functions on this thread until the SDK is loaded.
If m.sdk = Invalid
m.sdk = new_imaSdk()
End If
m.nonceLoader = m.sdk.CreateNonceLoader()
End Sub
' Starts the player event loop. This loop only terminates when "endThread" is sent.
Function runPalThread() as Void
' Used for the player life cycle loop.
m.top.endThread = False
port = CreateObject("roMessagePort")
End Function
]]>
</script>
</component>
处理 Nonce 请求
创建 nonceLoader 后，您需要将一个观察器附加到 requestNonce 字段来处理 Nonce 请求。通过仅在 nonceLoader 初始化后附加此观察器，您可以确保在 SDK 线程中处理 Nonce 请求，并且只有在存在有效的 nonceLoader 时才能发出 Nonce 请求。
components/PALInterface.xml
...
' Starts the player event loop. This loop only terminates when "endThread" is sent.
Function runPalThread() as Void
' Used for the player life cycle loop.
m.top.endThread = False
port = CreateObject("roMessagePort")
' Now that the nonceLoader exists, begin listening for nonce requests.
m.top.observeField("requestNonce", m.port)
End Function
' Requests a nonce from the PAL SDK.
Function requestNonce() as Void
nonceRequest = m.sdk.CreateNonceRequest()
m.nonceManager = m.nonceLoader.loadNonceManager(nonceRequest)
m.top.nonce = nonceManager.getNonce()
End Function
]]>
</script>
</component>
收集存储意见征求信息
NonceRequest.storageAllowed 的默认值为 true，但您在征得适当的意见后可以更改此值。getConsentToStorage() 方法是您自己用于征求用户同意的方法的占位符，您可以通过集成 CMP 或基于其他方法来处理存储权限同意。
components/PALInterface.xml
...
<script type = "text/brightscript">
<![CDATA[
Library "IMA3.brs"
Sub init()
' It is not possible to access roUrlTransfer on the main thread. Setting
' functionName to a function and then setting control to "RUN" causes that
'function to run on a separate thread.
m.top.functionName = "runPalThread"
' Loads the SDK on the current thread if it is not yet loaded.
' This blocks execution of other functions on this thread until the SDK is loaded.
If m.sdk = Invalid
m.sdk = new_imaSdk()
End If
m.isConsentToStorage = getConsentToStorage()
m.nonceLoader = m.sdk.CreateNonceLoader()
End Sub
...
' Requests a nonce from the PAL SDK.
Function requestNonce() as Void
nonceRequest = m.sdk.CreateNonceRequest()
' Include changes to storage consent here.
nonceRequest.storageAllowed = m.isConsentToStorage
m.nonceManager = m.nonceLoader.loadNonceManager(nonceRequest)
m.top.nonce = nonceManager.getNonce()
End Function
监听播放器生命周期信号
为了让 PAL 集成能够正确发送信号，您需要设置一个循环来监听播放器的生命周期信号。
components/PALInterface.xml
...
' Now that the nonceLoader exists, begin listening for nonce requests.
m.top.observeField("requestNonce", m.port)
m.top.observeField("sendAdClick", m.port)
m.top.observeField("sendAdTouchKey", m.port)
m.top.observeField("sendPlaybackStart", m.port)
m.top.observeField("sendPlaybackEnd", m.port)
' Setting endThread to true causes the while loop to exit.
m.top.observeField("endThread", m.port)
While Not m.top.endThread
message = m.port.waitMessage(1000)
If message = Invalid
pollManager()
Else If message.getField() = "requestNonce" And m.top.requestNonce = True
requestNonce()
m.top.requestNonce = False
Else If message.getField() = "sendAdClick" And m.top.sendAdClick = True
sendAdClick()
m.top.sendAdClick = False
Else If message.getField() = "sendAdTouchKey" And m.top.sendAdTouchKey <> ""
sendAdTouch(m.top.sendAdTouchKey)
m.top.sendAdTouchKey = ""
Else If message.getField() = "sendPlaybackStart" And m.top.sendPlaybackStart = True
sendPlaybackStart()
m.top.sendPlaybackStart = False
Else If message.getField() = "sendPlaybackEnd" And m.top.sendPlaybackEnd = True
sendPlaybackEnd()
m.top.sendPlaybackEnd = False
End If
End While
End Function
Function pollManager() as Void
If m.nonceManager <> Invalid
m.nonceManager.poll()
End If
End Function
' Requests a nonce from the PAL SDK.
Function requestNonce() as Void
nonceRequest = m.sdk.CreateNonceRequest()
m.nonceManager = m.nonceLoader.loadNonceManager(nonceRequest)
m.top.nonce = nonceManager.getNonce()
End Function
]]>
</script>
</component>
为 sendPlaybackStart、sendPlaybackEnd、sendAdClick 和 sendAdTouch 注册监听器
接下来，在“video player start”上调用 sendPlaybackStart。此方法会开始对 Google 服务器进行异步调用，以收集 IVT 监控和检测所需的信号。在播放结束时调用 sendPlaybackEnd。调用 sendAdClick 以响应广告点击。然后，针对非点击型用户轻触或点击事件调用 sendAdTouch。
components/PALInterface.xml
...
' Requests a nonce from the IMA SDK.
Function requestNonce() as Void
nonceRequest = m.sdk.CreateNonceRequest()
m.nonceManager = m.nonceLoader.loadNonceManager(nonceRequest)
m.top.nonce = nonceManager.getNonce()
End Function
' Registers an ad click using the IMA SDK.
Function sendAdClick() as Void
If m.nonceManager <> Invalid
m.nonceManager.sendAdClick()
End If
End Function
' Registers an ad touch event using the IMA SDK.
Function sendAdTouch(touch as String) as Void
If m.nonceManager <> Invalid
m.nonceManager.sendAdTouch(touch)
End If
End Function
' Registers the start of playback using the IMA SDK.
Function sendPlaybackStart() as Void
If m.nonceManager <> Invalid
m.nonceManager.sendPlaybackStart()
End If
End Function
' Registers the end of playback using the IMA SDK.
Function sendPlaybackEnd() as Void
If m.nonceManager <> Invalid
m.nonceManager.sendPlaybackEnd()
End If
End Function
]]>
</script>
</component>
将 Nonce 附加到广告请求中
如需在正式版应用中使用您从 PAL 库收到的 Nonce，请仅在生成 Nonce 后发起广告请求。然后，使用 u_paln 参数将 Nonce 附加到广告代码。
components/MainScene.xml
...
' Callback triggered when Nonce is loaded.
Sub onNonceLoaded(message as Object)
nonce = m.sdkTask.nonce
print "onNonceLoaded ";nonce
makeAdRequest(nonce)
End Sub
Sub makeAdRequest(nonce)
' Sample ad tag URL used in this sample. Your apps method of getting this
' URL will likely be different.
adTag = "https://pubads.g.doubleclick.net/gampad/ads?iu=/124319096/external/single_ad_samples"
preparedTag = adTag + "&u_paln=" + nonce
' Implement custom ad request logic here.
Print "ad tag with nonce ";preparedTag
End Sub
...
大功告成！现在，您的 Roku 应用可以请求 PAL Nonce 并向 PAL SDK 注册播放会话事件。
（可选）通过第三方广告服务器发送 Google Ad Manager 信号
配置第三方广告服务器向 Ad Manager 发出的请求。
配置第三方广告服务器，以便在服务器向 Ad Manager 发出的请求中添加 Nonce。以下是第三方广告服务器中配置的广告代码示例：
'https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...'
如需了解详情，请参阅 Google Ad Manager 服务器端实现指南。
Ad Manager 会查找 givn= 以识别 Nonce 值。第三方广告服务器需要支持自己的某些宏（例如 %%custom_key_for_google_nonce%%），并将其替换为您在上一步中提供的 Nonce 查询参数。如需详细了解如何实现此目的，请参阅第三方广告服务器的文档。
大功告成！现在，您应该已将 Nonce 参数从 PAL SDK 传播到中间服务器，然后再传播到 Google Ad Manager。这样，您就可以通过 Google Ad Manager 更好地创收。