כדי לראות אפליקציה לדוגמה שמשתמשת ב-PAL כדי ליצור צופן חד-פעמי (nonce), אפשר להוריד את הדוגמה של CTV סמסונג Tizen מ-GitHub.
במדריך הזה נסביר איך לשלב את PAL SDK באפליקציית סמסונג Tizen, לבקש צופן חד-פעמי (nonce) ולרשום חשיפות של מודעות.
דרישות מוקדמות
לפני שמתחילים להשתמש במדריך הזה, צריך ליצור אפליקציית Tizen בסיסית. אפשר להשתמש ב-Tizen IDE כדי להגדיר את האפליקציה. מידע נוסף זמין בסרטון הזה בנושא תחילת העבודה עם Tizen.
יצירת צופן חד-פעמי
Nonce הוא מחרוזת מוצפנת יחידה שנוצרת על ידי PAL באמצעות NonceLoader.
ב-PAL SDK, כל בקשה חדשה לסטרימינג צריכה לכלול ערך חדש של nonce. עם זאת, יכול להיות שיהיה שימוש חוזר בערכי Nonce בכמה בקשות להצגת מודעות באותו הזרם.
יוצרים קובץ HTML לאפליקציה. כוללים את התלות webapis.js בקובץ ה-HTML. התלות הזו נדרשת כדי ש-PAL יפעל. מידע נוסף זמין במסמכי התיעוד של Samsung WebApi.
כוללים תלות ב-SDK של PAL ל-CTV בקובץ index.html. טוענים את תג הסקריפט אחרי תג הסקריפט של webapis.js. לדוגמה, אפשר לעיין בקובץ index.html הבא.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
<script src="$WEBAPIS/webapis/webapis.js"></script>
<script src="//imasdk.googleapis.com/pal/sdkloader/pal_ctv.js"></script>
<script src="app.js"></script>
</head>
<body>
<header>
<hgroup>
<h1>Samsung Tizen app for PAL sdk</h1>
</hgroup>
</header>
<div id="placeholder-video"></div>
</body>
</html>
כדי שאותות הספאם של PAL יפעלו בצורה תקינה, נדרשות הרשאות מסוימות ב-Tizen. יוצרים קובץ config.xml עם הצהרות ההרשאות הבאות:
"http://tizen.org/privilege/internet""http://tizen.org/privilege/system""http://tizen.org/privilege/telephony""http://tizen.org/privilege/tv.inputdevice""http://developer.samsung.com/privilege/network.public""http://developer.samsung.com/privilege/productinfo"
ראו את קטע הקוד הבא לדוגמה config.xml:
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns:tizen="http://tizen.org/ns/widgets" xmlns="http://www.w3.org/ns/widgets" id="http://yourdomain/BasicProject" version="1.0.0" viewmodes="maximized">
<tizen:application id="PACKAGE_STRING.BasicProject" package="PACKAGE_STRING" required_version="2.3"/>
<content src="index.html"/>
<feature name="http://tizen.org/feature/screen.size.normal.1080.1920"/>
<icon src="icon.png"/>
<tizen:metadata key="http://tizen.org/metadata/app_ui_type/base_screen_resolution" value="extensive"/>
<name>BasicProject</name>
<tizen:privilege name="http://tizen.org/privilege/internet"/>
<tizen:privilege name="http://tizen.org/privilege/system"/>
<tizen:privilege name="http://tizen.org/privilege/telephony"/>
<tizen:privilege name='http://tizen.org/privilege/tv.inputdevice'/>
<tizen:privilege name="http://developer.samsung.com/privilege/network.public"/>
<tizen:privilege name="http://developer.samsung.com/privilege/productinfo"/>
<tizen:profile name="tv-samsung"/>
<tizen:setting screen-orientation="landscape" context-menu="enable" background-support="disable" encryption="disable" install-location="auto" hwkey-event="enable"/>
<access origin="*" subdomains="true"/>
</widget>
לאחר מכן, יוצרים קובץ JavaScript כדי ליצור צופן חד-פעמי (nonce). השלב הזה כולל את תהליך העבודה של PAL ליצירת NonceLoader, יצירת NonceRequest ואז שליחת בקשה לצופן חד-פעמי (nonce) באמצעות NonceLoader.loadNonceManager().
let videoElement;
let nonceLoader;
let managerPromise;
let nonceManager;
let playbackStarted = false;
/**
* Initializes the PAL loader.
*/
function init() {
const videoElement = document.getElementById('placeholder-video');
videoElement.addEventListener('mousedown', onVideoTouch);
videoElement.addEventListener('touchstart', onVideoTouch);
videoElement.addEventListener('play', function() {
if (!playbackStarted) {
sendPlaybackStart();
playbackStarted = true;
}
});
videoElement.addEventListener('ended', sendPlaybackEnd);
videoElement.addEventListener('error', function() {
// Handle video error.
sendPlaybackEnd();
});
// The default value for the `allowStorage` parameter is false. You must
// set this value to true to let PAL determine whether limited ads applies
// based on the TCF data. You can optionlly use the `forceLimitedAds`
// parameter to enable limited ads regardless of the TCF data.
const consentSettings = new goog.pal.ConsentSettings();
consentSettings.allowStorage = true;
nonceLoader = new goog.ctv.pal.NonceLoader(consentSettings);
generateNonce();
}
/**
* Generates a nonce with sample arguments and logs it to the console.
*
* The NonceRequest parameters set here are example parameters.
* You should set your parameters based on your own app characteristics.
*/
function generateNonce() {
const request = new goog.ctv.pal.NonceRequest();
request.adWillAutoPlay = true;
request.adWillPlayMuted = false;
request.continuousPlayback = false;
request.descriptionUrl = 'https://example.com';
request.iconsSupported = true;
request.playerType = 'Sample Player Type';
request.playerVersion = '1.0';
request.ppid = 'Sample PPID';
request.sessionId = 'Sample SID';
// Player support for VPAID 2.0, OMID 1.0, and SIMID 1.1
request.supportedApiFrameworks = '2,7,9';
request.url = 'https://developers.google.com/ad-manager/pal/ctv';
request.videoHeight = 480;
request.videoWidth = 640;
managerPromise = nonceLoader.loadNonceManager(request);
managerPromise
.then(function(manager) {
nonceManager = manager;
})
.catch((error) => {
// Handle nonce generating error.
});
}
window.addEventListener("load", function(event) {
init();
});
צירוף ערך ה-nonce לבקשה להצגת מודעה
כדי להשתמש בערך ה-nonce שנוצר, צריך לצרף את פרמטר givn עם ערך ה-nonce לתג המודעה לפני שליחת בקשות להצגת מודעות.
/**
* The ad tag for your ad request, for example:
* https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=
*
* For more sample ad tags, see https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/tags
*/
const DEFAULT_AD_TAG = "Your ad tag";
...
managerPromise = nonceLoader.loadNonceManager(request);
managerPromise
.then(function(manager) {
nonceManager = manager;
// Append the nonce to the ad tag URL.
makeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
})
מעקב אחר אירועי הפעלה
לבסוף, צריך להטמיע כמה גורמים מטפלים באירועים עבור הנגן. לצורך בדיקה, אפשר לצרף אותם לאירועי לחיצה על לחצן, אבל בהטמעה אמיתית, הם יופעלו על ידי אירועים מתאימים של הנגן:
/**
* Informs PAL that an ad click has occurred. How this function is
* called will vary depending on your ad implementation.
*/
function sendAdClick() {
if (nonceManager) {
nonceManager.sendAdClick();
}
}
/**
* Handles the user touching on the video element, passing it to PAL.
* @param {!TouchEvent|!MouseEvent} touchEvent
*/
function onVideoTouch(touchEvent) {
if (nonceManager) {
nonceManager.sendAdTouch(touchEvent);
}
}
/** Informs PAL that playback has started. */
function sendPlaybackStart() {
if (nonceManager) {
nonceManager.sendPlaybackStart();
}
}
/** Informs PAL that playback has ended. */
function sendPlaybackEnd() {
if (nonceManager) {
nonceManager.sendPlaybackEnd();
}
}
בהטמעה שלכם, צריך לקרוא ל-sendPlaybackStart ברגע שמפעילים את הסרטון. צריך לקרוא לשיטה sendPlaybackEnd ברגע שסשן ההפעלה של הסרטון מסתיים. sendAdClick צריכה להיקרא בכל פעם שהצופה לוחץ על מודעה. sendAdTouch צריך להפעיל את הפונקציה הזו בכל אינטראקציה של מגע עם נגן.
(אופציונלי) שליחת אותות של Google Ad Manager דרך שרתי מודעות של צד שלישי
מגדירים את הבקשה של שרת המודעות של הצד השלישי ל-Ad Manager.
מגדירים את שרת המודעות של הצד השלישי כך שיכלול את ה-nonce בבקשה של השרת אל Ad Manager. דוגמה לתג מודעה שהוגדר בשרת מודעות של צד שלישי:
'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.