Panduan ini ditujukan bagi 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 sisi klien dari integrasi. 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 pengiriman peristiwa siklus proses iklan. Dalam panduan ini, kami akan memandu Anda terkait cara mengimplementasikan adaptor untuk menangani operasi ini.
Alur kerja adaptor bidding
Inisialisasi
Alur mendetail dari seluruh siklus proses permintaan-respons-rendering 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 bidder agar dapat berpartisipasi dalam permintaan RTB, dan teruskan 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 selanjutnya: Saat iklan ditampilkan, beri tahu Google Mobile Ads SDK tentang peristiwa tayangan dan klik, serta peristiwa iklan lainnya yang terjadi selama siklus proses presentasi iklan Anda.
Mengimplementasikan adaptor bidding
Guna 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 harus menampilkan versi SDK. Versi ini diteruskan ke bidder Anda sebagai bagian dari permintaan OpenRTB.
Metode ini mengharuskan Anda menampilkan VersionInfo
. Contoh di bawah ini menunjukkan cara
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. Versi ini diteruskan ke bidder Anda sebagai bagian dari permintaan OpenRTB.
Adaptor open source dan
berversi Google
menggunakan skema versi adaptor 4 digit, tetapi VersionInfo
hanya mengizinkan 3
digit. Untuk mengatasi hal ini, sebaiknya gabungkan dua digit terakhir
ke dalam versi patch, seperti 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. Panggilan hanya dipanggil sekali per sesi. Metode ini memberi Anda daftar
objek MediationConfiguration
yang mewakili daftar lengkap
penempatan dalam aplikasi ini yang dikonfigurasi untuk jaringan iklan Anda. Anda dapat melakukan loop
melalui daftar ini untuk mengurai kredensial setiap penempatan,
dan meneruskan data yang relevan ke SDK Anda untuk inisialisasi.
Setelah SDK Anda 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.
@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. Instance RtbAdapter
ini akan digunakan selama durasi permintaan iklan, respons, dan siklus proses rendering untuk iklan tersebut. Metode collectSignals()
memungkinkan
adaptor Anda memberikan sinyal dari perangkat agar dikirim ke bidder dalam
permintaan OpenRTB.
collectSignals()
dipanggil pada thread latar belakang.
Google Mobile Ads SDK secara bersamaan meminta sinyal dari semua adaptor yang berpartisipasi dalam bidding. Hormati satu sama lain dan batasi panggilan ke UI thread
selama waktu ini. Setiap pekerjaan berat yang harus dilakukan adaptor atau SDK Anda untuk mengumpulkan
sinyal harus dilakukan di metode initialize()
dan di-cache.
Setelah sinyal Anda siap, panggil callback onSuccess()
dengan sinyal yang dienkode.
Berikut adalah contoh implementasinya:
@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.
Mengimplementasikan metode pemuatan iklan
Waktu tunggu: 10 detik
Jika bidder Anda menampilkan bid pemenang, Google Mobile Ads SDK akan memanggil adaptor untuk memuat iklan pemenang, sehingga meneruskan data yang ditampilkan oleh bidder yang diperlukan SDK Anda untuk memuat iklan tersebut.
Metode pemuatan persis yang dipanggil bergantung pada format iklan yang menjadi tujuan permintaan ini:
Format Iklan | Metode pemuatan |
---|---|
Banner | loadBannerAd()
|
Interstisial | loadInterstitialAd()
|
Diberikan sebagai reward | loadRewardedAd()
|
Terapkan metode ini untuk format iklan yang didukung adaptor Anda.
Metode pemuatan dipanggil di UI thread, pada instance adaptor yang sama dengan yang Anda beri sinyal. Metode ini memberikan parameter berikut:
MediationAdConfiguration
, yang berisi parameter yang diperlukan 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 Anda memuat iklan, panggil mediationAdLoadCallback.onSuccess()
. Jika
pemuatan iklan gagal, panggil mediationAdLoadCallback.onFailure()
dengan
string yang menjelaskan error yang terjadi.
Metode mediationAdLoadCallback.onSuccess()
mengharuskan Anda meneruskan objek yang dikonfirmasi ke salah satu antarmuka "Iklan" yang ditentukan oleh Google Mobile Ads SDK. Antarmuka iklan berikut meminta Anda memberikan beberapa informasi tentang iklan.
MediationAdConfiguration
juga memiliki metode getWatermark()
untuk menampilkan string berenkode base64 yang merepresentasikan gambar PNG. Gambar ini harus ubin dalam overlay transparan di iklan Anda.
Hubungi Google untuk mendapatkan panduan tambahan tentang cara merender watermark.
File ini berisi metadata tentang iklan yang ditampilkan untuk digunakan oleh penayang guna menentukan
sumber iklan yang ditampilkan.
Untuk banner, Anda akan diminta untuk menyediakan tampilan banner. Untuk iklan interstisial dan reward, Anda akan diminta untuk menerapkan metode show()
untuk menampilkan iklan di lain waktu. Sebagai praktik terbaik, sebaiknya jadikan class yang
melakukan pemuatan iklan juga bertanggung jawab untuk menerapkan metode iklan ini.
Berikut adalah contoh implementasi loadBannerAd()
. Perlu diingat bahwa implementasi adaptor akan terlihat berbeda karena adaptor 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 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 tentang setiap peristiwa siklus proses presentasi, sehingga peristiwa tersebut dapat diteruskan ke penayang. Penayang mengharapkan callback ini pada waktu tertentu, tidak peduli jaringan iklan mana yang menayangkan iklan, penting untuk memastikan callback tersebut dipanggil sebanyak mungkin, dan pada waktu yang tepat, agar Google Mobile Ads SDK dapat meneruskannya ke penayang.
Adaptor harus memanggil peristiwa berikut jika berlaku:
Umum untuk semua format | |
---|---|
Metode | Waktu panggilan |
reportAdClicked()
|
Iklan diklik. |
reportAdImpression()
|
Iklan merender tayangan. |
onAdOpened()
|
Iklan tersebut menyajikan tampilan layar penuh. |
onAdClosed()
|
Tampilan layar penuh untuk iklan telah ditutup. |
onAdLeftApplication()
|
Iklan tersebut 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 akan mendapatkan objek MediationAdLoadCallback<MediationAdT, MediationAdCallbackT>
kembali setelah memanggil mediationAdLoadCallback.onSuccess()
. Adaptor
diharapkan menempel 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 adaptor hanya memetakan callback dari SDK jaringan iklan Anda 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 untuk iklan native jika iklan native terlihat dengan 1 piksel. Jika SDK jaringan iklan Anda memerlukan aset tertentu agar ditampilkan untuk 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 sudah ditampilkan sebelum tayangan dicatat.
Baca dokumentasi aset native yang diperlukan untuk mengetahui informasi selengkapnya tentang cara menentukan aset tambahan yang diperlukan dalam respons bid.
Tampilkan error iklan
Untuk format layar penuh, seperti iklan interstisial dan reward, saat callback
berhasil dimuat, Anda akan memberikan implementasi
MediationInterstitialAd
atau MediationRewardedAd
sehingga Google Mobile Ads SDK dapat meminta adaptor Anda untuk menampilkan iklan.
Google Mobile Ads SDK memperkirakan bahwa jika adaptor berhasil memuat iklan, iklan siap ditampilkan saat penayang meminta untuk menampilkannya. Artinya, setiap panggilan acara akan menghasilkan tayangan.
Namun, mungkin ada kasus sudut yang membuat Anda tidak dapat menampilkan iklan. Jika Anda
tidak dapat menampilkan iklan, panggil callback
onAdFailedToShow()
untuk membatalkan tayangan.
Tabel di bawah menampilkan pengaruh callback presentasi terhadap perekaman tayangan untuk format iklan layar penuh:
Callback | Hasil |
---|---|
onAdOpened() | Impression recorded
|
onAdFailedToShow() | Impression failure1
|
Tak satu pun di atas selama beberapa detik | Impression recorded
|
1 Untuk tayangan gagal, jaringan iklan Anda tidak akan dikenai biaya untuk tayangan, tetapi hal ini memengaruhi penyesuaian tarif peristiwa yang dapat ditagih. Lihat sinyal permintaan bid untuk informasi selengkapnya.
Contoh tiruan berikut menunjukkan siklus proses pemuatan/penayangan ketika panggilan acara iklan 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, ...);
}
}