Pengembangan Adaptor Mediasi Jaringan Iklan

Panduan ini ditujukan untuk jaringan iklan yang ingin membuat adaptor mediasi. Jika Anda adalah penayang, lihat petunjuk mediasi penayang.

Adaptor jaringan iklan adalah lapisan komunikasi antara jaringan iklan Anda dan Mediasi Google Mobile Ads.

Adaptor bertanggung jawab untuk menerapkan MediationBannerAdapter untuk mendukung iklan banner dan MediationInterstitialAdapter untuk mendukung iklan interstisial. Aplikasi juga harus memanggil callback di MediationBannerListener dan MediationInterstitialListener pada waktu yang tepat untuk memberi tahu Mediasi Google Mobile Ads tentang peristiwa ini, yang juga dapat diteruskan ke developer.

Contoh jaringan iklan

Panduan ini menunjukkan cara membuat adaptor untuk Sample Ad Network. Sample ad network berisi kelas berikut yang mewakili kelas yang ditawarkan oleh sebagian besar jaringan iklan:

class SampleAdView {
    public SampleAdView(Context context);
    public void setSize(SampleAdSize size);
    public void setAdUnit(String sampleAdUnit);
    public void setAdListener(SampleAdListener listener);
    public void fetchAd(SampleAdRequest request);
    public void destroy();
}

class SampleAdSize {
    public SampleAdSize(int width, int height);
    public int getWidth();
    public int getHeight();
}

class SampleAdRequest {
    public SampleAdRequest();
    public void setKeywords(Set<String> keywords);
    public void setTestMode(boolean useTesting);
}

class SampleAdListener {
    public void onAdFetchSucceeded();
    public void onAdFetchFailed(SampleErrorCode code);
    public void onAdFullScreen();
    public void onAdClosed();
}

enum SampleErrorCode {
    UNKNOWN,
    BAD_REQUEST,
    NETWORK_ERROR,
    NO_INVENTORY
}

class SampleInterstitial {
    public SampleInterstitial(Context context);
    public void setAdUnit(String sampleAdUnit);
    public void setAdListener(SampleAdListener listener);
    public void fetchAd(SampleAdRequest request);
    public void show();
    public void destroy();
}

Baca penerapan SDK lengkap untuk mendapatkan informasi lebih lanjut tentang class ini.

Mengimplementasikan adaptor banner

Untuk mengimplementasikan adaptor yang mendukung iklan banner, buat class yang menerapkan MediationBannerAdapter.

public class SampleAdapter implements MediationBannerAdapter {
    @Override
    public void requestBannerAd(
            Context context,
            MediationBannerListener listener,
            Bundle serverParameters,
            AdSize adSize,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {}

    @Override
    public View getBannerView() {}

    @Override
    public void onDestroy() {}

    @Override
    public void onPause() {}

    @Override
    public void onResume() {}
}

Sebelum mempelajari lebih lanjut cara menerapkan MediationBannerAdapter, mari kita bahas parameter server, tambahan mediasi, dan cara nilai ini diteruskan ke adaptor.

Parameter server

Jaringan iklan Anda mungkin memerlukan beberapa ID untuk mengidentifikasi penayang. Sample Ad Network, misalnya, hanya memerlukan sebuah unit iklan. Parameter yang diperlukan ini diberikan kepada Anda dalam paket serverParameters di dalam requestBannerAd(). Selama pengembangan, Anda dapat mengasumsikan bahwa paket sudah terisi dengan kunci yang diperlukan:

private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";

@Override
public void requestBannerAd(
        Context context,
        MediationBannerListener listener,
        Bundle serverParameters,
        AdSize adSize,
        MediationAdRequest mediationAdRequest,
        Bundle mediationExtras) {
    String adUnit = serverParameters.getString(SAMPLE_AD_UNIT_KEY);
    ...
}

AdMob akan mengirimkan kuesioner yang menanyakan parameter server apa yang Anda perlukan dari penayang untuk meminta dan menayangkan iklan. AdMob akan menggunakan input tersebut untuk mengonfigurasi jaringan Anda di UI AdMob. Screenshot di bawah ini menunjukkan bahwa APID diperlukan untuk Millennial Media, dan ID Aplikasi diperlukan untuk InMobi.

AdMob akan menggunakan informasi ini untuk mengisi paket serverParameters saat membuat instance adaptor Anda.

Lihat artikel ini untuk informasi selengkapnya tentang cara penayang mengonfigurasi jaringan iklan mediasi.

Parameter penargetan tambahan

MediationAdRequest berisi beberapa informasi penargetan umum yang dapat Anda gunakan untuk penargetan iklan seperti:

Tambahan mediasi

Jika jaringan iklan Anda mendukung informasi penargetan yang tidak diberikan oleh MediationAdRequest, developer aplikasi dapat meneruskan paket mediationExtras khusus ke jaringan Anda. Mediasi memberikan contoh cara meneruskan mediasi tambahan.

Untuk memudahkan developer meneruskan informasi ini secara opsional, Anda dapat menyediakan class builder paket di adaptor Anda. Katakanlah jaringan Anda mendukung penerusan nilai pendapatan. Anda dapat menambahkan class builder di adaptor yang menetapkan pendapatan:

public static final class BundleBuilder {
    private int income;

