Pengembangan adaptor bidding

Panduan ini ditujukan untuk jaringan iklan yang ingin membuat adaptor bidding untuk berpartisipasi dalam bidding real-time (RTB) dalam mediasi Google. Jika Anda adalah penayang, lihat mediasi penayang petunjuk.

Adaptor bidding adalah bagian sisi klien dari integrasi. Adaptor mengaktifkan SDK jaringan iklan Anda untuk berkomunikasi dengan Google Mobile Ads SDK untuk memuat iklan yang ditayangkan oleh bidder Anda.

Agar bidding berfungsi dengan benar, adaptor harus menangani inisialisasi, mengumpulkan sinyal, memuat iklan, dan menyampaikan siklus proses iklan peristiwa. Dalam panduan ini, kami akan memandu Anda memahami cara adaptor untuk menangani operasi ini.

Catatan: Partisipasi dalam bidding juga mewajibkan bidder yang dapat merespons Permintaan OpenRTB. Petunjuk tentang cara mendukung bidder berada di luar cakupan panduan ini.

Alur kerja adaptor bidding

Inisialisasi

Alur mendetail dari keseluruhan siklus proses rendering-permintaan-respons adaptor ditampilkan di bawah ini:

Adaptor bertanggung jawab atas bagian alur kerja berikut:

• Langkah 4-7: Lakukan inisialisasi adaptor Anda dan panggil kembali Google Mobile Ads SDK setelah inisialisasi selesai.

• Langkah 10-13: Kumpulkan sinyal dari SDK jaringan iklan untuk dikirim ke untuk berpartisipasi dalam permintaan RTB, dan meneruskannya ke Google Mobile SDK Iklan.

• Langkah 18-21: Jika bidder Anda mengembalikan bid yang menang, muat iklan sesuai terhadap respons dari bidder Anda. Setelah dimuat, beri tahu Google Mobile Ads SDK bahwa iklan telah dimuat.

• Langkah 23 dan yang lebih baru: Saat iklan ditampilkan, beri tahu Google Mobile Ads SDK peristiwa tayangan dan klik, serta peristiwa iklan lain yang terjadi selama siklus hidup presentasi iklan.

Catatan: Google Mobile Ads SDK secara terpisah melacak peristiwa tayangan, tetapi Anda juga harus meneruskan peristiwa tayangan jaringan iklan agar kami dapat memeriksa perbedaan.

Menerapkan adaptor bidding

Untuk membuat adaptor bidding untuk Google Mobile Ads SDK, Anda harus memperluas class abstrak RtbAdapter. Bagian berikut menjelaskan setiap metode abstrak di RtbAdapter.

getSDKVersionInfo()

Di sini, Anda akan menampilkan versi SDK Anda. Versi ini diteruskan ke sebagai bagian dari permintaan OpenRTB.

Metode ini mengharuskan Anda menampilkan VersionInfo. Contoh di bawah ini menunjukkan cara Anda dapat mengonversi versi string SDK menjadi 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()

Di sini, Anda harus menampilkan versi adaptor Anda. Versi ini diteruskan ke sebagai bagian dari permintaan OpenRTB.

sumber terbuka dan berbagai versi Google adaptor gunakan skema versi adaptor 4 digit, tetapi VersionInfo hanya mengizinkan 3 digit. Untuk mengatasi hal ini, sebaiknya gabungkan dua digit terakhir ke versi patch, seperti yang ditunjukkan di bawah ini.

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

Waktu tunggu: 30 detik

Metode initialize() adalah metode pertama yang dipanggil di adaptor Anda. Penting yang hanya dipanggil sekali per sesi. Metode ini memberi Anda daftar Objek MediationConfiguration yang mewakili daftar lengkap penempatan di aplikasi ini yang dikonfigurasi untuk jaringan iklan Anda; Anda dapat mengulang melalui daftar ini untuk mengurai kredensial untuk setiap penempatan, dan meneruskan data yang relevan ke SDK untuk diinisialisasi.

Setelah SDK Anda diinisialisasi dan siap untuk menerima permintaan iklan, panggil metode Metode onInitializationSucceeded() dari InitializationCompleteCallback. Callback ini diteruskan ke penayang aplikasi sehingga mereka dapat mengetahui bahwa mereka dapat mulai memuat iklan.

