توسعه آداپتور مناقصه

این راهنما برای شبکه‌های تبلیغاتی در نظر گرفته شده است که به دنبال ساخت آداپتور مناقصه به منظور شرکت در مناقصه بی‌درنگ (RTB) در میانجی‌گری Google هستند. اگر ناشر هستید، دستورالعمل‌های میانجی‌گری ناشر را ببینید.

آداپتور مناقصه بخش سمت مشتری از ادغام است. آداپتور SDK شبکه تبلیغات شما را قادر می‌سازد تا با Google Mobile Ads SDK ارتباط برقرار کند تا تبلیغات ارائه شده توسط پیشنهاد دهنده شما را بارگیری کند.

برای اینکه مناقصه به درستی کار کند، آداپتور شما نیاز به تنظیم اولیه، جمع‌آوری سیگنال‌ها، بارگذاری تبلیغات، و انتقال رویدادهای چرخه عمر تبلیغات دارد. در این راهنما به شما توضیح خواهیم داد که چگونه آداپتور شما باید برای انجام این عملیات اجرا شود.

توجه: شرکت در مناقصه همچنین مستلزم پیشنهاد دهنده ای است که بتواند به درخواست های OpenRTB پاسخ دهد. دستورالعمل های مربوط به نحوه ایستادن در مناقصه خارج از محدوده این راهنما است.

گردش کار آداپتور مناقصه

مقدار دهی اولیه

یک جریان دقیق از کل چرخه عمر درخواست-پاسخ- رندر یک آداپتور در زیر نشان داده شده است:

آداپتور مسئول بخش های زیر از گردش کار است:

• مراحل 4-7: آداپتور خود را راه‌اندازی کنید و پس از تکمیل اولیه، Google Mobile Ads SDK را فراخوانی کنید.

• مراحل 10-13: سیگنال‌ها را از SDK شبکه تبلیغاتی خود جمع‌آوری کنید تا برای شرکت در درخواست RTB به پیشنهاد دهنده ارسال شود و آنها را به Google Mobile Ads SDK ارسال کنید.

• مراحل 18-21: اگر پیشنهاد دهنده شما پیشنهاد برنده را برگرداند، آگهی را مطابق با پاسخ پیشنهاد دهنده بارگیری کنید. پس از بارگیری، به Google Mobile Ads SDK اطلاع دهید که تبلیغ بارگیری شده است.

• مرحله 23 و بعد از آن: زمانی که تبلیغ شما نمایش داده می شود، SDK تبلیغات موبایلی Google را از رویدادهای نمایش و کلیک و همچنین سایر رویدادهای تبلیغاتی که در طول چرخه نمایش تبلیغات شما رخ می دهد، مطلع کنید.

توجه: Google Mobile Ads SDK رویدادهای نمایش را به طور جداگانه ردیابی می کند، اما همچنین مهم است که رویداد نمایش شبکه تبلیغاتی خود را فوروارد کنید تا بتوانیم مغایرت ها را بررسی کنیم.

پیاده سازی آداپتور مناقصه

برای ایجاد یک آداپتور مناقصه برای Google Mobile Ads SDK، باید کلاس انتزاعی RtbAdapter را گسترش دهید. بخش‌های زیر هر روش انتزاعی را در RtbAdapter توضیح می‌دهند.

getSDKVersionInfo()

در اینجا باید نسخه SDK خود را برگردانید. این نسخه به عنوان بخشی از درخواست OpenRTB به پیشنهاد دهنده شما ارسال می شود.

این روش از شما می خواهد که یک VersionInfo را برگردانید. مثال زیر نشان می دهد که چگونه می توانید نسخه رشته ای SDK خود را به VersionInfo.

@Override
public VersionInfo getSDKVersionInfo() {
  // Get your SDK's version as a string. E.g. "1.2.3"
  // String versionString = YourSdk.getVersion();
  String splits[] = versionString.split("\\.");
  if (splits.length >= 3) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]);
      return new VersionInfo(major, minor, micro);
   }

   String logMessage = String.format("Unexpected SDK version format: %s." +
           "Returning 0.0.0 for SDK version.", sdkVersion);
   Log.w(TAG, logMessage);
   return new VersionInfo(0, 0, 0);
}

getVersionInfo()

در اینجا باید نسخه آداپتور خود را برگردانید. این نسخه به عنوان بخشی از درخواست OpenRTB به پیشنهاد دهنده شما ارسال می شود.

