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 jej użycie w jego wersji AdSense SDK.

Jeśli przechodzisz na wersję 19.0.0 lub nowszą z 18.1.0 lub starszej wersji, zapoznaj się z naszym przewodnikiem po migracji.

Wymagania wstępne

W tym przewodniku po implementacji zakładamy, że znasz już następujące zagadnienia:

Zaimportuj pakiet SDK reklam natywnych AdSense dla wyszukiwania

Dodaj pakiet SDK

Aby dodać do aplikacji pakiet SDK reklam natywnych AdSense dla wyszukiwania:

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

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

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

Wykonaj te instrukcje, aby dodać do projektu samodzielną wtyczkę do dopasowywania wersji Google Play. Zastosowanie tej wtyczki powoduje wystąpienie błędu kompilacji Gradle, gdy pakiet SDK natywnego wyświetlania reklam AdSense dla reklam jest używany z niezgodną wersją Usług Google Play. Nie pozwala on aplikacji na tworzenie, choć może powodować awarie w czasie działania. Możesz też zastosować do projektu strategię failOnVersionConflict() ResolutionStrategy, która spowoduje błąd kompilacji, gdy w projekcie używane są niezgodne wersje 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, aplikacja musi korzystać z bibliotek Jetpack (AndroidX) a nie 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 później.
  • Zaktualizuj aplikację, aby używać w niej Jetpack (AndroidX). Wykonaj czynności opisane w sekcji Migracja na AndroidaX.

Zajęcia

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

SearchAdController

  • Ta klasa odpowiada za asynchroniczne żądania reklam, zapisywanie ich w pamięci podręcznej i pobieranie oraz renderowanie reklam.
  • Każdy kontekst reklamy wymaga osobnego elementu SearchAdController. Jeśli np. masz ekran, który wyświetla reklamy obok listy wyników wyszukiwania, i drugi ekran, na którym wyświetlają się reklamy obok informacji o konkretnym produkcie, utwórz 2 osobne wystąpienia parametru SearchAdController, po 1 w każdym przypadku.
  • W konstruktorze musisz podać kod usługi internetowej (identyfikator wydawcy), identyfikator stylu, który ma być stosowany do zwracanych reklam, oraz parametr SearchAdOptions. Pole Context w konstruktorze musi być obiektem Activity zawierającym SearchAdController i miejscem, w którym umieścisz reklamę View.
  • Wywołaj loadAds, aby wskazać nowe wyszukiwanie użytkownika i zainicjować asynchroniczne żądanie reklamy. Po wykonaniu nowego wywołania wszystkie reklamy wczytane z poprzednich wywołań funkcji loadAds są usuwane z wewnętrznej pamięci podręcznej reklam.
  • Aby wyświetlać kreacje, utwórz View z elementem createAdView.
  • Po wczytaniu reklam wywołaj populateAdView z poleceniem View wygenerowanym wcześniej za pomocą funkcji createAdView, aby wyrenderować reklamę z pamięci podręcznej w tym elemencie: View. Oprócz uzupełnionego pola View podaj dowolny ciąg znaków adKey, który jednoznacznie identyfikuje reklamę. Powoduje to powiązanie konkretnej kreacji reklamy zwróconej z pamięci podręcznej z tym obiektem adKey. Gdy ta sama wartość adKey zostanie przekazana w przyszłym wywołaniu do populateAdView, ta sama reklama zostanie zwrócona. Jeśli na przykład funkcja populateAdView zostanie po raz pierwszy wywołana z metodą adKey="keyA" i wyrenderuje reklamę butów trekkingowych, każde kolejne wywołanie populateAdView z parametrem adKey="keyA" wypełni tę samą reklamę butów trekkingowych. (Nowe wywołanie loadAds powoduje usunięcie wszystkich reklam z pamięci podręcznej i powiązanych z nimi kluczy reklam).

SearchAdOptions

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

View

  • Utwórz obiekt View do wstrzymywania reklam, wywołując createAdView() w SearchAdController. Wyświetla nie więcej niż 1 reklamę naraz, ale ten sam element View może być wykorzystany, aby w miarę upływu czasu wyświetlać inne reklamy.

SearchAdRequest

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

AdListener

  • Zaimplementuj ten interfejs i przekaż go do konstruktora SearchAdController, aby zarejestrować wywołania zwrotne dla kilku stanów.
  • Uwaga: wywołania zwrotne AdListener nie będą wykonywane w przypadku anulowanej prośby (czyli wywołania do loadAds, które zostało przerwane przez inne wywołanie loadAds przed zakończeniem pierwszego).

Przykładowa implementacja

Poniższy przykład pokazuje, jak utworzyć SearchAdController w przykładowym 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 zainicjuje zapytanie, utwórz SearchAdRequest i wywołaj loadAds w SearchAdController, aby rozpocząć 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 w celu umieszczenia załadowanej reklamy w widoku reklamy.

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 powiązana z danym zapytaniem pojawi się teraz w adView.

Analizowanie błędów

SearchAdController wymaga obiektu AdListener z metodą onAdLoaded(), aby powiadamiać aplikację, że reklamy są gotowe do wyświetlenia. Musisz też wdrożyć metodę onAdFailedToLoad(), która umożliwi wykrywanie i korygowanie błędów. Do debugowania implementacji możesz np. użyć 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.