Catatan: Metode initialize() dipanggil pada instance throwaway adaptor. Tidak ada metode lain yang akan dipanggil pada instance khusus ini. Jika adaptor Anda perlu menyimpan status sebagai hasil dari metode ini, semua status harus statis.

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

Waktu tunggu: 1 detik

Setiap kali penayang meminta iklan, instance baru RtbAdapter Anda akan dibuat dan metode collectSignals() dipanggil. Contoh ini RtbAdapter akan digunakan selama durasi permintaan iklan, respons, dan siklus proses rendering untuk iklan tersebut. Metode collectSignals() memungkinkan adaptor untuk memberikan sinyal dari perangkat untuk dikirim ke bidder Anda dalam Permintaan OpenRTB.

collectSignals() dipanggil di thread latar belakang. Google Mobile Ads SDK secara bersamaan meminta sinyal dari semua adaptor yang berpartisipasi dalam bidding. Harap saling menghormati dan batasi panggilan ke UI thread selama periode ini. Pekerjaan berat apa pun yang perlu dilakukan adaptor atau SDK Anda untuk mengumpulkan harus dilakukan dalam metode initialize() dan di-cache.

Setelah Anda menyiapkan sinyal, panggil callback onSuccess() dengan sinyal yang dienkode.

Berikut adalah contoh implementasi:

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

Jika adaptor Anda gagal mengumpulkan sinyal, panggil signalCallbacks.onFailure() dengan string yang menjelaskan error yang terjadi.

Catatan: String sinyal dapat mewakili objek apa pun, dan dapat berada dalam seperti JSON biasa, berenkode Base64, atau bentuk enkripsi lain yang pilih. Sebaiknya enkripsi sinyal untuk memastikan sinyal buram di luar jaringan Anda.

Menerapkan metode pemuatan iklan

Waktu tunggu: 10 detik

Jika bidder Anda menampilkan bid yang menang, Google Mobile Ads SDK memanggil adaptor Anda untuk memuat iklan pemenang, meneruskan data yang kembali bahwa SDK Anda perlu memuat iklan tersebut.

Metode pemuatan persis yang dipanggil bergantung pada iklan format permintaan ini untuk:

Format Iklan	Metode pemuatan
Banner	loadBannerAd()
Interstisial	loadInterstitialAd()
Reward	loadRewardedAd()

Terapkan metode ini untuk format iklan yang didukung adaptor Anda.

Metode pemuatan dipanggil pada UI thread, pada instance yang sama adaptor yang Anda beri sinyal. Metode ini memberi Anda hal berikut parameter:

• MediationAdConfiguration, yang berisi parameter yang diperlukan SDK Anda memuat iklan untuk bid pemenang, seperti respons bid dan kredensial apa pun penayang yang dikonfigurasi di UI AdMob.

• Objek MediationAdLoadCallback yang digunakan untuk memberi tahu Google Mobile Ads SDK kapan pemuatan berhasil atau gagal.

Setelah SDK memuat iklan, panggil mediationAdLoadCallback.onSuccess(). Di kolom pemuatan iklan peristiwa gagal, panggil mediationAdLoadCallback.onFailure() dengan string yang menjelaskan error yang terjadi.

Metode mediationAdLoadCallback.onSuccess() mengharuskan Anda meneruskan elemen yang mengonfirmasi ke salah satu "Iklan" antarmuka yang ditentukan oleh Google Mobile SDK Iklan. Antarmuka iklan ini meminta Anda memberikan sejumlah informasi tentang iklan.

MediationAdConfiguration juga memiliki getWatermark() untuk menampilkan string berenkode base64 yang mewakili gambar PNG. Gambar ini harus memiliki ubin di overlay transparan di iklan Anda. Hubungi Google untuk mendapatkan panduan tambahan tentang cara merender watermark. Hasil ini berisi metadata tentang iklan yang ditampilkan untuk digunakan oleh penerbit guna menentukan sumber iklan yang ditampilkan.

Untuk banner, Anda akan diminta untuk memberikan tampilan banner. Untuk interstisial dan iklan reward, Anda akan diminta untuk menerapkan metode show() untuk menampilkan iklan di waktu yang akan datang. Sebagai praktik terbaik, sebaiknya buat kelas yang apakah pemuatan iklan juga bertanggung jawab untuk menerapkan metode iklan ini.

Berikut adalah contoh implementasi loadBannerAd(). Harap diingat implementasi adaptor akan terlihat berbeda, karena diintegrasikan ke SDK yang berbeda.

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

