افزودن پشتیبانی آگهی‌های همپا

ممکن است بخواهید جایگاه‌های آگهی HTML درون‌صفحه‌ای خود را با جایگاه‌های آگهی ویدیویی یا رونهاد مرتبط کنید. این رابطه بین جای آگهی‌های منسوب به‌عنوان رابطه اصلی-همراه شناخته می‌شود.

علاوه‌بر درخواست آگهی‌های ویدیویی و رونهاد اصلی، می‌توانید از «کیت توسعه نرم‌افزار IMA» برای نمایش آگهی‌های HTML همراه استفاده کنید. این آگهی‌ها در محیط HTML نمایش داده می‌شوند

استفاده از آگهی‌های همپا

برای استفاده از آگهی‌های همراه، مراحل زیر را انجام دهید:

۱. آگهی‌های همپای خود را رزرو کنید

ابتدا باید آگهی‌های همراهی را که می‌خواهید با آگهی‌های اصلی‌تان نمایش داده شود رزرو کنید. آگهی‌های همراه را می‌توان در Ad Manager جاری‌سازی کرد. می‌توانید حداکثر شش آگهی همراه برای هر آگهی اصلی ارائه دهید. این تکنیک، زمانی که یک خریدار واحد همه آگهی‌های صفحه را کنترل می‌کند، به عنوان roadblocking نیز شناخته می‌شود.

۲. درخواست آگهی‌های همپا

به‌طور پیش‌فرض، آگهی‌های همپا برای هر درخواست آگهی فعال هستند.

۳. نمایش آگهی‌های همپای تصویری

دو روش برای ارائه آگهی‌های همراه وجود دارد:

• به‌طور خودکار بااستفاده از «برچسب ناشر Google» (GPT).

  اگر از GPT برای پیاده‌سازی آگهی‌های همراه خود استفاده می‌کنید، این آگهی‌ها به‌طور خودکار نمایش داده می‌شوند، به شرطی که جایگاه‌های آگهی همراه در صفحه HTML تعریف شده باشند و این آگهی‌ها در API ثبت شده باشند (یعنی div ID در JavaScript و HTML باید مطابقت داشته باشند). برخی‌از مزایای استفاده از GPT عبارت‌اند از:

  • آگاهی از جایگاه همراه.
  • اگر پاسخ VAST حاوی آگهی‌های همراه کمتری نسبت به جایگاه‌های تعریف‌شده در صفحه HTML باشد، پر کردن مجدد همراه از شبکه ناشر انجام می‌شود.
  • تکمیل خودکار همراه درصورت نبودن آگهی ویدیویی.
  • جایگاه‌های آگهی همراه پیش‌بارگذاری‌شده برای پخش‌کننده‌های ویدیو پخش‌باکلیک.
  • پردازش همراه خودکارسازی‌شده، شامل HTMLResource و iFrameResource.

• به‌صورت دستی بااستفاده از Ad API.

استفاده از آگهی‌های همراه با «برچسب ناشر Google»

«برچسب ناشر Google»‏ (GPT) نمایش آگهی‌های همراه HTML را در سایت شما خودکار می‌کند. توصیه می‌کنیم که اکثر ناشران از GPT استفاده کنند. اگر GPT در صفحه وب اصلی (نه در IFrame) بار شده باشد، «کیت توسعه نرم‌افزار HTML5» جایگاه‌های GPT را تشخیص می‌دهد. می‌توانید اطلاعات دقیق‌تر درباره استفاده از GPT با کیت توسعه نرم‌افزار IMA را در اسناد GPT پیدا کنید.

اگر کیت توسعه نرم‌افزار HTML5 را در IFrame میزبانی کنید

اگر هر دو معیار زیر را دارید، باید یک اسکریپت پراکسی اضافی اضافه کنید تا همراهان GPT شما به‌درستی نمایش داده شوند:

1. کیت توسعه نرم‌افزار HTML5 را در IFrame بار کنید.
2. ‫GPT را در صفحه وب اصلی (خارج از IFrame) بار کنید.

برای اینکه همراهان شما در این سناریو نمایش داده شوند، باید پیش‌از بار کردن کیت توسعه نرم‌افزار، نوشتار پراکسی GPT را بار کنید:

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

نکات مهمی که باید به‌خاطر داشته باشید:

• هیچ GPT نباید در IFrame بارگیری‌کننده «کیت توسعه نرم‌افزار» بار شود.
• ‫GPT باید در صفحه بالایی بار شود، نه در IFrame دیگر.
• دستورگان پراکسی باید در همان چارچوب GPT بار شود (یعنی در صفحه اصلی).

جایگاه‌های آگهی همراه را در HTML اعلام کنید

این بخش توضیح می‌دهد که چگونه آگهی‌های همراه را در HTML بااستفاده از GPT اعلام کنید و کد نمونه برای سناریوهای مختلف ارائه می‌دهد. برای HTML5 SDK، باید مقداری جاوا اسکریپت به صفحه HTML خود اضافه کنید و جایگاه‌های آگهی همراه را اعلام کنید.

• مثال ۱: پیاده‌سازی جایگاه آگهی پایه
• مثال ۲: پیاده‌سازی جایگاه آگهی پویا
• مثال ۳: جای آگهی پیش‌بارگذاری‌شده

