بدء استخدام LG

يتضمّن هذا الدليل دمج حزمة PAL SDK في تطبيق LG webOS، وطلب رقم خاص، وتسجيل مرّات ظهور الإعلانات.

المتطلبات الأساسية

قبل البدء في هذا الدليل، أنشئ تطبيقًا أساسيًا على LG webOS. يمكنك استخدام إما webOS CLI أو webOS Studio لإعداد التطبيق. لمزيد من التفاصيل، راجِع دليل إنشاء تطبيقك الأول.

إنشاء رقم خاص

"الرقم الخاص" هو سلسلة مشفّرة واحدة يتم إنشاؤها بواسطة PAL باستخدام NonceLoader. تتطلّب حزمة تطوير البرامج (SDK) الخاصة بـ PAL أن يكون كل طلب بث جديد مصحوبًا برقم عشوائي جديد تم إنشاؤه. ومع ذلك، يمكن إعادة استخدام الأرقام العشوائية لطلبات إعلانات متعددة ضمن البث نفسه.

عند إنشاء تطبيق باستخدام webOS CLI أو webOS Studio، يتم إنشاء ملف HTML يتضمّن التبعية webOSTV.js. تتطلّب ميزة PAL توفّر هذه الاعتمادية لكي تعمل. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات webOSTV.js.

أدرِج ملحقًا لحزمة تطوير البرامج (SDK) الخاصة بـ PAL على أجهزة التلفزيون المتصلة في ملف 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 لإنشاء رقم خاص. تتضمّن هذه الخطوة سير عمل PAL لإنشاء NonceLoader، ثم إنشاء NonceRequest، ثم طلب قيمة عشوائية باستخدام 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();
});

إرفاق الرقم الخاص بطلب عرض الإعلان

لاستخدام الرقم الخاص الذي تم إنشاؤه، ألحِق علامة الإعلان بمَعلمة 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);
        
      })

إذا كنت تطلب إعلانات وتعرضها من 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" من خلال خوادم إعلانات خارجية

اضبط طلب خادم الإعلانات التابع لجهة خارجية في "إدارة إعلانات Google".

اضبط خادم الإعلانات من جهة خارجية لتضمين الرقم الخاص في طلب الخادم إلى &quot;إدارة الإعلانات&quot;. في ما يلي مثال على علامة إعلان تم إعدادها داخل خادم إعلانات من جهة خارجية:

'https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...'

لمزيد من التفاصيل، اطّلِع على دليل تنفيذ &quot;مدير إعلانات Google&quot; من جهة الخادم.

يبحث "مدير إعلانات Google" عن givn= لتحديد قيمة الرقم العشوائي. يجب أن يتيح خادم الإعلانات التابع لجهة خارجية استخدام بعض وحدات الماكرو الخاصة به، مثل %%custom_key_for_google_nonce%%، وأن يستبدلها بمَعلمة طلب البحث الخاصة برقم الاستخدام لمرة واحدة التي قدّمتها في الخطوة السابقة. يجب أن تتوفّر معلومات إضافية حول كيفية تنفيذ ذلك في مستندات خادم الإعلانات التابع لجهة خارجية.

هذا كل شيء! من المفترض أن تكون قد تمكّنت الآن من نشر مَعلمة nonce من PAL SDK، من خلال خوادمك الوسيطة، ثم إلى إدارة إعلانات Google. يتيح ذلك تحقيق الربح بشكل أفضل من خلال &quot;مدير إعلانات Google&quot;.