آداپتورهای منبع باز و نسخه شده Google از طرح نسخه آداپتور 4 رقمی استفاده می کنند، اما VersionInfo فقط 3 رقم را مجاز می کند. برای حل این مشکل، توصیه می‌شود مانند شکل زیر، دو رقم آخر را در نسخه پچ ترکیب کنید.

@Override
public VersionInfo getVersionInfo() {
  // Get your adapters's version as a string. E.g. "1.2.3.0"
  String versionString = BuildConfig.VERSION_NAME;
  String splits[] = versionString.split("\\.");
  if (splits.length >= 4) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
      return new VersionInfo(major, minor, micro);
    }

    String logMessage = String.format("Unexpected adapter version format: %s." +
                "Returning 0.0.0 for adapter version.", versionString);
    Log.w(TAG, logMessage);
    return new VersionInfo(0, 0, 0);
}

مقداردهی اولیه ()

تایم اوت: 30 ثانیه

متد initialize() اولین روشی است که در آداپتور شما فراخوانی شده است. در هر جلسه فقط یک بار فراخوانی می شود. این روش فهرستی از اشیاء MediationConfiguration را در اختیار شما قرار می دهد که نشان دهنده لیست کامل مکان های موجود در این برنامه است که برای شبکه تبلیغاتی شما پیکربندی شده اند. می‌توانید از طریق این فهرست، اعتبارنامه‌های هر مکان را تجزیه کنید و داده‌های مربوطه را برای مقداردهی اولیه به SDK خود ارسال کنید.

هنگامی که SDK شما مقداردهی اولیه شد و برای دریافت درخواست های تبلیغاتی آماده شد، متد onInitializationSucceeded() از InitializationCompleteCallback را فراخوانی کنید. این تماس برگشتی به ناشران برنامه ارسال می‌شود تا بدانند می‌توانند بارگیری تبلیغات را شروع کنند.

نکته: متد initialize() در یک نمونه از یک آداپتور فراخوانی می شود. هیچ روش دیگری در این نمونه خاص فراخوانی نخواهد شد. اگر آداپتور شما در نتیجه این روش نیاز به ذخیره حالت داشته باشد، هر حالتی باید ثابت باشد.

@Override
public void initialize(Context context,
    InitializationCompleteCallback initializationCompleteCallback,
    List<MediationConfiguration> mediationConfigurations) {
  // Initialize your ad network's SDK.
  ...

  // Invoke the InitializationCompleteCallback once initialization completes.
  initializationCompleteCallback.onInitializationSucceeded();
}

collectSignals()

تایم اوت: 1 ثانیه

هر بار که ناشر درخواست تبلیغ می کند، یک نمونه جدید از RtbAdapter شما ایجاد می شود و متد collectSignals() فراخوانی می شود. این نمونه از RtbAdapter برای مدت زمان درخواست تبلیغ، پاسخ، و چرخه حیات رندر آن تبلیغ استفاده خواهد شد. متد collectSignals() آداپتور شما را قادر می‌سازد تا سیگنال‌هایی را از دستگاه ارائه کند تا در یک درخواست OpenRTB به پیشنهاد دهنده شما ارسال شود.

collectSignals() روی یک رشته پس زمینه فراخوانی می شود. Google Mobile Ads SDK به طور همزمان از همه آداپتورهای شرکت کننده در مناقصه سیگنال می خواهد. لطفاً محترمانه رفتار کنید و در این مدت تماس‌ها را به رشته رابط کاربری محدود کنید. هر کار سنگینی که آداپتور یا SDK شما برای جمع‌آوری سیگنال‌ها باید انجام دهد، باید در متد initialize() انجام شود و در حافظه پنهان ذخیره شود.

هنگامی که سیگنال‌های خود را آماده کردید، با سیگنال‌های کدگذاری شده، callback onSuccess() را فراخوانی کنید.

در اینجا یک نمونه پیاده سازی آورده شده است:

@Override
public void collectSignals(RtbSignalData rtbSignalData,
                           SignalCallbacks signalCallbacks) {
  String signals = YourSdk.getSignals();
  signalCallbacks.onSuccess(signals);
}

اگر آداپتور شما نتوانست سیگنال‌ها را جمع‌آوری کند، signalCallbacks.onFailure() را با رشته‌ای که خطای رخ داده را توضیح می‌دهد تماس بگیرید.

توجه: رشته سیگنال می تواند هر شیئی را نشان دهد و می تواند در هر قالبی باشد، مانند JSON ساده، Base64 رمزگذاری شده، یا هر شکل دیگری از رمزگذاری که شما انتخاب می کنید. رمزگذاری سیگنال ها برای اطمینان از اینکه سیگنال ها در خارج از شبکه شما مات هستند توصیه می شود.

