Implementacja AdSense dla wyszukiwania do aplikacji mobilnych (AFMA) na Androidzie

Wymagania wstępne

W tym przewodniku po implementacji przyjęto założenie, że znasz już te zagadnienia:

  • Protokół implementacji reklam w wyszukiwarce niestandardowej AdSense dla wyszukiwania (CSA)
  • Tworzenie aplikacji na Androida
  • Powiązanie pakietu SDK do reklam mobilnych Google na Androida (teraz należącego do Usług Google Play) z projektem w Android Studio. Wymagana jest wersja 9.0.0 Usług Google Play.

Zajęcia

Aby wyświetlać w swojej aplikacji reklamy AFSMA (znane też jako dynamiczne reklamy wysokości w wyszukiwarce), zastosuj te klasy:

SearchAdView

  • Ta klasa dziedziczy z klasy ViewGroup Androida i wyświetla reklamy AFSMA. SearchAdView wysyła żądanie reklamy z zastosowaniem DynamicHeightSearchAdRequest i renderuje zwrócone reklamy. Należy dodać SearchAdView do dowolnej z istniejących grup widoków aplikacji.
  • Wystąpienie SearchAdView musi być utworzone w kontekście, w którym działa SearchAdView. Zwykle jest to Activity.
  • Po utworzeniu instancji SearchAdView musisz wywołać metodę setAdSize() z atrybutem AdSize.SEARCH, by wysyłać żądania reklam AFSMA. Inne wartości wyliczeniowe będą zgłaszać żądania reklam niezgodnych z AdSense dla wyszukiwania do aplikacji mobilnych.
  • Wywołaj metodę setAdUnitId() w tym obiekcie za pomocą kodu właściwości.

DynamicHeightSearchAdRequest.Builder

  • Ta klasa zawiera parametry żądania reklamy. Działa to analogicznie do konfigurowania parametrów w obiektach żądań reklam JavaScript (opcje stron i jednostki) w przypadku AdSense dla wyszukiwania na komputery i w internecie mobilnym.
  • Ustaw parametry za pomocą odpowiednich ustawiających (czyli użyj wywołania setQuery(), aby ustawić parametr zapytania).

Przykładowa implementacja

Przykład poniżej pokazuje użycie elementu Activity do utworzenia widoku SearchAdView jako widoku podrzędnego ViewGroup. Aby wysyłać żądania reklam AFSMA, obiekt SearchAdView musi wywoływać metodę setAdSize() z parametrem AdSize.SEARCH.

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

// Create the SearchAdView
final SearchAdView searchAdView = new SearchAdView(this);

// Set parameter to request for dynamic height search ads
searchAdView.setAdSize(AdSize.SEARCH); // Important!

// Replace with your pub ID (e.g. ms-app-pub-9616389000213823)
searchAdView.setAdUnitId("ms-app-pub-################");

// Add searchAdView to parent view group
...

W tym samym elemencie Activity utwórz element DynamicHeightSearchAdRequest.Builder, który określa parametry reklamy, która będzie renderowana w SearchAdView. Reklamy AdSense dla wyszukiwania mobilnego konfiguruje się tak samo jak reklamy AdSense w wyszukiwarce niestandardowej. Więcej informacji znajdziesz w dokumentacji dotyczącej reklam AdSense w wyszukiwarce niestandardowej.

// Create the ad request
DynamicHeightSearchAdRequest.Builder builder =
        new DynamicHeightSearchAdRequest.Builder();
builder.setQuery("flowers");
builder.setNumber(2);

// Replace with the ID of a style from your custom search styles
builder.setAdvancedOptionValue("csa_styleId", "0000000001");

// Customization options (set using setters on
// DynamicHeightSearchAdRequest.Builder)
builder.setAdTest(true);

Inne opcje dostosowania są dostępne po ustawieniu dodatkowych właściwości w obiekcie DynamicHeightSearchAdRequest.Builder.

Aby wysłać żądanie reklamy, wywołaj metodę loadAd() za pomocą obiektu DynamicHeightSearchAdRequest.Builder z obiektu SearchAdView:

searchAdView.loadAd(builder.build());

Opcje zaawansowane

Większość parametrów żądania reklamy można ustawić za pomocą metod ustawiania w obiekcie DynamicHeightSearchAdRequest.Builder. Wszystkie parametry, które nie mają metody ustawiającej w DynamicHeightSearchAdRequest.Builder, można ustawiać za pomocą par klucz-wartość za pomocą metody setAdvancedOptionValue(). Pełną listę ustawień, które można skonfigurować, korzystając z metody setAdvancedOptionValue(), znajdziesz w dokumentacji dotyczącej reklam AdSense w wyszukiwarce niestandardowej.

Aby parametr był skonfigurowany prawidłowo, parametr klucza musi być poprzedzony „csa_”. 

// Advanced customization options (set using key-value pair)

// Set a parameter (parameter_name) and its value (parameter_value)
// builder.setAdvancedOptionValue("csa_parameter_name", "parameter_value");

// Example: Show visible URL below description
// (domainLinkAboveDescription: false)
builder.setAdvancedOptionValue("csa_domainLinkAboveDescription", "false");

