Penerapan Native AFS untuk Android

Google Mobile Ads SDK juga mendukung gaya penelusuran khusus. Jika aplikasi Anda sudah menggunakan Google Mobile Ads SDK, sebaiknya gunakan versi AFSMA SDK.

Jika Anda melakukan upgrade ke versi 19.0.0 atau yang lebih baru dari 18.1.0 atau versi sebelumnya, lihat panduan migrasi kami.

Prasyarat

Panduan penerapan ini mengasumsikan bahwa Anda telah memahami hal-hal berikut:

Mengimpor SDK Native AFS

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 pada dependencies untuk SDK versi terbaru:

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

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

Ikuti petunjuk ini untuk menyertakan Plugin Matcher 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 dibuat tetapi berpotensi menyebabkan error runtime. Atau, terapkan ResolutionStrategy failOnVersionConflict() ke project Anda untuk menyebabkan error build saat versi Layanan Google Play yang tidak kompatibel digunakan dalam project Anda. Simpan perubahan, lalu klik Sync Project with Gradle Files di toolbar.

Menggunakan AndroidX, bukan Android Support Library

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

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

Class

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

SearchAdController

  • Kelas ini bertanggung jawab untuk meminta iklan secara asinkron, menyimpan iklan dalam cache dan mengambil iklan, serta merender iklan.
  • Setiap konteks iklan memerlukan SearchAdController terpisah; misalnya, jika Anda memiliki layar yang menampilkan iklan bersama daftar hasil penelusuran dan layar lain yang menampilkan iklan bersama detail untuk produk tertentu, Anda harus membuat dua instance SearchAdController terpisah, satu untuk setiap kasus.
  • Konstruktor ini perlu memberikan kode properti web (ID penayang), ID gaya agar dapat diterapkan ke iklan yang ditampilkan, dan SearchAdOptions. Context yang diberikan di konstruktor harus berupa Activity yang berisi SearchAdController dan tempat Anda akan menempatkan View iklan.
  • Panggil loadAds untuk menunjukkan penelusuran pengguna baru dan memulai permintaan iklan asinkron. Semua iklan yang dimuat dari panggilan sebelumnya ke loadAds akan dihapus dari cache iklan internal saat panggilan baru dilakukan.
  • Membuat View dengan createAdView untuk menampilkan materi iklan.
  • Setelah iklan dimuat, panggil populateAdView dengan View yang sebelumnya dibuat dengan createAdView untuk merender iklan yang di-cache ke View tersebut. Selain 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 ditampilkan. Misalnya, jika populateAdView dipanggil untuk pertama kalinya dengan adKey="keyA" dan merender iklan untuk sepatu bot hiking, setiap panggilan berikutnya ke populateAdView dengan adKey="keyA" akan mengisi iklan yang sama untuk sepatu bot hiking. (Melakukan panggilan baru ke loadAds akan 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() pada SearchAdOptions.Builder untuk membuat 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 di SearchAdController dengan SearchAdRequest untuk memulai permintaan iklan asinkron. Panggil build() pada SearchAdRequest.Builder untuk membuat objek SearchAdRequest.

AdListener

  • Implementasikan 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 pertama 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 kini akan muncul di adView.

Menyelidiki error

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

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.