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 petunjuk mediasi penayang.

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

Agar bidding berfungsi dengan benar, adaptor Anda harus menangani inisialisasi, pengumpulan sinyal, pemuatan iklan, dan meneruskan peristiwa siklus proses iklan. Dalam panduan ini, kami akan memandu Anda cara menerapkan adaptor untuk menangani operasi ini.

Catatan: Partisipasi dalam bidding juga memerlukan bidder yang dapat merespons permintaan OpenRTB. Petunjuk tentang cara menyiapkan bidder berada di luar cakupan panduan ini.

Alur kerja adaptor bidding

Inisialisasi

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

Adaptor bertanggung jawab atas bagian alur kerja berikut:

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

• Langkah 10-13: Kumpulkan sinyal dari SDK jaringan iklan Anda untuk dikirim ke bidder Anda agar dapat berpartisipasi dalam permintaan RTB, dan teruskan sinyal tersebut ke Google Mobile Ads SDK.

• Langkah 18-21: Jika bidder Anda menampilkan bid pemenang, muat iklan sesuai dengan respons dari bidder Anda. Setelah dimuat, beri tahu Google Mobile Ads SDK bahwa iklan telah dimuat.

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

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

Menerapkan adaptor bidding

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

getSDKVersionInfo()

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

Metode ini mengharuskan Anda menampilkan VersionInfo. Contoh di bawah menunjukkan cara mengonversi versi string SDK Anda 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. Versi ini diteruskan ke bidder Anda sebagai bagian dari permintaan OpenRTB.

Adapter open source dan berversi Google menggunakan skema versi adapter 4 digit, tetapi VersionInfo hanya mengizinkan 3 digit. Untuk mengatasi hal ini, sebaiknya gabungkan dua digit terakhir ke dalam versi patch, seperti yang ditunjukkan di bawah.

@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. Metode ini hanya dipanggil satu kali per sesi. Metode ini memberi Anda daftar objek MediationConfiguration yang merepresentasikan daftar lengkap penempatan di aplikasi ini yang dikonfigurasi untuk jaringan iklan Anda; Anda dapat melakukan loop melalui daftar ini untuk mengurai kredensial untuk setiap penempatan, dan meneruskan data yang relevan ke SDK Anda untuk inisialisasi.

Setelah SDK diinisialisasi dan siap menerima permintaan iklan, panggil 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 adaptor sekali pakai. Tidak ada metode lain yang akan dipanggil pada instance tertentu ini. Jika adaptor perlu menyimpan status sebagai hasil dari metode ini, status apa pun 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 RtbAdapter baru Anda akan dibuat dan metode collectSignals() dipanggil. Instance RtbAdapter ini akan digunakan selama durasi siklus proses permintaan, respons, dan rendering iklan tersebut. Metode collectSignals() memungkinkan adaptor Anda memberikan sinyal dari perangkat untuk dikirim ke bidder Anda dalam permintaan OpenRTB.

collectSignals() dipanggil pada thread latar belakang. Google Mobile Ads SDK secara bersamaan meminta sinyal dari semua adapter yang berpartisipasi dalam bidding. Harap bersikap sopan dan batasi panggilan ke UI thread selama waktu ini. Setiap tugas berat yang perlu dilakukan adaptor atau SDK Anda untuk mengumpulkan sinyal harus dilakukan dalam metode initialize() dan di-cache.

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

Berikut contoh penerapan:

@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 merepresentasikan objek apa pun, dan dapat dalam format apa pun, seperti JSON biasa, dienkode Base64, atau bentuk enkripsi lain yang Anda pilih. Enkripsi sinyal direkomendasikan untuk memastikan sinyal tidak transparan di luar jaringan Anda.

Menerapkan metode pemuatan iklan

Waktu tunggu: 10 detik

Jika bidder Anda menampilkan bid yang menang, Google Mobile Ads SDK akan memanggil adaptor Anda untuk memuat iklan yang menang, dan meneruskan data apa pun yang ditampilkan bidder Anda yang diperlukan SDK Anda untuk memuat iklan tersebut.

Metode pemuatan persis yang dipanggil bergantung pada format iklan yang diminta:

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

Terapkan metode ini untuk format iklan yang didukung adaptor Anda.

