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

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

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

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

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

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

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

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

  • مراحل ۴ تا ۷: آداپتور خود را مقداردهی اولیه کنید و پس از اتمام مقداردهی اولیه، SDK تبلیغات موبایلی گوگل را فراخوانی کنید.

  • مراحل ۱۰ تا ۱۳: سیگنال‌ها را از SDK شبکه تبلیغاتی خود جمع‌آوری کنید تا برای شرکت در درخواست RTB به پیشنهاددهنده ارسال شود و آنها را به SDK تبلیغات موبایلی گوگل ارسال کنید.

  • مراحل ۱۸ تا ۲۱: در صورتی که پیشنهاد دهنده شما پیشنهاد برنده را برگرداند، تبلیغ را مطابق با پاسخ پیشنهاد دهنده خود بارگذاری کنید. پس از بارگذاری، به SDK تبلیغات موبایلی گوگل اطلاع دهید که تبلیغ بارگذاری شده است.

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

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

برای ایجاد یک آداپتور پیشنهاد قیمت برای 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 به پیشنهاد دهنده شما ارسال می‌شود.

آداپتورهای متن‌باز و نسخه‌بندی‌شده‌ی گوگل از طرح نسخه‌بندی آداپتور ۴ رقمی استفاده می‌کنند، اما 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);
}

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

زمان انتظار: 30 ثانیه

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

پس از اینکه SDK شما مقداردهی اولیه شد و آماده دریافت درخواست‌های تبلیغاتی شد، متد 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() در یک رشته پس‌زمینه فراخوانی می‌شود. SDK تبلیغات موبایل گوگل (Google Mobile Ads SDK) به طور همزمان از همه آداپتورهای شرکت‌کننده در مناقصه، سیگنال درخواست می‌کند. لطفاً در این مدت، فراخوانی‌ها به رشته UI را محدود کنید. هرگونه کار سنگینی که آداپتور یا SDK شما برای جمع‌آوری سیگنال‌ها باید انجام دهد، باید در متد initialize() انجام شده و در حافظه پنهان (cache) ذخیره شود.

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

در اینجا یک مثال پیاده‌سازی شده است:

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

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

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

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

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

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

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

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

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

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

  • یک شیء MediationAdLoadCallback که برای اطلاع‌رسانی به SDK تبلیغات موبایلی گوگل در صورت موفقیت‌آمیز بودن یا نبودن بارگذاری استفاده می‌شود.

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

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

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

برای بنرها، از شما خواسته می‌شود که نمای بنر را ارائه دهید. برای تبلیغات بینابینی و پاداشی، از شما خواسته می‌شود که یک متد 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 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;
  }
}

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

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

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

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

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

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

مثال زیر نشان می‌دهد که چگونه می‌توانید callbackها را از شنونده‌ی تبلیغات 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();
        }
    }
});

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

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

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

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

برای قالب‌های تمام صفحه، مانند تبلیغات بینابینی و پاداشی، در فراخوانی موفقیت‌آمیز بارگذاری، شما پیاده‌سازی MediationInterstitialAd یا MediationRewardedAd را ارائه خواهید داد تا 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, ...);
  }
}