    public BundleBuilder setIncome(int income) {
        this.income = income;
        return this;
    }

    public Bundle build() {
        Bundle bundle = new Bundle();
        bundle.putInt("income", income);
        return bundle;
    }
}

Class ini menyediakan API bersih bagi developer untuk membuat paket untuk jaringan Anda:

Bundle sampleAdapterBundle =
        new SampleAdapter.BundleBuilder().setIncome(100000).build();

requestBannerAd()

Setelah Anda memahami parameter server dan tambahan mediasi, kita dapat menggunakannya untuk mem-build MediationBannerAdapter.

Metode requestBannerAd() dipanggil segera setelah adaptor dibuat instance-nya. Di sinilah Anda harus membuat tampilan iklan dan membuat permintaan iklan banner.

Penerapan requestBannerAd() untuk Sample ad network akan terlihat seperti ini:

public class SampleAdMobAdapter implements MediationBannerAdapter {
    private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";
    private SampleAdView sampleAdView;

    @Override
    public void requestBannerAd(
            Context context, // May be an application context.
            MediationBannerListener listener,
            Bundle serverParameters,
            AdSize adSize,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {
        sampleAdView = new SampleAdView(context);

        if (serverParameters.containsKey(SAMPLE_AD_UNIT_KEY)) {
            sampleAdView.setAdUnit(serverParameters.getString(SAMPLE_AD_UNIT_KEY));
        } else {
            listener.onAdFailedToLoad(this, AdRequest.ERROR_CODE_INVALID_REQUEST);
        }

        sampleAdView.setSize(
                new SampleAdSize(adSize.getWidth(),adSize.getHeight()));

        sampleAdView.setAdListener(
                new SampleBannerEventForwarder(listener, this));

        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        sampleAdView.fetchAd(request);
    }
}

Jangan berasumsi bahwa parameter konteks adalah jenis Activity. Bergantung pada penerapan penayang, Mediasi Google Mobile Ads dapat meneruskan konteks aplikasi ke adaptor Anda. Jika adaptor Anda tidak dapat menangani konteks aplikasi, sebaiknya panggil onAdFailedToLoad() dengan kode error AdRequest.ERROR_CODE_INVALID_REQUEST.

Callback MediationBannerListener

Anda harus menyimpan MediationBannerListener yang diberikan kepada Anda di requestBannerAd() sehingga Anda dapat meneruskan peristiwa iklan kembali ke Mediasi Google Mobile Ads. Setiap callback harus dipanggil pada waktu yang tepat dalam siklus proses iklan:

Metode Waktu menelepon
onAdLoaded() Permintaan banner berhasil.
onAdFailedToLoad() Permintaan banner gagal.
onAdClicked() Banner diklik.
onAdOpened() Banner menampilkan tampilan layar penuh.
onAdClosed() Pengguna kembali ke aplikasi setelah mengklik banner.
onAdLeftApplication() Banner tersebut menyebabkan pengguna keluar dari aplikasi.

Adaptor Sample ad network membuat class bernama SampleBannerEventForwarder untuk menangani penerusan peristiwa:

public class SampleBannerEventForwarder extends SampleAdListener {
    private MediationBannerListener mediationListener;
    private SampleAdapter adapter;