پیاده سازی روش های بارگذاری تبلیغات

تایم اوت: 10 ثانیه

اگر پیشنهاد دهنده شما پیشنهاد برنده را برگرداند، Google Mobile Ads SDK با آداپتور شما تماس می گیرد تا آگهی برنده را بارگیری کند و هر داده ای را که پیشنهاد دهنده شما برگردانده است و SDK شما برای بارگیری آن تبلیغ نیاز دارد، در اختیار شما قرار می دهد.

روش دقیق بارگذاری که فراخوانی می شود بستگی به قالب تبلیغی دارد که این درخواست برای آن است:

فرمت تبلیغات	روش بارگذاری
بنر	loadBannerAd()
بینابینی	loadInterstitialAd()
پاداش داده شد	loadRewardedAd()

این روش‌ها را برای قالب‌های تبلیغاتی که آداپتور شما پشتیبانی می‌کند، اجرا کنید.

روش بارگذاری در رشته UI، در همان نمونه آداپتوری که سیگنال‌ها را از آن ارائه کرده‌اید، فراخوانی می‌شود. این روش پارامترهای زیر را در اختیار شما قرار می دهد:

• یک MediationAdConfiguration که شامل پارامترهایی است که SDK شما برای بارگیری آگهی برای پیشنهاد برنده نیاز دارد، مانند پاسخ پیشنهاد و هر گونه اعتباری که ناشر در رابط کاربری AdMob پیکربندی کرده است.

• یک شی MediationAdLoadCallback که برای اطلاع دادن به SDK تبلیغات موبایلی Google در هنگام بارگیری موفق یا ناموفق استفاده می شود.

هنگامی که SDK شما آگهی را بارگیری کرد، با mediationAdLoadCallback.onSuccess() تماس بگیرید. در صورتی که بارگیری آگهی با شکست مواجه شد، mediationAdLoadCallback.onFailure() را با رشته ای که خطای رخ داده را توضیح می دهد فراخوانی کنید.

متد mediationAdLoadCallback.onSuccess() مستلزم آن است که یک شی را که به یکی از واسط های «آگهی» تعریف شده توسط Google Mobile Ads SDK تأیید می کند، ارسال کنید. این رابط‌های تبلیغاتی از شما می‌خواهند اطلاعاتی در مورد آگهی ارائه دهید.

MediationAdConfiguration همچنین دارای یک متد getWatermark() برای برگرداندن یک رشته کدگذاری شده با base64 است که یک تصویر PNG را نشان می دهد. این تصویر باید در یک پوشش شفاف روی تبلیغات شما کاشی شود. برای راهنمایی بیشتر در مورد نحوه ارائه واترمارک با Google تماس بگیرید. این شامل ابرداده در مورد آگهی است که برای استفاده توسط ناشران برای تعیین منبع تبلیغات نشان داده شده است.

برای بنرها، از شما خواسته می شود نمای بنر را ارائه دهید. برای تبلیغات بینابینی و دارای پاداش، از شما خواسته می شود که یک متد show() پیاده سازی کنید تا تبلیغ را در زمان بعدی نشان دهید. به عنوان بهترین روش، توصیه می کنیم کلاس خود را که بارگذاری تبلیغات را انجام می دهد، مسئول اجرای این روش های تبلیغاتی نیز باشد.

در زیر نمونه ای از پیاده سازی loadBannerAd() آورده شده است. به خاطر داشته باشید که اجرای آداپتور شما متفاوت به نظر می رسد، زیرا آداپتور شما با یک SDK متفاوت ادغام می شود.

public final class SampleRtbAdapter extends RtbAdapter {
  ...

  @Override
  public void loadBannerAd(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> callback) {

      SampleBannerRenderer bannerRenderer =
          new SampleBannerRenderer(adConfiguration, callback);
      bannerRenderer.render();
    }
}

// Renders a banner ad, and forwards callbacks to the Google Mobile Ads SDK.
public class SampleBannerRenderer implements MediationBannerAd {
  private MediationBannerAdConfiguration adConfiguration;
  private final MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback;
  private AdView adView;
  private MediationBannerAdCallback callback;

  public SampleRtbBannerRenderer(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback) {
    this.adConfiguration = adConfiguration;
    this.adLoadCallback = adLoadCallback;
  }

