إتاحة الإعلانات المصاحبة

اختيار النظام الأساسي: HTML5 Android iOS

ننصحك بربط خانات إعلانات HTML داخل الصفحة بخانات إعلانات الفيديو أو الإعلانات على شكل طبقات. يُشار إلى هذه العلاقة بين مواضع الإعلانات المرتبطة باسم علاقة الإعلان الرئيسي والإعلان المرافق.

بالإضافة إلى طلب الإعلانات الرئيسية على الفيديو والإعلانات الرئيسية على شكل طبقات، يمكنك استخدام حزمة IMA SDK لعرض إعلانات HTML المصاحبة. يتم عرض هذه الإعلانات ضمن بيئة HTML.

استخدام الإعلانات المصاحبة

لاستخدام الإعلانات المصاحبة، اتّبِع الخطوات التالية:

1. حجز إعلاناتك المصاحبة

عليك أولاً حجز الإعلانات المصاحبة التي تريد عرضها مع إعلاناتك الرئيسية. يمكن عرض الإعلانات المصاحبة في "مدير إعلانات Google". يمكنك عرض ما يصل إلى ستة إعلانات مصاحبة لكل إعلان رئيسي. تُعرف هذه التقنية، التي يتحكّم فيها مشترٍ واحد في جميع الإعلانات على الصفحة، أيضًا باسم حظر الإعلانات المتزامنة.

2. طلب الإعلانات المصاحبة

يتم تلقائيًا تفعيل الإعلانات المصاحبة لكل طلب عرض إعلان.

3- عرض الإعلانات المصاحبة الصورية

هناك طريقتان لعرض الإعلانات المصاحبة:

  • تلقائيًا باستخدام "علامة ناشر Google"‏ (GPT)

    في حال استخدام GPT لتنفيذ الإعلانات المصاحبة، سيتم عرضها تلقائيًا ما دامت هناك خانات إعلانات مصاحبة معرَّفة في صفحة HTML وتم تسجيل هذه الإعلانات باستخدام واجهة برمجة التطبيقات (أي يجب أن يتطابق معرّف div في JavaScript وHTML). تتضمّن مزايا استخدام مكتبة "علامة ناشر Google" ما يلي:

    • الوعي بموضع الإعلان المصاحب
    • ملء المساحة الإعلانية بإعلانات بانر مصاحبة من شبكة الناشر، إذا كان ردّ VAST يتضمّن عددًا من إعلانات البانر المصاحبة أقل من عدد المساحات الإعلانية المحدّدة في صفحة HTML
    • الملء التلقائي للإعلان المصاحب إذا كان إعلان الفيديو غير متوفّر
    • خانات الإعلانات المصاحبة المحمَّلة مسبقًا لمشغّلات الفيديو التي تتطلّب النقر لتشغيلها
    • عرض الإعلانات المصاحبة آليًا، بما في ذلك HTMLResource وiFrameResource

  • يدويًا باستخدام Ad API

استخدام الإعلانات المصاحبة مع "علامة الناشر من Google"

تتولّى "علامة ناشر Google" (المعروفة بالاختصار GPT) عرض الإعلانات المصاحبة بتنسيق HTML تلقائيًا على موقعك الإلكتروني. ننصح معظم الناشرين باستخدام GPT. تتعرّف حزمة تطوير البرامج (SDK) المستندة إلى HTML5 على خانات علامة GPT إذا تم تحميل علامة GPT على صفحة الويب الرئيسية (وليس في إطار iframe). يمكنك العثور على معلومات أكثر تفصيلاً حول استخدام GPT مع حزمة IMA SDK في مستندات GPT.

إذا كنت تستضيف حزمة تطوير البرامج (SDK) بتنسيق HTML5 ضِمن إطار IFrame

إذا استوفيت المعيارَين التاليَين، عليك تضمين نص برمجي إضافي للخادم الوكيل لكي يتم عرض الإعلانات المصاحبة في GPT بشكل صحيح:

  1. حمِّل حزمة تطوير البرامج HTML5 SDK في إطار iframe.
  2. تحميل GPT على صفحة الويب الرئيسية (خارج إطار IFrame)

لعرض الإعلانات المصاحبة في هذا السيناريو، يجب تحميل نص GPT الوكيل قبل تحميل حزمة تطوير البرامج (SDK):

