البدء

إنشاء رقم خاص

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

لإنشاء رقم عشوائي باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ PAL، أنشئ ملف HTML وأضِف ما يلي:

pal.html

<html>
<head></head>
<body>
  <div id="placeholder-video"></div>
  <button id="generate-nonce">Generate Nonce</button>
  <script src="//imasdk.googleapis.com/pal/sdkloader/pal.js"></script>
  <script src="pal.js"></script>
</body>
</html>

بعد ذلك، أنشِئ ملف JavaScript وأضِف ما يلي:

pal.js

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', (e) => void onVideoTouch(e));
  videoElement.addEventListener('touchstart', (e) => void onVideoTouch(e));
  videoElement.addEventListener('play', () => {
    if (!playbackStarted) {
      sendPlaybackStart();
      playbackStarted = true;
    }
  });
  videoElement.addEventListener('ended', () => void sendPlaybackEnd());
  videoElement.addEventListener('error', () => {
    console.log("Video error: " + videoElement.error.message);
    sendPlaybackEnd();
  });

  document.getElementById('generate-nonce')
      .addEventListener('click', generateNonce);

  // 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.pal.NonceLoader(consentSettings);
}

/**
 * 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.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/html5';
  request.videoHeight = 480;
  request.videoWidth = 640;

  managerPromise = nonceLoader.loadNonceManager(request);
  managerPromise
      .then((manager) => {
        nonceManager = manager;
        console.log('Nonce generated: ' + manager.getNonce());
      })
      .catch((error) => {
        console.log('Error generating nonce: ' + error);
      });
}

init();

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

لاستخدام الرقم الخاص الذي تم إنشاؤه، ألحِق علامة الإعلان بمَعلمة givn وقيمة الرقم الخاص، وذلك قبل إرسال طلبات عرض الإعلانات.

pal.js

  /**
   * 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((manager) => {
        nonceManager = manager;
        console.log('Nonce generated: ' + manager.getNonce());
        
        // Append the nonce to the ad tag URL.
        makeAdRequest(DEFAULT_AD_TAG + "&givn=" + nonceString);
      })

إذا كنت تطلب إعلانات وتعرضها من Google، عليك عرض رمز AdChoices والتراكب. للحصول على تفاصيل حول تحليل استجابة VAST وعرض الرموز، يُرجى الاطّلاع على رمز "خيارات الإعلان" والتراكب.

تتبُّع أحداث التشغيل

أخيرًا، عليك تنفيذ معالجات أحداث مختلفة للمشغّل. لأغراض الاختبار، يمكنك ربط هذه الأحداث بأحداث النقر على الأزرار، ولكن في عملية التنفيذ الفعلية، سيتم تشغيلها من خلال أحداث المشغّل المناسبة:

pal.js

/**
 * Informs PAL that an ad click has occurred. How this function is
 * called will vary depending on your ad implementation.
 */
function sendAdClick() {
  nonceManager?.sendAdClick();
}

/**
 * Handles the user touching on the video element, passing it to PAL.
 * @param {!TouchEvent|!MouseEvent} touchEvent
 */
function onVideoTouch(touchEvent) {
  nonceManager?.sendAdTouch(touchEvent);
}

/** Informs PAL that playback has started. */
function sendPlaybackStart() {
  nonceManager?.sendPlaybackStart();
}

/** Informs PAL that playback has ended. */
function sendPlaybackEnd() {
  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;.