Penerapan Native AFS untuk Android

Google Mobile Ads SDK juga mendukung gaya penelusuran kustom. Jika aplikasi Anda sudah menggunakan Google Mobile Ads SDK, sebaiknya gunakan Versi AFSMA SDK sebagai gantinya.

Jika Anda meningkatkan ke versi 19.0.0 atau yang lebih baru dari 18.1.0 atau yang lebih lama, lihat panduan migrasi kami.

Prasyarat

Panduan penerapan ini mengasumsikan bahwa Anda sudah memahami hal berikut:

Mengimpor AFS Native SDK

Menambahkan SDK

Untuk menambahkan AFS Native SDK ke aplikasi Anda, lakukan hal berikut:

Buka file build.gradle di dalam direktori modul aplikasi Anda. Tambahkan aturan build baru di bagian dependencies untuk versi terbaru SDK:

dependencies {
  implementation 'com.google.android.gms:play-services-afs-native:19.1.0'
}

Pastikan build.gradle tingkat teratas berisi referensi ke google() repo atau ke maven { url "https://maven.google.com" }.

Ikuti petunjuk ini untuk menyertakan Plugin Pencocokan Versi Mandiri Google Play dalam project Anda. Menerapkan plugin ini akan menyebabkan error build gradle saat AFS Native SDK digunakan dengan versi Layanan Google Play yang tidak kompatibel, bukan mengizinkan aplikasi untuk dibangun, tetapi berpotensi menyebabkan error runtime. Atau, terapkan failOnVersionConflict() ResolutionStrategy pada project Anda yang akan menyebabkan error build saat versi Google Play yang tidak kompatibel Layanan digunakan dalam project Anda. Simpan perubahan, lalu klik Sync Project with Gradle Files di {i>toolbar<i}.

Menggunakan AndroidX, bukan Android Support Library

Mulai dari SDK versi 17.0.0, aplikasi Anda harus menggunakan Jetpack (AndroidX) Library, bukan Android Support Library. Persyaratan kompatibilitas:

  • Tetapkan com.android.tools.build:gradle ke v3.2.1 atau yang lebih baru.
  • Tetapkan compileSdkVersion ke 28 atau yang lebih baru.
  • Mengupdate aplikasi untuk menggunakan Jetpack (AndroidX); ikuti petunjuk di Bermigrasi ke AndroidX.

Class

Untuk menayangkan iklan native AFS di aplikasi Anda, terapkan kelas berikut:

SearchAdController

  • Kelas ini bertanggung jawab untuk meminta iklan, penyimpanan dalam cache, dan mengambil iklan, dan merender iklan.
  • Setiap konteks iklan memerlukan SearchAdController yang terpisah; misalnya, jika Anda memiliki layar yang menampilkan iklan di samping daftar hasil penelusuran dan yang menampilkan iklan di samping detail produk tertentu, Anda harus membuat dua instance terpisah dari SearchAdController, satu untuk setiap kasus.
  • Konstruktor harus memberikan kode properti web (ID penayang), style ID untuk diterapkan ke iklan yang ditampilkan, dan SearchAdOptions. Context yang disediakan dalam konstruktor harus Activity yang berisi SearchAdController dan tempat Anda akan menempatkan iklan View.
  • Panggil loadAds untuk menunjukkan penelusuran pengguna baru dan memulai iklan asinkron permintaan. Semua iklan yang dimuat dari panggilan sebelumnya ke loadAds akan dihapus dari {i>cache<i} iklan internal ketika ada panggilan baru.
  • Buat View dengan createAdView untuk menampilkan materi iklan.
  • Setelah iklan dimuat, panggil populateAdView dengan View yang dibuat sebelumnya dengan createAdView untuk merender iklan yang di-cache ke View tersebut. Selain pasal View yang akan diisi, berikan adKey, string arbitrer untuk mengidentifikasi iklan secara unik. Hal ini mengaitkan materi iklan tertentu yang ditampilkan dari cache dengan adKey tersebut, sehingga saat adKey yang sama diteruskan ke panggilan mendatang ke populateAdView, iklan yang sama akan dikembalikan. Misalnya, jika populateAdView dipanggil untuk pertama kalinya dengan adKey="keyA" dan merender iklan untuk sepatu bot lintas alam, setiap panggilan berikutnya ke populateAdView dengan adKey="keyA" akan mengisi iklan yang sama untuk sepatu bot lintas alam. (Melakukan panggilan baru ke loadAds menghapus semua iklan yang di-cache dan kunci iklan terkait.)