<script src="https://imasdk.googleapis.com/js/sdkloader/gpt_proxy.js"></script>

بعض النقاط المهمة الواجب مراعاتها:

  • يجب عدم تحميل GPT داخل إطار IFrame الذي يحمّل حزمة تطوير البرامج (SDK).
  • يجب تحميل GPT على الصفحة الرئيسية، وليس في إطار iframe آخر.
  • يجب تحميل النص البرمجي للوكيل في الإطار نفسه الذي يتم فيه تحميل GPT (أي على الصفحة الرئيسية).

تحديد خانات الإعلانات المصاحبة في HTML

يوضّح هذا القسم كيفية تعريف الإعلانات المصاحبة في HTML باستخدام GPT، ويقدّم نموذجًا للرمز البرمجي لسيناريوهات مختلفة. بالنسبة إلى حزمة تطوير البرامج (SDK) لـ HTML5، عليك إضافة بعض JavaScript إلى صفحة HTML وتحديد الخانات الإعلانية المصاحبة.

المثال 1: عملية تنفيذ بسيطة لخانة الإعلان

يوضّح نموذج الرمز التالي كيفية تضمين ملف gpt.js في صفحة HTML وتحديد موضع إعلان. الخانة الإعلانية المحدّدة هي ‎728x90 بكسل. تحاول GPT ملء المساحة الإعلانية بأي إعلانات مصاحبة يتم عرضها في استجابة VAST وتتطابق مع هذا الحجم. بعد تعريف مواضع الإعلانات، يمكن للدالة googletag.display() عرضها في أي مكان يتم استدعاؤها فيه على الصفحة. بما أنّ الخانات هي خانات إعلانية مصاحبة، لا يتم عرض الإعلانات على الفور. بدلاً من ذلك، تظهر هذه الإعلانات إلى جانب إعلان الفيديو الرئيسي.

في ما يلي مثال على التنفيذ:

<html>
  <head>
    <!-- Uncomment the line below for the HTML5 SDK caveat proxy -->
    <!--<script src="https://imasdk.googleapis.com/js/sdkloader/gpt_proxy.js"></script>-->
    <!-- HEAD part -->
    <!-- Initialize the tagging library -->
    <script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>

    <!-- Register your companion slots -->
    <script>
       window.googletag = window.googletag || { cmd: [] };

       googletag.cmd.push(function() {
         // Supply YOUR_NETWORK and YOUR_UNIT_PATH.
         googletag.defineSlot('/YOUR_NETWORK/YOUR_UNIT_PATH', [728, 90], 'companionDiv')
             .addService(googletag.companionAds())
             .addService(googletag.pubads());
         googletag.companionAds().setRefreshUnfilledSlots(true);
         googletag.pubads().enableVideoAds();
         googletag.enableServices();
       });
    </script>
  </head>

  <body>
    <!-- BODY part -->
    <!-- Declare a div where you want the companion to appear. Use
          googletag.display() to make sure the ad is displayed. -->
    <div id="companionDiv" style="width:728px; height:90px;">
      <script>
         // Using the command queue to enable asynchronous loading.
         // The unit does not actually display now - it displays when
         // the video player is displaying the ads.
         googletag.cmd.push(function() { googletag.display('companionDiv'); });
      </script>
    </div>
  <body>
</html>

للتجربة:

يمكنك الاطّلاع على codepen التالي لمعرفة طريقة التنفيذ.

المثال 2: تنفيذ خانة الإعلان الديناميكية

في بعض الأحيان، قد لا تعرف عدد مساحات عرض الإعلانات المتوفّرة في الصفحة إلى أن يتم عرض محتوى الصفحة. يوضّح نموذج الرمز البرمجي التالي كيفية تحديد مواضع الإعلانات أثناء عرض الصفحة. هذا المثال مطابق للمثال 1 باستثناء أنّه يسجّل مواضع الإعلانات التي يتم عرضها فيها فعليًا.

