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

پلاتفرم را انتخاب کنید: HTML5 Android iOS

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

توجه: وقتی از Google Interactive Media Ads SDK برای ارائه آگهی استفاده می‌کنید، سنجه‌های گزارش‌شده به سرور آگهی ممکن است شامل این باشد که آیا بازدیدکننده با صفحه‌ای که آگهی‌ها در آن ارائه شده‌اند تعامل داشته است یا نه. برای رعایت کردن الزامات شفاف‌سازی جمع‌آوری و استفاده از داده‌ها در قراردادتان با Google، باید این موضوع را به بازدیدکنندگان خود اطلاع دهید.

اگر کیت توسعه نرم‌افزار 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، باید مقداری جاوا اسکریپت به صفحه HTML خود اضافه کنید و جایگاه‌های آگهی همپا را اعلام کنید.

توجه: در هریک از مثال‌های زیر، حتماً network و unit-path معتبری را در فراخوانی روش googletag.defineSlot (واقع در برچسب <head> یا <body>، بسته به مثال واقعی که استفاده می‌کنید) ارائه دهید.

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

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

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

امتحان کنید

برای پیاده‌سازی درحال کار، می‌توانید code-pen زیر را ببینید.

استفاده از آگهی‌های همپا با 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>