  public void render() {
    adView = new AdView(adConfiguration.getContext());
    adView.setAdSize(adConfiguration.getAdSize());
    // serverParameters are the parameters entered in the AdMob UI for your network.
    adView.setAdUnitId(adConfiguration.getServerParameters().getString("adUnitId"));

    // Map the callbacks from your SDK to Google's SDK.
    adView.setAdListener(new AdListener() {
      // See the next step for more information on callback mapping.
      // ...
    });

    // Get the bid response and watermark from the ad configuration and
    // pass the relevant information to your SDK.
    String ad = adConfiguration.getBidResponse();
    String watermark = adConfiguration.getWatermark();
    Bundle extras = new Bundle();
    extras.putString("bid", ad);
    extras.putString("watermark", watermark);
    AdRequest request = new AdRequest.Builder()
        .addNetworkExtrasBundle(AdMobAdapter.class, extras)
        .build();
    adView.loadAd(request);
  }

  // MediationBannerAd implementation

  @NonNull
  @Override
  public View getView() {
    return adView;
  }
}

رویدادهای چرخه عمر ارائه تبلیغات را رله کنید

مسئولیت نهایی آداپتور این است که Google Mobile Ads SDK را از رویدادهای چرخه عمر ارائه مطلع کند تا بتوان آنها را به ناشر بازارسال کرد. ناشر انتظار دارد این تماس‌ها در زمان‌های خاصی انجام شود، مهم نیست که کدام شبکه تبلیغاتی تبلیغ را ارائه می‌کند، بنابراین مهم است که تا حد امکان و در زمان مناسب از این تماس‌ها فراخوانی شود تا Google Mobile Ads SDK بتواند آنها را به ناشر ارسال کند. .

آداپتورها در صورت لزوم باید رویدادهای زیر را فراخوانی کنند:

مشترک برای همه فرمت ها
روش	چه زمانی تماس بگیرید
reportAdClicked()	تبلیغ کلیک شد.
reportAdImpression()	این آگهی تاثیری بر جای گذاشت.
onAdOpened()	این تبلیغ یک نمای تمام صفحه را ارائه کرد.
onAdClosed()	نمای تمام صفحه آگهی بسته شده است.
onAdLeftApplication()	این تبلیغ باعث شد تا کاربر برنامه را ترک کند.
تبلیغات با پاداش
onRewarded()	به کاربر جایزه تعلق می گیرد.
تماس های ویدیویی (تبلیغات با پاداش و بومی)
onVideoStarted()	ویدیوی تبلیغ شروع شد.
onVideoCompleted()	ویدیوی آگهی تکمیل شد.

آداپتور یک شی MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> را پس از فراخوانی mediationAdLoadCallback.onSuccess() دریافت می کند. از آداپتورها انتظار می رود که روی این شیء نگه دارند و از آن برای فراخوانی رویدادهای ارائه که در تبلیغ شما رخ می دهند استفاده کنند.

به طور معمول، بیشتر این رویدادها توسط SDK شبکه تبلیغاتی شما هدایت می شوند. نقش آداپتور صرفاً ترسیم تماس‌های برگشتی از SDK شبکه تبلیغاتی شما به Google Mobile Ads SDK است.

مثال زیر نشان می‌دهد که چگونه پاسخ‌های تماس را از شنونده تبلیغات SDK خود به Google Mobile Ads SDK بازارسال می‌کنید:

adView.setAdListener(new AdListener() {
    public void onAdLoaded() {
        callback = adLoadCallback.onSuccess(SampleBannerRenderer.this);
    }

    public void onAdImpression() {
        if (callback != null) {
            callback.reportAdImpression();
        }
    }

    public void onAdFailedToLoad(LoadAdError adError) {
        adLoadCallback.onFailure("Error: " + adError.toString());
    }

    public void onAdClosed() {
        if (callback != null) {
            callback.onAdClosed();
        }
    }

    public void onAdOpened() {
        if (callback != null) {
            callback.onAdOpened();
            callback.reportAdClicked();
        }
    }

    public void onAdLeftApplication() {
        if (callback != null) {
            callback.onAdLeftApplication();
        }
    }
});

دارایی های مورد نیاز برای ردیابی نمایش تبلیغات بومی

وقتی 1 پیکسل از تبلیغ قابل مشاهده باشد، SDK تبلیغات موبایل Google یک نمایش برای یک آگهی بومی ثبت می‌کند. اگر SDK شبکه تبلیغاتی شما نیاز به نمایش دارایی‌های خاصی دارد تا نمایش معتبری ارائه کند، پیشنهاد دهنده شما می‌تواند این دارایی‌های بومی مورد نیاز را در پاسخ پیشنهادی نشان دهد. سپس Google Mobile Ads SDK تأیید می‌کند که دارایی‌های بومی مورد نیاز شما قبل از ثبت یک نمایش نمایش داده می‌شوند.