<html>
  <head>
    <!-- Uncomment the line below for the HTML5 SDK caveat proxy -->
    <!-- <script src="https://imasdk.googleapis.com/js/sdkloader/gpt_proxy.js"></script> -->
    <script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
    <!-- HEAD part -->
    <!-- Initialize the tagging library -->
    <script>
      window.googletag = window.googletag || { cmd: [] };

      googletag.cmd.push(function() {
        googletag.companionAds().setRefreshUnfilledSlots(true);
        googletag.pubads().enableVideoAds();
        googletag.enableServices();
      });
    </script>
  </head>

  <body>
    <!-- BODY part -->
    <!-- Declare a div where you want the companion to appear. Use
        googletag.display() to make sure the ad is displayed. -->
    <div id="companionDiv" style="width:728px; height:90px;">
      <script>
        // Using the command queue to enable asynchronous loading.
        // The unit does not actually display now - it displays when
        // the video player is displaying the ads.
        googletag.cmd.push(function() {
          // Supply YOUR_NETWORK and YOUR_UNIT_PATH.
          googletag.defineSlot('/YOUR_NETWORK/YOUR_UNIT_PATH', [728, 90], 'companionDiv')
              .addService(googletag.companionAds())
              .addService(googletag.pubads());
          googletag.display('companionDiv');
        });
      </script>
    </div>
  <body>
</html>

للتجربة:

يمكنك الاطّلاع على الرمز التالي لتنفيذ عملية ناجحة.

المثال 3: مواضع الإعلانات المحمَّلة مسبقًا

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

في ما يلي مثال على عملية التنفيذ الموضّحة أعلاه:

<html>
  <head>
    ...
    <!-- Register your companion slots -->
    <script>
      window.googletag = window.googletag || { cmd: [] };

      googletag.cmd.push(function() {
        // Supply YOUR_PRELOAD_NETWORK and YOUR_PRELOAD_UNIT_PATH.
        googletag.defineSlot('/YOUR_PRELOAD_NETWORK/YOUR_PRELOAD_UNIT_PATH', [728, 90], 'companionDiv')
            .addService(googletag.companionAds())
            .addService(googletag.pubads());
        googletag.companionAds().setRefreshUnfilledSlots(true);
        googletag.pubads().enableVideoAds();
        googletag.enableServices();
      });
    </script>
  </head>
  ...
</html>

للتجربة:

يمكنك الاطّلاع على CodePen التالي لمعرفة كيفية تنفيذ ذلك.

استخدام الإعلانات المصاحبة مع Ad API

يوضّح هذا القسم كيفية عرض الإعلانات المصاحبة باستخدام واجهة برمجة التطبيقات Ad.

عرض الإعلانات المصاحبة الصورية

لعرض الإعلانات المصاحبة، يجب أولاً الحصول على مرجع إلى عنصر Ad من خلال أي من أحداث AdEvent التي يتم إرسالها من AdsManager. ننصحك باستخدام الحدث AdEvent.STARTED، لأنّ عرض الإعلانات المصاحبة يجب أن يتزامن مع عرض الإعلان الرئيسي.

بعد ذلك، استخدِم عنصر Ad هذا لاستدعاء getCompanionAds() للحصول على مصفوفة من عناصر CompanionAd. يتوفّر لك هنا خيار تحديد CompanionAdSelectionSettings، ما يتيح لك ضبط فلاتر على الإعلانات المصاحبة حسب نوع التصميم ونسبة التطابق التقريبي ونوع المرجع ومعايير الحجم. لمزيد من المعلومات حول هذه الإعدادات، يُرجى الاطّلاع على مستندات IMA CompanionAdSelectionSettings API.

يمكن الآن استخدام عناصر CompanionAd التي تعرضها الدالة getCompanionAds لعرض الإعلانات المصاحبة على الصفحة باتّباع الإرشادات التالية:

  1. أنشئ خانة إعلانية مصاحبة <div> بالحجم المطلوب على الصفحة.
  2. في معالج الأحداث الخاص بالحدث STARTED، استرجِع الكائن Ad من خلال استدعاء getAd().
  3. استخدِم getCompanionAds() للحصول على قائمة بالإعلانات المصاحبة التي تتطابق مع حجم خانة الإعلان المصاحب و CompanionAdSelectionSettings وتتضمّن رقم التسلسل نفسه الخاص بتصميم الإعلان الرئيسي. يتم التعامل مع المواد الإبداعية التي لا تتضمّن سمة التسلسل على أنّ رقم التسلسل الخاص بها هو 0.
  4. احصل على المحتوى من مثيل CompanionAd واضبطه على أنّه HTML الداخلي لـ <div> في موضع الإعلان هذا.

