開始使用

警告： Roku 不會為實作 PAL SDK 的新版或現有 Roku 應用程式進行發布認證。我們預期 Roku 將在 2025 年停止支援 PAL SDK，這將影響您透過 Google 營利的情形。我們正在開發 Google Ad Manager 的替代方案，以便繼續傳遞必要的驗證信號，識別並消除 CTV 詐欺。如想加入封閉 Beta 版測試計畫，請與您的客戶經理聯絡。

Roku 的程式輔助存取權資料庫 (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
  

注意： images/ 資料夾是任何 Roku 應用程式的標準元件。您可以下載這個範例應用程式使用的完整圖片組合，或自行建立圖片，只要圖片的尺寸和檔案格式與範例圖片相符即可。

設定專案

您必須先設定專案檔案，才能整合 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>

建立測試介面

注意： 為了展示 PAL SDK 的功能，本範例會使用簡單的測試介面，觸發 SDK 的各種函式。在實際應用程式中，這些函式會因使用者互動或媒體事件而觸發。

實作含有按鈕的場景，以執行下列操作：

• 要求 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 隨機數值，並使用 PAL SDK 註冊播放工作階段事件。

(選用) 透過第三方廣告伺服器傳送 Google Ad Manager 信號

設定第三方廣告伺服器的 Ad Manager 請求。

注意：如果您使用多個第三方解決方案 (例如第三方 SSAI 伺服器呼叫其他第三方廣告伺服器)，請務必確保 PAL SDK 的加密 Nonce 會轉送給每個第三方。

請設定第三方廣告伺服器，在伺服器向 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 更有效地營利。