برای اطلاعات بیشتر در مورد نحوه تعیین دارایی های مورد نیاز اضافی در پاسخ پیشنهاد، به اسناد دارایی های مورد نیاز بومی مراجعه کنید.

نکته کلیدی: هر گونه نمایشی که به دلیل دارایی های اضافی مورد نیاز شبکه تبلیغاتی شما نامعتبر شود، بر نسبت رویداد قابل پرداخت شما برای آن ناشر تأثیر می گذارد.

نمایش خطاهای تبلیغاتی

برای فرمت های تمام صفحه، مانند تبلیغات بینابینی و پاداش، در بارگذاری موفقیت آمیز پاسخ به تماس، پیاده سازیMediationInterstitialAd یا MediationRewardedAdبه طوری که Google Mobile Ads SDK بتواند از آداپتور شما بخواهد که تبلیغ را نشان دهد.

Google Mobile Ads SDK انتظار دارد که اگر یک آداپتور با موفقیت یک تبلیغ را بارگیری کرد، زمانی که ناشر درخواست نمایش آن را می‌دهد، آگهی آماده نمایش است. این بدان معنی است که هر تماس نمایشی باید به یک برداشت منجر شود.

با این حال، ممکن است مواردی وجود داشته باشد که نتوانید تبلیغی را نشان دهید. اگر نمی توانید آگهی را نشان دهید، با این شماره تماس بگیریدonAdFailedToShow()برای لغو برداشت.

جدول زیر نشان می‌دهد که چگونه فراخوان‌های ارائه بر روی ضبط نمایش برای قالب‌های تبلیغات تمام صفحه تأثیر می‌گذارند:

پاسخ به تماس	نتیجه
onAdOpened()	Impression recorded
onAdFailedToShow()	Impression failure ^1
هیچ کدام از موارد بالا برای چند ثانیه وجود ندارد	Impression recorded

¹ برای نمایش های ناموفق، شبکه تبلیغاتی شما برای نمایش هزینه ای دریافت نمی کند، اما بر تنظیم نرخ رویداد قابل پرداخت شما تأثیر می گذارد. برای اطلاعات بیشتر به سیگنال های درخواست پیشنهاد مراجعه کنید.

مثال ساختگی زیر چرخه عمر بارگذاری/نمایش را نشان می‌دهد که در آن تماس نمایش آگهی ممکن است منجر به شکست شود.

final class SampleRtbAdapter extends RtbAdapter implements MediationRewardedAd {

 private MediationRewardedAdCallback callback;
 private RewardedAd rewardedAd;

 ...

  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration adConfiguration,
      final MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> loadCallback) {

    // Load an ad. This mock example uses Google's SDK, but in practice
    // your adapter will load the ad using your ad network's SDK.
    RewardedAd.load(adConfiguration.getContext(),
        "ca-app-pub-3940256099942544/5224354917",
        new AdRequest.Builder().build(),
        new RewardedAdLoadCallback() {
          @Override
          public void onAdLoaded(@NonNull RewardedAd rewardedAd) {
            // When the ad loads, invoke the load success callback.
            callback = loadCallback.onSuccess(SampleRtbAdapter.this);
          }
        });
  }

  @Override
  public void showAd(Context context) {
    // In this mock example, your ad network requires an activity context, but
    // didn't receive one, making you unable to show the ad.
    if (!(context instanceof Activity)) {
      AdError error = new AdError(1, "Context must be an activity",
          "com.google.ads.mediation.sample");
      callback.onAdFailedToShow(error);
    }

    // This example shows Google SDK's callbacks, but it's likely your SDK
    // has similar presentation callbacks.
    rewardedAd.setFullScreenContentCallback(new FullScreenContentCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Your ad network SDK successfully showed the ad. Call onAdOpened().
        callback.onAdOpened();
      }

      @Override
      public void onAdFailedToShowFullScreenContent(AdError adError) {
        // Your ad network SDK failed to show the ad, invoke onAdFailedToShow.
        // In practice, you will map your SDK's error to an AdError.
        AdError error = new AdError(adError.getCode(), adError.getMessage(),
            adError.getDomain());
        callback.onAdFailedToShow(adError);
      }
    });


    rewardedAd.show((Activity) context, ...);
  }
}