Meneruskan peristiwa siklus proses presentasi iklan

Tanggung jawab terakhir adaptor adalah memberi tahu Google Mobile Ads SDK setiap peristiwa siklus proses presentasi, sehingga dapat diteruskan ke penayang. Penayang mengharapkan callback ini pada waktu tertentu, terlepas dari jaringan iklan mana yang menayangkan iklan. Oleh karena itu, callback dipanggil mungkin, dan pada saat yang tepat, sehingga callback Mobile Ads SDK dapat meneruskannya ke penayang.

Adaptor harus memanggil peristiwa berikut jika berlaku:

Umum untuk semua format
Metode	Kapan harus menelepon
reportAdClicked()	Iklan diklik.
reportAdImpression()	Iklan menampilkan tayangan.
onAdOpened()	Iklan menampilkan tampilan layar penuh.
onAdClosed()	Tampilan layar penuh iklan telah ditutup.
onAdLeftApplication()	Iklan menyebabkan pengguna keluar dari aplikasi.
Iklan reward
onRewarded()	Pengguna diberi reward.
Callback video (iklan reward dan native)
onVideoStarted()	Video iklan dimulai.
onVideoCompleted()	Video iklan selesai.

Adaptor mendapatkan MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> objek kembali setelah memanggil mediationAdLoadCallback.onSuccess(). Adaptor adalah dapat menyimpan objek ini dan menggunakannya untuk memanggil peristiwa presentasi yang terjadi pada iklan Anda.

Biasanya, sebagian besar peristiwa ini didorong oleh SDK jaringan iklan Anda. Tujuan peran adaptor hanya untuk memetakan callback dari SDK jaringan iklan ke Google Mobile Ads SDK.

Contoh berikut menunjukkan bagaimana Anda akan meneruskan callback dari Pemroses iklan SDK ke 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();
        }
    }
});

Aset yang diperlukan untuk pelacakan tayangan iklan native

Google Mobile Ads SDK mencatat tayangan iklan native saat 1 piksel iklan terlihat. Jika SDK jaringan iklan Anda memerlukan aset tertentu untuk ditampilkan untuk menampilkan tayangan iklan yang valid, bidder Anda dapat menunjukkan hal tersebut diwajibkan aset native dalam respons bid. Google Mobile Ads SDK kemudian memvalidasi bahwa aset native yang diperlukan akan ditampilkan sebelum merekam tayangan.

Lihat aset native yang diperlukan dokumentasi untuk informasi selengkapnya tentang cara menentukan aset tambahan yang diperlukan dalam bid yang dihasilkan.

Poin Penting: Tayangan iklan apa pun yang ditampilkan tidak valid karena tambahan aset native yang diperlukan akan memengaruhi rasio peristiwa yang dapat ditagih untuk penayang tersebut.

Tampilkan error iklan

Untuk format layar penuh, seperti iklan interstisial dan reward, meraih kesuksesan Anda akan memberikan implementasi MediationInterstitialAd atau MediationRewardedAd sehingga Google Mobile Ads SDK dapat meminta adaptor Anda untuk menampilkan iklan.

Google Mobile Ads SDK memperkirakan jika adaptor berhasil memuat iklan, iklan siap ditayangkan saat penayang meminta untuk menampilkannya. Hal ini berarti bahwa setiap panggilan acara seharusnya menghasilkan tayangan.

Namun, mungkin ada kasus sudut saat Anda tidak dapat menampilkan iklan. Jika Anda tidak dapat menampilkan iklan, panggil onAdFailedToShow() untuk membatalkan tayangan.

Tabel di bawah menunjukkan bagaimana callback presentasi memengaruhi perekaman tayangan untuk format iklan layar penuh:

Telepon Balik	Hasil
onAdOpened()	Impression recorded
onAdFailedToShow()	Impression failure^1
Tak satu pun di atas selama beberapa detik	Impression recorded

¹ Untuk gagal tayangan, jaringan iklan tidak dikenai biaya untuk tayangan tersebut, tetapi akan berdampak pada penyesuaian tarif peristiwa yang dapat ditagih. Lihat permintaan bid sinyal untuk mendapatkan informasi lainnya tidak akurat atau tidak sesuai.

Contoh tiruan berikut menunjukkan siklus proses pemuatan/acara saat iklan {i>show call<i} dapat mengakibatkan kegagalan.

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, ...);
  }
}