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

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

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

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

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

راه‌اندازی

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

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

  • مراحل ۴ تا ۷: آداپتور را مقداردهی اولیه کنید و پس‌از تکمیل مقداردهی اولیه، Google Mobile Ads SDK (Legacy) را فراخوانی کنید.

  • مراحل ۱۰ تا ۱۳: سیگنال‌ها را از کیت توسعه نرم‌افزار شبکه آگهی‌تان جمع‌آوری کنید تا برای شرکت در درخواست مناقصه هم‌زمان به پیشنهاددهنده‌تان ارسال شود، و آن‌ها را به کیت توسعه نرم‌افزار Google Mobile Ads بازارسال کنید.

  • مراحل ۱۸ تا ۲۱: اگر پیشنهاددهنده شما پیشنهاد برنده را برگرداند، آگهی را مطابق با پاسخ پیشنهاددهنده خود بار کنید. پس‌از بار شدن، به Google Mobile Ads SDK (Legacy) اطلاع دهید که آگهی بار شده است.

  • مرحله ۲۳ و بعداز آن: درحالی‌که آگهی شما نمایش داده می‌شود، به Google Mobile Ads SDK از رویدادهای ظهور و کلیک، و همچنین سایر رویدادهای آگهی که درطول چرخه حیات ارائه آگهی شما رخ می‌دهد، اطلاع دهید.

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

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

getSDKVersionInfo()

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

این روش مستلزم آن است که VersionInfo را برگردانید. مثال زیر نشان می‌دهد که چگونه می‌توانید نسخه رشته‌ای کیت توسعه نرم‌افزارتان را به 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 از طرح نسخه آداپتور ۴ رقمی استفاده می‌کنند، اما VersionInfo فقط ۳ رقم را مجاز می‌داند. برای حل این مشکل، توصیه می‌شود دو رقم آخر را در نسخه وصله ترکیب کنید، همان‌طور که در زیر نشان داده شده است.

@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);
}

initialize()

زمان استراحت: ۳۰ ثانیه

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

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

@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()

زمان استراحت: ۱ ثانیه

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

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

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

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

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

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

پیاده‌سازی روش‌های بار کردن آگهی

زمان استراحت: ۱۰ ثانیه

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

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

قالب‌بندی آگهی روش بار کردن
برنما loadBannerAd()
بینابینی loadInterstitialAd()
پاداش loadRewardedAd()

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

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

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

  • شیء MediationAdLoadCallback که برای مطلع کردن Google Mobile Ads SDK (Legacy) درصورت موفقیت یا عدم موفقیت بارگیری استفاده می‌شود.

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

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

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

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

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

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 Google Mobile Ads SDK (Legacy).
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 (Legacy) را از هرگونه رویداد چرخه حیات ارائه مطلع کند تا بتوان آن‌ها را به ناشر بازارسال کرد. ناشر انتظار دارد این فراخوانی‌های برگشتی در زمان‌های خاصی انجام شود، صرف‌نظر از اینکه کدام شبکه آگهی آگهی را ارائه می‌دهد، بنابراین مهم است که تا حد امکان تعداد بیشتری از این فراخوانی‌های برگشتی و در زمان مناسب فراخوانی شوند تا Google Mobile Ads SDK (Legacy) بتواند آن‌ها را به ناشر ارسال کند.

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

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

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

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

مثال زیر نشان می‌دهد که چگونه می‌توانید فراخوانی‌های برگشتی را از شنونده آگهی کیت توسعه نرم‌افزار خود به Google Mobile Ads SDK (Legacy) بازارسال کنید:

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();
        }
    }
});

دارایی‌های لازم برای ردیابی ظهور آگهی بومی

Google Mobile Ads SDK (Legacy) زمانی ظهور آگهی بومی را ثبت می‌کند که ۱ پیکسل از آگهی نمایان باشد. اگر کیت توسعه نرم‌افزار شبکه آگهی شما برای ارائه ظهور معتبر به نمایش دارایی‌های خاصی نیاز دارد، پیشنهاددهنده شما می‌تواند این دارایی‌های بومی الزامی را در پاسخ پیشنهاد قیمت نشان دهد. سپس Google Mobile Ads SDK (Legacy) پیش‌از ثبت ظهور، نمایش دارایی‌های بومی الزامی شما را اعتبارسنجی می‌کند.

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

نمایش خطاهای آگهی

برای قالب‌های تمام‌صفحه، مانند آگهی‌های بینابینی و پاداشی، در فراخوانی برگشتی بارگیری موفق، پیاده‌سازی MediationInterstitialAd یا MediationRewardedAd را ارائه خواهید داد تا Google Mobile Ads SDK (Legacy) بتواند از آداپتور شما بخواهد آگهی را نشان دهد.

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

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

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

پاسخ تماس نتیجه
onAdOpened() Impression recorded
onAdFailedToShow() Impression failure1
هیچ‌کدام از موارد بالا برای چند ثانیه 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, ...);
  }
}