Roku के लिए प्रोग्रामैटिक ऐक्सेस लाइब्रेरी (PAL) SDK, पब्लिशर को डायरेक्ट वीएएसटी कॉल (डीवीसी) की अनुमति देता है. इससे वे डीवीसी पर आधारित Roku ऐप्लिकेशन से कमाई कर सकते हैं. PAL SDK की मदद से, Google से नॉन्स का अनुरोध किया जा सकता है. नॉन्स, एन्क्रिप्ट की गई स्ट्रिंग होती हैं. इनकी मदद से, डीवीसी अनुरोधों पर हस्ताक्षर किए जा सकते हैं. हर नई स्ट्रीम के अनुरोध के साथ, नया जनरेट किया गया नॉन्स होना चाहिए. हालांकि, एक ही स्ट्रीम में एक से ज़्यादा विज्ञापन अनुरोधों के लिए, एक ही नॉन्स का फिर से इस्तेमाल किया जा सकता है.
इस गाइड में, Roku ऐप्लिकेशन में PAL SDK टूल को शामिल करने, नॉन्स का अनुरोध करने, और विज्ञापन इंप्रेशन को रजिस्टर करने का उदाहरण दिया गया है.
ज़रूरी शर्तें
इस गाइड को शुरू करने से पहले, आपको ये काम करने होंगे:
- 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>
टेस्ट इंटरफ़ेस बनाना
बटन के साथ एक सीन लागू करता है, ताकि ये काम किए जा सकें:
- नॉन्स का अनुरोध करें.
- विज्ञापन पर क्लिक भेजें.
- प्लेबैक शुरू होने का इवेंट भेजें.
- वीडियो चलाने की प्रोसेस खत्म होने का इवेंट भेजें.
- फ़ोकस को वीडियो बटन पर ले जाएं.
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>
नॉन्स अनुरोधों को प्रोसेस करना
nonceLoader
फ़ील्ड बनाने के बाद, आपको requestNonce
फ़ील्ड में ऑब्ज़र्वर अटैच करके, नॉन्स अनुरोधों को मैनेज करना होगा. nonceLoader
को शुरू करने के बाद ही इस ऑब्ज़र्वर को अटैच करके, यह पक्का किया जा सकता है कि SDK थ्रेड में नॉन्स अनुरोध मैनेज किए जाते हैं. साथ ही, यह भी पक्का किया जा सकता है कि नॉन्स अनुरोध सिर्फ़ तब किया जा सकता है, जब कोई मान्य nonceLoader
हो.
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()
तरीका, उपयोगकर्ता की सहमति लेने के लिए आपके तरीके का प्लेसहोल्डर है. यह तरीका, सीएमपी के साथ इंटिग्रेट करके या स्टोरेज की सहमति को मैनेज करने के अन्य तरीकों के आधार पर अपनाया जा सकता है.
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
के लिए दर्शकों को रजिस्टर करना
इसके बाद, "वीडियो प्लेयर शुरू करें" पर sendPlaybackStart
को कॉल करें. इस तरीके से, Google सर्वर को एक साथ कई कॉल भेजे जाते हैं. इससे, आईवीटी की निगरानी और पता लगाने के लिए ज़रूरी सिग्नल इकट्ठा किया जाता है. प्लेबैक खत्म होने पर, 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>
विज्ञापन अनुरोधों में नॉन्स अटैच करना
प्रोडक्शन ऐप्लिकेशन में PAL लाइब्रेरी से मिलने वाले नॉन्स का इस्तेमाल करने के लिए,
नॉन्स जनरेट होने के बाद ही विज्ञापन अनुरोध शुरू करें. इसके बाद, u_paln
पैरामीटर का इस्तेमाल करके, विज्ञापन टैग में नॉन्स जोड़ें.
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 के लिए, तीसरे पक्ष के विज्ञापन सर्वर के अनुरोध को कॉन्फ़िगर करें.
अपने तीसरे पक्ष के विज्ञापन सर्वर को कॉन्फ़िगर करें, ताकि वह Ad Manager को भेजे जाने वाले सर्वर के अनुरोध में नॉन्स शामिल कर सके. यहां तीसरे पक्ष के विज्ञापन सर्वर में कॉन्फ़िगर किए गए विज्ञापन टैग का उदाहरण दिया गया है:
'https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...'
ज़्यादा जानकारी के लिए, Google Ad Manager के सर्वर साइड लागू करने की गाइड देखें.
Ad Manager, नॉन्स वैल्यू की पहचान करने के लिए givn=
खोजता है. तीसरे पक्ष के विज्ञापन सर्वर को अपने कुछ मैक्रो, जैसे कि %%custom_key_for_google_nonce%%
के साथ काम करना होगा. साथ ही, इसे पिछले चरण में दिए गए नॉन्स क्वेरी पैरामीटर से बदलना होगा. ऐसा करने के तरीके के बारे में ज़्यादा जानकारी, तीसरे पक्ष के विज्ञापन सर्वर के दस्तावेज़ में उपलब्ध होनी चाहिए.
हो गया! अब आपके पास PAL SDK टूल से, इंटरमीडियरी सर्वर के ज़रिए, Google Ad Manager में भेजा गया नॉन्स पैरामीटर होना चाहिए. इससे, Google Ad Manager की मदद से बेहतर तरीके से कमाई की जा सकती है.