SearchAdOptions

  • Teruskan objek ini ke konstruktor SearchAdController untuk menyesuaikan cara iklan diminta dan ditampilkan. Panggil build() di SearchAdOptions.Builder untuk buat objek SearchAdOptions.

View

  • Buat objek View untuk menangguhkan iklan dengan memanggil createAdView() di SearchAdController. Menampilkan maksimal satu iklan dalam satu waktu, tetapi View yang sama dapat didaur ulang untuk menampilkan iklan yang berbeda dari waktu ke waktu.

SearchAdRequest

  • Panggil metode loadAds pada SearchAdController dengan SearchAdRequest untuk memulai permintaan iklan asinkron. Panggil build() di SearchAdRequest.Builder untuk membuat objek SearchAdRequest.

AdListener

  • Terapkan antarmuka ini dan teruskan ke konstruktor SearchAdController untuk mendaftarkan callback untuk beberapa status.
  • Catatan: Callback AdListener tidak akan dipanggil pada permintaan yang dibatalkan (panggilan ke loadAds yang di-preempt oleh panggilan lain ke loadAds sebelum panggilan telah diselesaikan).

Contoh implementasi

Contoh di bawah menunjukkan pembuatan SearchAdController dalam contoh Activity.

//  MainActivity.java implementation
//  (MainActivity is a subclass of Activity)

SearchAdController adController;
// adContainer where we will place our ads in this example.
ViewGroup adContainer;

protected void onCreate(Bundle bundle){
  super.onCreate(bundle);
  adContainer = (ViewGroup) findViewById(...);
  // Specify ad options (not required).
  SearchAdOptions.Builder adOptionsBuilder = new SearchAdOptions.Builder();
  adOptionsBuilder.setAdType(SearchAdOptions.AD_TYPE_TEXT);
  adOptionsBuilder.setPrefetch(true);
  adOptionsBuilder.setNumAdsRequested(3);
  // Provide a callback to trigger when ads are loaded.
  AdListener adListener = new AdListener() {
    public void onAdLoaded() {
      createAndShowAd();
    }
  };
  // Instantiate the SearchAdController.
  adController = new SearchAdController(this, "your-client-id", "your-style-id",
                                        adOptionsBuilder.build(), adListener);
}

Saat pengguna memulai kueri, buat SearchAdRequest dan panggil loadAds di SearchAdController untuk memulai permintaan iklan asinkron.

// Create the request.
SearchAdRequest.Builder requestBuilder = new SearchAdRequest.Builder();
requestBuilder.setQuery("user query here");
// Load the ads.
adController.loadAds(requestBuilder.build());

Terapkan callback onAdLoaded Anda untuk mengisi iklan yang dimuat ke tampilan iklan.

private void createAndShowAd() {
  // Create a new view that will contain the ad.
  View adView = adController.createAdView();
  // Attach the new view to the view hierarchy.
  adContainer.addView(adView);
  // Display the ad inside the adView. We need to provide an adKey to
  // indicate which ad is to be displayed in the adView. In this example, 
  // since we only have one ad, we can provide any constant string. However, 
  // if you intend to display multiple ads, each ad you wish to display
  // should be given a unique adKey of your choosing.
  adController.populateAdView(adView, "demoAd");
}

Iklan yang terkait dengan kueri tertentu sekarang akan muncul di adView.

Menyelidiki error

SearchAdController memerlukan objek AdListener dengan onAdLoaded() untuk memberi tahu aplikasi bahwa iklan siap ditampilkan. Anda juga harus mengimplementasikan metode onAdFailedToLoad() sehingga Anda dapat mendeteksi dan memperbaiki error. Misalnya, Anda dapat menggunakan AdListener berikut untuk men-debug penerapan:

AdListener adListener = new AdListener() {
    public void onAdLoaded() {
        // Called when an ad is loaded.
        Toast.makeText(MainActivity.this, "Ad Loaded",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Loaded");
    }

    public void onAdLeftApplication() {
        // Called when an ad leaves the application
        // (to go to the browser for example).
        Toast.makeText(MainActivity.this, "Ad Left Application",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Left Application");
    }

    @Override
    public void onAdFailedToLoad(int errorCode) {
        // Called when an ad request failed.
        Toast.makeText(MainActivity.this, "Ad Failed to Load: " + errorCode,
                Toast.LENGTH_SHORT).show();
        Log.e(MainActivity.class.getSimpleName(), "Ad Failed to Load: " +
                errorCode);
    }
};

Konstanta yang digunakan dalam metode callback onAdFailedToLoad() ditentukan di AdListener.