مثال ۱: پیاده‌سازی جایگاه آگهی پایه

کد نمونه زیر نشان می‌دهد که چگونه فایل gpt.js را در صفحه HTML خود بگنجانید و یک جایگاه آگهی را اعلام کنید. جایگاه آگهی اعلام‌شده ‎۷۲۸x۹۰ پیکسل است. ‫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 زیر را ببینید.

مثال ۲: پیاده‌سازی جایگاه آگهی پویا

گاهی ممکن است تا زمانی که محتوای صفحه ارائه نشود، ندانید چند جایگاه آگهی در صفحه دارید. کد نمونه زیر نحوه تعریف جای آگهی را در حین پرداز زدن صفحه نشان می‌دهد. این مثال با مثال ۱ یکسان است با این تفاوت که جایگاه‌های آگهی را در جایی که واقعاً نمایش داده می‌شوند ثبت می‌کند.

<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>

امتحان کنید

می‌توانید کد زیر را برای پیاده‌سازی کارا ببینید.

مثال ۳: جایگاه‌های آگهی پیش‌بارگذاری‌شده

در برخی موارد، ممکن است لازم باشد قبل‌از درخواست آگهی همراه، چیزی را در جایگاه آگهی نمایش دهید. آگهی‌های همراه معمولاً همراه با آگهی ویدیویی درخواست می‌شوند. این درخواست می‌تواند پس‌از بار شدن صفحه رخ دهد. برای مثال، آگهی همراه ممکن است فقط پس‌از اینکه کاربر روی ویدیو کلیک‌کردنی کلیک کرد بار شود. در چنین موردی، باید بتوانید قبل‌از درخواست آگهی همراه، آگهی معمولی درخواست کنید تا جایگاه آگهی را پر کند. برای پشتیبانی از این مورد استفاده، می‌توانید آگهی‌های وب استاندارد را در جایگاه همراه نمایش دهید. مطمئن شوید که آگهی‌های وب برای جایگاه‌های همراه هدف‌یابی شده‌اند. می‌توانید جایگاه‌های همراه را به همان روشی که جایگاه‌های آگهی وب استاندارد را هدف‌یابی می‌کنید، هدف‌یابی کنید.

در اینجا نمونه‌ای از پیاده‌سازی که در بالا توضیح داده شد آورده شده است:

<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>

امتحان کنید

برای پیاده‌سازی کارا می‌توانید کد-قلم زیر را ببینید.

استفاده از آگهی‌های همراه با Ad API

این بخش نحوه نمایش آگهی‌های همراه بااستفاده از Ad API را توضیح می‌دهد.

نمایش آگهی‌های همپا

برای نمایش آگهی‌های همراه، ابتدا ازطریق هریک از رویدادهای AdEvent ارسال‌شده از AdsManager، مرجعی به شیء Ad دریافت کنید. توصیه می‌کنیم از رویداد AdEvent.STARTED استفاده کنید، زیرا نمایش آگهی‌های همراه باید با نمایش آگهی اصلی هم‌زمان باشد.

سپس، از این شیء Ad برای فراخوانی getCompanionAds() استفاده کنید تا آرایه‌ای از اشیاء CompanionAd را دریافت کنید. در اینجا می‌توانید CompanionAdSelectionSettings را مشخص کنید که به شما امکان می‌دهد فیلترهایی را روی آگهی‌های همراه برای نوع خلاقانه، درصد مطابقت نزدیک، نوع منبع، و معیارهای اندازه تنظیم کنید. برای اطلاعات بیشتر درباره این تنظیمات، به مستندات IMA CompanionAdSelectionSettings API مراجعه کنید.

اکنون می‌توان از CompanionAd شیء برگشتی از getCompanionAds برای نمایش آگهی‌های همراه در صفحه بااستفاده از این رهنمودها استفاده کرد:

1. جایگاه آگهی همراه <div> با اندازه موردنیاز در صفحه ایجاد کنید.
2. در مدیر رویداد برای رویداد STARTED ، شیء Ad را با فراخوانی getAd() بازیابی کنید.
3. از getCompanionAds() استفاده کنید تا فهرستی از آگهی‌های همراه دریافت کنید که هم با اندازه جای آگهی همراه مطابقت داشته باشند و هم CompanionAdSelectionSettings و شماره ترتیب یکسانی با عنصر خلاقانه اصلی داشته باشند. خلاقانه‌ای که مشخصه توالی نداشته باشد به‌عنوان دارای شماره توالی ۰ درنظر گرفته می‌شود.
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>

نمایش آگهی‌های همپای روان تصویری

‫IMA اکنون از آگهی‌های همراه جاری پشتیبانی می‌کند. این آگهی‌های همراه می‌توانند تغییر اندازه دهند تا با اندازه جای آگهی مطابقت داشته باشند. ‫٪۱۰۰ عرض بخش div والد را پر می‌کند، سپس ارتفاع خود را تغییر می‌دهد تا با محتوای آگهی همراه مطابقت داشته باشد. این‌ها بااستفاده از اندازه همراه Fluid در Ad Manager تنظیم می‌شوند. برای اینکه بدانید این مقدار را کجا تنظیم کنید، تصویر زیر را ببینید.

همراهان سیال 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>