    public SampleBannerEventForwarder(
            MediationBannerListener listener, SampleAdapter adapter) {
        this.mediationListener = listener;
        this.adapter = adapter;
    }

    @Override
    public void onAdFetchSucceeded() {
        mediationListener.onAdLoaded(adapter);
    }

    @Override
    public void onAdFetchFailed(SampleErrorCode errorCode) {
        switch(errorCode) {
            case UNKNOWN:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_INTERNAL_ERROR);
                break;
            case BAD_REQUEST:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_INVALID_REQUEST);
                break;
            case NETWORK_ERROR:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_NETWORK_ERROR);
                break;
            case NO_INVENTORY:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_NO_FILL);
                break;
        }
    }

    @Override
    public void onAdFullScreen() {
        mediationListener.onAdClicked(adapter);
        mediationListener.onAdOpened(adapter);
        mediationListener.onAdLeftApplication(adapter);
    }

    @Override
    public void onAdClosed() {
        mediationListener.onAdClosed(adapter);
    }
}

Perhatikan cara adaptor Sample ad network mengirim onAdClicked, onAdOpened, dan onAdLeftApplication dalam callback yang sama. Meskipun callback untuk jaringan Anda mungkin tidak sama persis dengan callback yang dibutuhkan Google Mobile Ads, adaptor bertanggung jawab untuk memberikan pemetaan yang wajar.

getBannerView

Setelah Anda memanggil MediationBannerListener.onAdLoaded(), mediasi akan memanggil getBannerView() agar tampilan banner jaringan iklan Anda ditampilkan di layar. Cukup tampilkan tampilan banner yang Anda buat di requestBannerAd():

@Override
public View getBannerView() {
    return sampleAdView;
}

Peristiwa siklus proses aktivitas

Mediasi akan memberi tahu adaptor peristiwa aktivitas onPause() dan onResume() jika developer aplikasi memberitahukan mediasi peristiwa tersebut. Lakukan jeda dan lanjutkan yang diperlukan untuk banner Anda:

@Override
public void onPause() {
}

@Override
public void onResume() {
}

Sample Ad Network tidak menyertakan jeda atau melanjutkan panggilan, sehingga menyediakan implementasi kosong.

Mediasi akan melakukan upaya terbaik untuk memanggil onDestroy() saat adaptor akan dihancurkan. Lakukan pembersihan yang diperlukan di sini:

@Override
public void onDestroy() {
    if (sampleAdView != null) {
        sampleAdView.destroy();
    }
}

Banner cerdas

Google Mobile Ads SDK mendukung ukuran iklan smart banner, dengan lebar penuh dan tinggi bervariasi tergantung ukuran perangkat.

Untuk mendapatkan ukuran iklan banner cerdas secara akurat, adaptor Anda harus menggunakan adSize.getWidthInPixels(context) untuk mendapatkan lebar dan adSize.getHeightInPixels(context), bukan adSize.getHeight() untuk mendapatkan tingginya. Kemudian akan dibagi dengan kepadatan perangkat:

int widthInPixels = adSize.getWidthInPixels(context);
int heightInPixels = adSize.getHeightInPixels(context);
DisplayMetrics displayMetrics = Resources.getSystem().getDisplayMetrics();
int widthInDp = Math.round(widthInPixels / displayMetrics.density);
int heightInDp = Math.round(heightInPixels / displayMetrics.density);

Anda kemudian dapat menggunakan widthInDp dan heightInDp sebagai ukuran saat membuat permintaan iklan.

Selesai. Anda sekarang memiliki adaptor mediasi yang berfungsi untuk banner. Untuk referensi, implementasi SampleAdapter secara lengkap dapat ditemukan di sini.

Menerapkan adaptor interstisial

Penerapan adaptor untuk iklan interstisial mirip dengan iklan banner. Untuk menerapkan adaptor yang mendukung iklan interstisial, buat class yang menerapkan MediationInterstitialAdapter:

