תחילת העבודה עם Tizen (Samsung)

כדי לראות אפליקציה לדוגמה שמשתמשת ב-PAL ליצירת צופן חד-פעמי, צריך להוריד את ה-CTV (Tizen) דוגמה מ- GitHub.

מדריך זה משלב את PAL SDK באפליקציית Samsung (Tizen), חד-פעמיות, ולרשום חשיפות של מודעות.

דרישות מוקדמות

לפני שתתחילו את המדריך הזה, עליכם ליצור אפליקציית Tizen בסיסית. אפשר להשתמש בסביבת הפיתוח המשולבת Tizen IDE כדי להגדיר את האפליקציה. צפייה בסרטון הזה ב- איך מתחילים לעבוד עם Tizen אפשר לקבל מידע נוסף.

יצירת קוד חד-פעמי (nonce)

"אף" היא מחרוזת מוצפנת יחידה שנוצרה על ידי PAL באמצעות הפקודה NonceLoader. ב-PAL SDK נדרש שהבקשה החדשה להעברת הנתונים תכלול קוד חד-פעמי (nonce) שנוצר לאחרונה. עם זאת, אפשר לעשות שימוש חוזר במספרים חד-פעמיים במספר בקשות להצגת מודעות באותו מקור.

יוצרים קובץ HTML לאפליקציה. צריך לכלול את התלות webapis.js ב- קובץ HTML. כדי ש-PAL יפעל, נדרשת התלות הזו. מידע נוסף זמין במאמר הבא: ה מסמכי תיעוד של Samsung WebApi

יש לכלול בקובץ index.html תלות של CTV PAL SDK. טען את תג סקריפט המעקב אחרי תג הסקריפט עבור 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>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 כדי ליצור קוד חד-פעמי. השלב הזה כולל את שיטת PAL תהליך עבודה של יצירת NonceLoader, יצירת NonceRequest, ואז מבקשים צופן חד-פעמי (nonce) באמצעות NonceLoader.loadNonceManager().

let videoElement;
let nonceLoader;
let managerPromise;
let nonceManager;
let storageConsent = true;
let playbackStarted = false;

/**
 * A placeholder for the publisher's own method of obtaining user
 * consent, either by integrating with a CMP or based on other
 * methods the publisher chooses to handle storage consent.
 * @return {boolean} Whether storage consent has been given.
 */
function getConsentToStorage() {
  return storageConsent;
}

/**
 * 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 `allowStorage` is false, but can be
  // changed once the appropriate consent has been gathered.
  const consentSettings = new goog.ctv.pal.ConsentSettings();
  consentSettings.allowStorage = getConsentToStorage();

  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) לבקשה להצגת מודעה

כדי להשתמש בצפנים חד-פעמיים שנוצרו, צריך להוסיף את תג המודעה לפרמטר givn ואת התג לפני שליחת בקשות להצגת מודעות.

  /**
   * 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 guide.

מערכת Ad Manager מחפשת את givn= כדי לזהות את ערך ה-nonce. המודעה של הצד השלישי השרת צריך לתמוך במאקרו מסוים משל עצמו, כמו %%custom_key_for_google_nonce%%, ומחליפים אותו בפרמטר השאילתה צופן חד-פעמי (nonce) שסיפקת בשלב הקודם. מידע נוסף על האופן שבו מבצעים את הפעולה הזו אמור להיות זמין במסמכי העזרה של שרת המודעות של הצד השלישי.

זהו! עכשיו הפרמטר nonce יופץ מ-PAL SDK. דרך השרתים המתווכים, ואז אל Google Ad Manager. הפעולה הזאת מאפשרת מונטיזציה משופרת באמצעות Google Ad Manager.