نموذج الرموز البرمجية

<!--Set a companion ad div in html page. -->
<div id="companion-ad-300-250" width="300" height="250"></div>

<script>

  // Listen to the STARTED event.
  adsManager.addEventListener(
    google.ima.AdEvent.Type.STARTED,
    onAdEvent);

  function onAdEvent(adEvent) {
    switch (adEvent.type) {
      case google.ima.AdEvent.Type.STARTED:
        // Get the ad from the event.
        var ad = adEvent.getAd();
        var selectionCriteria = new google.ima.CompanionAdSelectionSettings();
        selectionCriteria.resourceType = google.ima.CompanionAdSelectionSettings.ResourceType.STATIC;
        selectionCriteria.creativeType = google.ima.CompanionAdSelectionSettings.CreativeType.IMAGE;
        selectionCriteria.sizeCriteria = google.ima.CompanionAdSelectionSettings.SizeCriteria.IGNORE;
        // Get a list of companion ads for an ad slot size and CompanionAdSelectionSettings
        var companionAds = ad.getCompanionAds(300, 250, selectionCriteria);
        var companionAd = companionAds[0];
        // Get HTML content from the companion ad.
        var content = companionAd.getContent();
        // Write the content to the companion ad slot.
        var div = document.getElementById('companion-ad-300-250');
        div.innerHTML = content;
        break;
    }
  }
</script>

عرض الإعلانات المصاحبة المرنة

تتيح حزمة تطوير البرامج (SDK) الخاصة بـ IMA الآن إعلانات بانر مصاحبة مرنة. يمكن تغيير حجم هذه الإعلانات المصاحبة ليتطابق مع حجم مساحة الإعلان. وتشغل هذه الإعلانات% 100 من عرض العنصر div الرئيسي، ثم يتم تغيير ارتفاعها ليناسب محتوى الإعلان المرافق. يتم ضبطها باستخدام حجم Fluid الإعلان المرافق في "مدير إعلانات Google". راجِع الصورة التالية لمعرفة مكان ضبط هذه القيمة.

صورة تعرض إعدادات الإعلان المرافق في &quot;مدير إعلانات Google&quot; توضّح هذه الصورة خيار أحجام الإعلانات المصاحبة.

إعلانات مصاحبة مرنة في GPT

عند استخدام إعلانات مصاحبة في GPT، يمكنك تحديد موضع إعلان مصاحب مرن من خلال تعديل المَعلمة الثانية لطريقة defineSlot().

<!-- Register your companion slots -->
<script>
  googletag.cmd.push(function() {
    // Supply YOUR_NETWORK and YOUR_UNIT_PATH.
    googletag.defineSlot('/YOUR_NETWORK/YOUR_UNIT_PATH', ['fluid'], 'companionDiv')
        .addService(googletag.companionAds())
        .addService(googletag.pubads());
    googletag.companionAds().setRefreshUnfilledSlots(true);
    googletag.pubads().enableVideoAds();
    googletag.enableServices();
  });
</script>

الإعلانات المصاحبة المرنة في Ad API

عند استخدام Ad API لعرض إعلانات مصاحبة، يمكنك تحديد خانة إعلان مصاحب مرنة من خلال تعديل google.ima.CompanionAdSelectionSettings.SizeCriteria إلى القيمة SELECT_FLUID.

<script>

  ...
    // Get the ad from the event.
    var ad = adEvent.getAd();
    var selectionCriteria = new google.ima.CompanionAdSelectionSettings();
    selectionCriteria.resourceType = google.ima.CompanionAdSelectionSettings.ResourceType.STATIC;
    selectionCriteria.creativeType = google.ima.CompanionAdSelectionSettings.CreativeType.IMAGE;
    selectionCriteria.sizeCriteria = google.ima.CompanionAdSelectionSettings.SizeCriteria.SELECT_FLUID;
    // Get a list of companion ads for an ad slot size and CompanionAdSelectionSettings
    // Note: Companion width and height are irrelevant when fluid size is used.
    var companionAds = ad.getCompanionAds(0, 0, selectionCriteria);
    var companionAd = companionAds[0];
  ...
    }
  }
</script>