public class SampleAdapter implements MediationInterstitialAdapter {
    @Override
    public void requestInterstitialAd(
            Context context,
            MediationInterstitialListener listener,
            Bundle serverParameters,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {}

    @Override
    public View showInterstitial() {}

    @Override
    public void onDestroy() {}

    @Override
    public void onPause() {}

    @Override
    public void onResume() {}
}

Jika adaptor Anda juga mendukung banner, Anda dapat menggunakan kelas adaptor yang sama untuk menerapkan kedua antarmuka.

Pahami parameter server dan tambahan mediasi sebelum melanjutkan penerapan MediationInterstitialAdapter.

Parameter server (interstisial)

Lihat bagian Parameter server banner.

Parameter penargetan tambahan (interstisial)

Lihat bagian Parameter penargetan tambahan banner.

Tambahan mediasi (interstisial)

Lihat bagian Tambahan mediasi banner.

requestInterstitialAd

Metode requestInterstitialAd() dipanggil segera setelah adaptor dibuat instance-nya. Di sinilah tempat Anda membuat iklan interstisial dan membuat permintaan interstisial.

Penerapan requestInterstitialAd() untuk Sample ad network akan terlihat seperti ini:

public class SampleAdapter implements MediationBannerAdapter {
    private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";

    private SampleInterstitial sampleInterstitial;

    @Override
    public void requestInterstitialAd(
            Context context, // May be an application context.
            MediationInterstitialListener listener,
            Bundle serverParameters,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {
        sampleInterstitial = new SampleInterstitial(context);

        if (serverParameters.containsKey(SAMPLE_AD_UNIT_KEY)) {
            sampleInterstitial.setAdUnit(serverParameters.getString(SAMPLE_AD_UNIT_KEY));
        } else {
            listener.onAdFailedToLoad(this, AdRequest.ERROR_CODE_INVALID_REQUEST);
        }

        sampleInterstitial.setAdListener(
                new SampleInterstitialEventForwarder(listener, this));

        // Make an ad request.
        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        sampleInterstitial.fetchAd(request);
    }
}

Jangan berasumsi bahwa parameter konteks adalah jenis Aktivitas. Mediasi Google Mobile Ads meneruskan konteks yang diteruskan oleh developer aplikasi, dan ada kemungkinan bahwa konteks aplikasi diteruskan. Jika adaptor Anda tidak dapat menangani konteks aplikasi, sebaiknya panggil onAdFailedToLoad dengan kode error AdRequest.ERROR_CODE_INVALID_REQUEST.

Callback MediationInterstitialListener

Anda harus menyimpan MediationInterstitialListener yang diberikan kepada Anda di requestInterstitialAd sehingga Anda dapat meneruskan peristiwa iklan kembali ke Mediasi Google Mobile Ads. Setiap callback harus dipanggil pada waktu yang sesuai dalam siklus proses iklan:

Metode Waktu menelepon
onAdLoaded Permintaan interstisial berhasil.
onAdFailedToLoad Permintaan interstisial gagal.
onAdOpened Interstisial ditampilkan.
onAdClosed Interstisial ditutup.
onAdLeftApplication Iklan interstisial menyebabkan pengguna keluar dari aplikasi.

showInterstitial

Setelah memanggil MediationInterstitialListener.onAdLoaded(), Anda harus menunggu untuk menampilkan interstisial hingga showInterstitial() dipanggil. Developer aplikasi memutuskan waktu untuk menampilkan interstisial, yang dapat memakan waktu beberapa menit setelah diminta.

Implementasi untuk showInterstitial() cukup mudah. Cukup tampilkan objek interstisial Anda:

@Override
public void showInterstitial() {
    sampleInterstitial.show();
}

Peristiwa siklus proses Aktivitas (interstisial)

Lihat bagian Peristiwa siklus proses aktivitas banner.

Setelah mengimplementasikan peristiwa siklus proses aktivitas, adaptor mediasi Anda siap untuk menangani iklan interstisial. Untuk referensi, penerapan SampleAdapter secara lengkap dapat ditemukan di sini.

FAQ

Apa yang harus saya lakukan jika adaptor saya hanya mendukung iklan banner atau interstisial, tetapi tidak keduanya?

Jika adaptor hanya mendukung banner, Anda hanya perlu menerapkan antarmuka MediationBannerAdapter. Jika adaptor hanya mendukung interstisial, Anda hanya perlu menerapkan antarmuka MediationInterstitialAdapter.