Jeśli użyjesz metody ustawiającej parametru i ustawisz ją za pomocą funkcji setAdvancedOptionValue, drugie wywołanie zastąpi wartość z pierwszego wywołania.

Analizowanie błędów

SearchAdView (searchAdView tutaj) zawiera metodę setAdListener(), która pomaga w badaniu błędów. W ramach tego samego konta Activity:

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

    @Override
    public void onAdOpened() {
        // Called when an ad opens an overlay that covers the screen
        super.onAdOpened();
        Toast.makeText(MainActivity.this, "Ad Opened",
                Toast.LENGTH_SHORT).show();
        Log.d(MainActivity.class.getSimpleName(), "Ad Opened");
    }

    @Override
    public void onAdLeftApplication() {
        // Called when an ad leaves the application
        // (to go to the browser for example)
        super.onAdLeftApplication();
        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
        super.onAdFailedToLoad(errorCode);
        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ą opisane w dokumentacji interfejsu API.

Przygotowanie do wymagań Google Play dotyczących ujawniania informacji

W maju 2021 roku w Google Play pojawiła się nowa sekcja Bezpieczeństwo danych z pochodzącymi od deweloperów informacjami dotyczącymi zbierania, udostępniania i zabezpieczania danych użytkowników przez aplikacje.

Na tej stronie znajdziesz informacje, które pomogą Ci spełnić wymagania dotyczące ujawniania informacji w odniesieniu do korzystania z pakietu SDK dla reklam natywnych AFS (dotyczy to również korzystania z AdSense dla Zakupów Google). Na tej stronie znajdziesz informacje o tym, czy i jak nasze pakiety SDK postępują z danymi użytkowników.

Dążymy do prezentowania informacji w jak najbardziej przejrzysty sposób. Jednak jako deweloper aplikacji ponosisz wyłączną odpowiedzialność za decyzje związane z sekcją Bezpieczeństwo danych w formularzu Google Play dotyczące zbierania, udostępniania i zabezpieczania danych użytkowników przez Twoją aplikację.

Jak korzystać z informacji na tej stronie

Ta strona zawiera informacje o tym, jakie dane użytkowników są zbierane tylko przez najnowszą wersję pakietu SDK.

Aby spełnić wymagania dotyczące ujawniania informacji, skorzystaj z przewodnika po typach danych na Androidzie, który pomoże Ci określić, jaki typ danych najlepiej opisuje gromadzone przez Ciebie dane. W oświadczeniu o korzystaniu z danych musisz uwzględnić sposób udostępniania i wykorzystywania zgromadzonych danych przez aplikację.

Pakiet SDK typu danych ma dostęp do danych i zbiera je

Pakiety:

com.google.android.gms:play-services-afs-native

com.google.ads.afsn

Dane zbierane automatycznie

Pakiet SDK AdSense dla wyszukiwania automatycznie zbiera następujące dane. Wszystkie dane są przesyłane z urządzenia do Google w celu wyświetlania reklam. Dane są w trakcie przesyłania szyfrowane. Dane osobowe użytkownika nigdy nie są zbierane, chyba że aplikacja wyśle zapytanie użytkownika.

Dane Te dane są zbierane w następujących celach...
Adres IP Podsumowanie:
  • Zapobieganie oszustwom, bezpieczeństwo i zgodność z przepisami
  • Cele marketingowe
  • Wyznacz przybliżoną lokalizację
Szczegóły:
Adres IP jest używany do monitorowania oszustw i nadużyć, a także do określania przybliżonej lokalizacji użytkownika.

Przybliżona lokalizacja jest następnie używana, aby zapewnić zgodność wyświetlanych reklam z lokalnymi przepisami, a także do wyświetlania reklam odpowiednich do przybliżonej lokalizacji geograficznej użytkownika.

Aktywność w aplikacjach
  • Wyświetlenia stron i kliknięcia w aplikacji
  • Historia wyszukiwania w aplikacji
 Podsumowanie:
  • Statystyki
  • Zapobieganie oszustwom, bezpieczeństwo i zgodność z przepisami
  • Cele marketingowe
  • Personalizacja
Szczegóły:
Aplikacja przekazuje nam zapytanie użytkownika, dzięki czemu możemy wyświetlać reklamy w wyszukiwarce pasujące do słowa kluczowego. Mierzymy wyświetlenia i zaangażowanie (kliknięcia) w wyświetlane reklamy.
Diagnostyka Podsumowanie:
  • Statystyki
Szczegóły:
SDK mierzy opóźnienie renderowania reklam, aby umożliwić wprowadzanie ulepszeń w usłudze i jej pomiar. Wysyłamy też raporty o awariach i błędach, a w razie potrzeby dodajemy też inne narzędzia pozwalające zrozumieć, jak wydawcy korzystają z funkcji.
Identyfikatory urządzenia i inne Podsumowanie:
  • Zapobieganie oszustwom, bezpieczeństwo i zgodność z przepisami
  • Cele marketingowe
Szczegóły:
Identyfikator urządzenia pomaga w monitorowaniu oszustw i nadużyć, a także w mierzeniu skuteczności reklam.