Metode pemuatan dipanggil di thread UI, pada instance adapter yang sama tempat Anda memberikan sinyal. Metode ini memberikan parameter berikut kepada Anda:

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

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

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

Metode mediationAdLoadCallback.onSuccess() mengharuskan Anda meneruskan objek yang sesuai dengan salah satu antarmuka "Ad" yang ditentukan oleh Google Mobile Ads SDK. Antarmuka iklan ini meminta Anda untuk memberikan beberapa informasi tentang iklan.

MediationAdConfiguration juga memiliki metode getWatermark() untuk menampilkan string berenkode base64 yang merepresentasikan gambar PNG. Gambar ini harus disusun dalam overlay transparan di iklan Anda. Hubungi Google untuk mendapatkan panduan tambahan tentang cara merender watermark. Objek ini berisi metadata tentang iklan yang ditampilkan untuk digunakan oleh penayang dalam menentukan sumber iklan yang ditampilkan.

Untuk banner, Anda akan diminta memberikan tampilan banner. Untuk iklan interstisial dan rewarded, Anda akan diminta untuk menerapkan metode show() untuk menampilkan iklan di lain waktu. Sebagai praktik terbaik, sebaiknya buat class yang memuat iklan juga bertanggung jawab untuk menerapkan metode iklan ini.

Berikut adalah contoh penerapan loadBannerAd(). Perlu diingat bahwa penerapan adaptor Anda akan terlihat berbeda, karena adaptor Anda terintegrasi dengan 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 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 akhir adaptor adalah memberi tahu Google Mobile Ads SDK tentang peristiwa siklus proses presentasi apa pun, sehingga peristiwa tersebut dapat diteruskan ke penayang. Penayang mengharapkan panggilan balik ini pada waktu tertentu, terlepas dari jaringan iklan mana yang menayangkan iklan, jadi penting agar sebanyak mungkin panggilan balik ini dipanggil, dan pada waktu yang tepat, sehingga Google Mobile Ads SDK dapat meneruskannya ke penayang.

Adapter harus memanggil peristiwa berikut jika berlaku:

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

Adaptor akan mendapatkan objek MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> kembali setelah memanggil mediationAdLoadCallback.onSuccess(). Adaptor diharapkan untuk 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. Peran adapter hanyalah memetakan callback dari SDK jaringan iklan ke Google Mobile Ads SDK.

Contoh berikut menunjukkan cara 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 untuk iklan native saat 1 px iklan terlihat. Jika SDK jaringan iklan Anda memerlukan aset tertentu untuk ditampilkan agar dapat merender tayangan yang valid, bidder Anda dapat menunjukkan aset native yang diperlukan ini dalam respons bid. Kemudian, Google Mobile Ads SDK akan memvalidasi bahwa aset native yang diperlukan ditampilkan sebelum mencatat tayangan iklan.

Lihat dokumentasi aset wajib asli untuk mengetahui informasi selengkapnya tentang cara menentukan aset wajib tambahan dalam respons bid.

Poin Penting: Tayangan iklan yang dianggap tidak valid karena aset native tambahan yang diperlukan oleh jaringan iklan Anda akan memengaruhi rasio peristiwa yang dapat ditagih untuk penayang tersebut.

Menampilkan error iklan

Untuk format layar penuh, seperti iklan interstisial dan reward, di callback pemuatan yang berhasil, Anda akan memberikan penerapan MediationInterstitialAd atau MediationRewardedAd agar Google Mobile Ads SDK dapat meminta adapter Anda untuk menampilkan iklan.

Google Mobile Ads SDK berharap jika adaptor berhasil memuat iklan, iklan siap ditampilkan saat penayang meminta untuk menampilkannya. Artinya, setiap panggilan penayangan harus menghasilkan tayangan.

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

Tabel di bawah menunjukkan pengaruh callback presentasi terhadap perekaman tayangan iklan untuk format iklan layar penuh:

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

¹ Untuk tayangan yang gagal, jaringan iklan Anda tidak dikenai biaya untuk tayangan tersebut, tetapi hal ini memengaruhi penyesuaian rasio peristiwa yang dapat ditagih. Lihat sinyal permintaan bid untuk mengetahui informasi selengkapnya.

Contoh tiruan berikut menunjukkan siklus proses pemuatan/penayangan saat panggilan penayangan iklan dapat menyebabkan 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, ...);
  }
}