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

اختيار النظام الأساسي: 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 في إطار iframe.
  2. تحميل علامة "ناشر Google" على صفحة الويب الرئيسية (خارج إطار IFrame)

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

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

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

  • يجب عدم تحميل GPT داخل إطار IFrame الذي يحمّل حزمة تطوير البرامج.
  • يجب تحميل 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 في &quot;مدير الإعلانات&quot;. راجِع الصورة التالية لمعرفة مكان ضبط هذه القيمة.

صورة تعرض إعدادات الإعلان المرافق في &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>