Implementacja reklam natywnych AdSense dla wyszukiwania na Androida

Pakiet SDK do reklam mobilnych Google obsługuje też niestandardowe style reklamy w wyszukiwarce. Jeśli Twoja aplikacja korzysta już z pakietu SDK do reklam mobilnych Google, zalecamy korzystanie z pakietu SDK AdSense dla wyszukiwania.

Jeśli aktualizujesz aplikację z wersji 18.1.0 lub nowszej do wersji 19.0.0 lub nowszej, zapoznaj się z naszym przewodnikiem po migracji.

Wymagania wstępne

W tym przewodniku po implementacji zakładamy, że znasz te zagadnienia:

Importowanie natywnego pakietu SDK AdSense dla wyszukiwania

Dodaj pakiet SDK

Aby dodać do aplikacji natywny pakiet SDK AdSense dla wyszukiwania, wykonaj te czynności:

Otwórz plik build.gradle w katalogu modułu aplikacji. W sekcji dependencies dodaj nową regułę kompilacji dla najnowszej wersji pakietu SDK:

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

Upewnij się, że obiekt build.gradle najwyższego poziomu zawiera odwołanie do repozytorium google() lub maven { url "https://maven.google.com" }.

Wykonaj te instrukcje, aby dołączyć do swojego projektu samodzielną wtyczkę do dopasowywania wersji Google Play. Zastosowanie tej wtyczki powoduje błąd kompilacji Gradle, gdy natywny pakiet SDK AdSense dla wyszukiwania jest używany z niezgodną wersją Usług Google Play, zamiast zezwalać aplikacji na kompilację, ale może powodować awarie podczas działania. Możesz też zastosować w projekcie failOnVersionConflict() ResolutionStrategy, aby powodować błąd kompilacji w przypadku użycia w projekcie niezgodnych wersji usług Google Play. Zapisz zmiany i na pasku narzędzi kliknij Synchronizuj projekt z plikami Gradle.

Używaj AndroidaX zamiast bibliotek pomocy Androida

Począwszy od wersji 17.0.0 pakietu SDK Twoja aplikacja musi korzystać z bibliotek Jetpack (AndroidX) zamiast z bibliotek pomocy Androida. Wymagania dotyczące zgodności:

  • Ustaw com.android.tools.build:gradle na wersję 3.2.1 lub nowszą.
  • Ustaw compileSdkVersion na 28 lub więcej
  • Zaktualizuj aplikację, aby używać Jetpack (AndroidX). Wykonaj instrukcje opisane w artykule Migracja na AndroidaX.

Zajęcia

Aby wyświetlać w aplikacji reklamy natywne AdSense dla wyszukiwania, zaimplementuj te klasy:

SearchAdController

  • Ta klasa odpowiada za asynchroniczne żądania reklam, buforowanie i pobieranie reklam oraz renderowanie reklam.
  • Każdy kontekst reklamy wymaga osobnego elementu SearchAdController. Jeśli np. masz ekran, na którym reklamy wyświetlają się obok listy wyników wyszukiwania, i drugi, na którym wyświetlane są reklamy ze szczegółowymi informacjami o danym produkcie, musisz utworzyć 2 oddzielne wystąpienia SearchAdController, po jednej dla każdego przypadku.
  • Konstruktor musi zawierać kod usługi internetowej (identyfikator wydawcy), identyfikator stylu, który ma być stosowany do zwracanych reklam, oraz SearchAdOptions. Obiekt Context podany w konstruktorze musi być obiektem Activity zawierającym SearchAdController i miejscem, w którym chcesz umieścić reklamę View.
  • Wywołaj loadAds, aby wskazać nowe wyszukiwanie użytkownika i zainicjować asynchroniczne żądanie reklamy. Po wywołaniu nowego wywołania wszystkie reklamy wczytane w ramach poprzednich wywołań funkcji loadAds są usuwane z wewnętrznej pamięci podręcznej reklam.
  • Aby wyświetlać kreacje, utwórz View z parametrem createAdView.
  • Po załadowaniu reklam wywołaj populateAdView z parametrem View wygenerowanym wcześniej za pomocą createAdView, by wyrenderować w tym elemencie View reklamę z pamięci podręcznej. Oprócz pola View, które ma zostać wypełnione, podaj adKey – dowolny ciąg znaków umożliwiający jednoznaczne zidentyfikowanie reklamy. Powiąże to konkretną kreację wyświetlaną z pamięci podręcznej z elementem adKey, więc gdy ta sama wartość adKey zostanie przekazana do przyszłego wywołania populateAdView, ta sama reklama zostanie zwrócona. Jeśli na przykład parametr populateAdView jest wywoływany po raz pierwszy za pomocą metody adKey="keyA" i wyrenderuje reklamę butów turystycznych, każde kolejne wywołanie populateAdView z parametrem adKey="keyA" spowoduje wyświetlenie tej samej reklamy butów trekkingowych. (Nowe wywołanie funkcji loadAds usuwa wszystkie reklamy z pamięci podręcznej i powiązane z nimi klucze reklam).

SearchAdOptions

  • Przekaż ten obiekt do konstruktora SearchAdController, aby dostosować sposób wysyłania i wyświetlania reklam. Wywołaj build() w SearchAdOptions.Builder, aby utworzyć obiekt SearchAdOptions.

View

  • Utwórz obiekt View do wstrzymywania reklam, wywołując createAdView() w SearchAdController. Wyświetla maksymalnie 1 reklamę w danym momencie, ale ten sam View może być używany do recyklingu, aby z czasem wyświetlać różne reklamy.

SearchAdRequest

  • Wywołaj metodę loadAds w SearchAdController za pomocą parametru SearchAdRequest, aby zainicjować asynchroniczne żądanie reklamy. Wywołaj build() w SearchAdRequest.Builder, aby utworzyć obiekt SearchAdRequest.

AdListener

  • Zaimplementuj ten interfejs i przekaż go do konstruktora SearchAdController, aby zarejestrować wywołania zwrotne w kilku stanach.
  • Uwaga: wywołania zwrotne AdListener nie będą wywoływane w przypadku anulowanego żądania (wywołania loadAds, które zostało wyparte przez inne wywołanie loadAds przed zakończeniem pierwszego połączenia).

Przykładowa implementacja

Poniższy przykład pokazuje, jak utworzyć SearchAdController w przykładowym pliku 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);
}

Gdy użytkownik inicjuje zapytanie, utwórz w elemencie SearchAdController polecenie SearchAdRequest i wywołaj polecenie loadAds, aby uruchomić asynchroniczne żądanie reklamy.

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

Zaimplementuj wywołanie zwrotne onAdLoaded, aby wczytać wczytaną reklamę w jej widoku.

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");
}

Reklama związana z danym zapytaniem pojawi się teraz w adView.

Badanie błędów

SearchAdController wymaga obiektu AdListener z metodą onAdLoaded(), aby powiadomić aplikację, że reklamy są gotowe do wyświetlenia. Musisz też zaimplementować metodę onAdFailedToLoad(), aby móc wykrywać i poprawiać błędy. Aby na przykład debugować implementację, możesz użyć na przykład tego kodu AdListener:

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);
    }
};

Stałe używane w metodzie wywołania zwrotnego onAdFailedToLoad() są zdefiniowane w elemencie AdListener.