תחילת העבודה עם LG

במדריך הזה נסביר איך לשלב את PAL SDK באפליקציית LG webOS, לשלוח בקשה לערך חד-פעמי ולרשום חשיפות של מודעות.

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

לפני שמתחילים להשתמש במדריך הזה, צריך ליצור אפליקציית webOS בסיסית של LG. אפשר להשתמש ב-webOS CLI או ב-webOS Studio כדי להגדיר את האפליקציה. פרטים נוספים זמינים במדריך ליצירת האפליקציה הראשונה.

יצירת מספר חד-פעמי

‫Nonce הוא מחרוזת מוצפנת יחידה שנוצרת על ידי PAL באמצעות NonceLoader. בכל בקשה חדשה להצגת סטרימינג באמצעות PAL SDK, צריך לצרף ערך חדש של nonce שנוצר. עם זאת, אפשר לעשות שימוש חוזר בערכי nonce לכמה בקשות להצגת מודעות באותו הסטרימינג.

כשיוצרים אפליקציה באמצעות webOS CLI או webOS Studio, נוצר קובץ HTML שכולל את התלות webOSTV.js. כדי ש-PAL יפעל, נדרש התלות הזה. מידע נוסף זמין במאמרי העזרה בנושא webOSTV.js.

מוסיפים תלות ב-CTV PAL SDK לקובץ index.html. טוענים את תג הסקריפט אחרי תג הסקריפט של webOSTV.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">
  <meta name="description" content="LG app for PAL sdk"/>
  <title>LG app for PAL sdk</title>
  <link rel="stylesheet" href="style.css"/>
  <script src="path/to/webOSTVjs/webOSTV.js" charset="utf-8"></script>
  <script src="https://imasdk.googleapis.com/pal/sdkloader/pal_ctv.js"></script>
  <script src="app.js"></script>
</head>
<body>
  <header>
    <hgroup>
      <h1>LG app for PAL sdk</h1>
    </hgroup>
  </header>
  <div id="placeholder-video"></div>
</body>
</html>

לאחר מכן, יוצרים קובץ 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() {
  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();
  });

  // PAL automatically determines whether limited ads apply based on the TCF
  // data found on the page. You can optionally use the `forceLimitedAds`
  // parameter to manually enable limited ads regardless of the TCF data.
  const consentSettings = new goog.pal.ConsentSettings();

  nonceLoader = new goog.ctv.pal.NonceLoader(consentSettings);

  generateNonce();
}

/**
 * Generates a nonce with sample arguments.
 *
 * 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);
        
      })

אם אתם שולחים בקשות להצגת מודעות מ-Google ומציגים אותן, אתם חייבים להציג את הסמל ואת שכבת העל של AdChoices.

מעקב אחרי אירועי הפעלה

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

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

מגדירים את שרת המודעות של הצד השלישי כך שיכלול את המספר האקראי בבקשה של השרת אל 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 אמור להתפשט מ-PAL SDK, דרך השרתים המתווכים שלכם, ואז אל Google Ad Manager. כך אפשר לשפר את המונטיזציה באמצעות Google Ad Manager.