Rozpocznij

Ważne: pakiet SDK do uzyskiwania zgody na przetwarzanie danych został wycofany. Teraz zastępujemy go – pakiet SDK User Messaging Platform (UMP).

Pakiet SDK platformy do personalizowania wiadomości wyświetlanych użytkownikom (UMP) od Google to narzędzie do zarządzania prywatnością i wyświetlania wiadomości, które ułatwia Ci zarządzanie ustawieniami prywatności. Więcej informacji znajdziesz w artykule Informacje o narzędziu Prywatność i wyświetlanie wiadomości.

Wymagania wstępne

• Poziom interfejsu API 21 lub nowszy

Tworzenie typu wiadomości

Wiadomości dla użytkowników możesz tworzyć w jednym z dostępnych typów wiadomości na karcie Prywatność i wyświetlanie wiadomości na koncie AdMob. Pakiet SDK UMP próbuje wyświetlić wiadomość dotyczącą prywatności utworzoną na podstawie identyfikatora aplikacji AdMob ustawionego w projekcie.

Więcej informacji znajdziesz w artykule na temat prywatności i wyświetlania wiadomości.

Instalowanie za pomocą Gradle

Dodaj zależność do pakietu SDK platformy do personalizowania wiadomości wyświetlanych użytkownikom od Google do pliku Gradle na poziomie aplikacji modułu (zwykle app/build.gradle):

dependencies {
  implementation("com.google.android.ump:user-messaging-platform:3.1.0")
}

Po wprowadzeniu zmian w narzędziu build.gradle aplikacji zsynchronizuj swój projekt z plikami Gradle.

Dodaj identyfikator aplikacji

Identyfikator aplikacji znajdziesz w interfejsie AdMob. Dodaj identyfikator do pliku AndroidManifest.xml za pomocą tego fragmentu kodu:

<manifest>
  <application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
  </application>
</manifest>

Uzyskiwanie zgody

Aby uzyskać zgodę użytkowników, wykonaj te czynności:

1. Prośba o aktualne informacje o zgodzie użytkownika.
2. W razie potrzeby wczytaj i wyświetl formularz zgody.

Prośba o informacje dotyczące zgody

Należy prosić o aktualizację informacji o zgodzie użytkownika przy każdym uruchomieniu aplikacji za pomocą narzędzia requestConsentInfoUpdate(). To żądanie sprawdza, czy:

• Czy wymagana jest zgoda użytkownika. np. zgoda jest wymagana po raz pierwszy lub poprzednia decyzja już wygasła.
• Czy wymagany jest punkt wejścia opcji prywatności. Niektóre komunikaty dotyczące prywatności wymagają, aby aplikacje umożliwiały użytkownikom zmianę ustawień prywatności w dowolnym momencie.

Ostrzeżenie: korzystanie z innych sposobów sprawdzania stanu zgody, np. z pamięci podręcznej aplikacji lub wcześniej zapisanego ciągu znaków zgody, może spowodować błąd TCF 3.3, jeśli zgoda wygasła.

W razie potrzeby wczytaj i wyświetl formularz wiadomości dotyczącej ochrony prywatności

Po otrzymaniu najnowszego stanu zgody wywołaj funkcję loadAndShowConsentFormIfRequired(), aby załadować formularze wymagane do uzyskania zgody użytkownika. Po załadowaniu formularze są od razu widoczne.

Ważne: jeśli żaden formularz z informacjami o prywatności nie wymaga zbierania zgody użytkownika przed wysłaniem prośby o reklamy, wywołanie funkcji zwrotnej zostanie wykonane natychmiast.

Ten kod pokazuje, jak zażądać najnowszych informacji o zgodzie użytkownika. W razie potrzeby kod wczytuje się i wyświetla formularz wiadomości dotyczącej ochrony prywatności:

Java

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () ->
        UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            activity,
            formError -> {
              // Consent has been gathered.
              onConsentGatheringCompleteListener.consentGatheringComplete(formError);
            }),
    requestConsentError ->
        onConsentGatheringCompleteListener.consentGatheringComplete(requestConsentError));
GoogleMobileAdsConsentManager.java

Kotlin

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
  activity,
  params,
  {
    UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
      // Consent has been gathered.
      onConsentGatheringCompleteListener.consentGatheringComplete(formError)
    }
  },
  { requestConsentError ->
    onConsentGatheringCompleteListener.consentGatheringComplete(requestConsentError)
  },
)
GoogleMobileAdsConsentManager.kt

Opcje prywatności

Niektóre formularze wiadomości dotyczących ochrony prywatności są wyświetlane w wyrenderowanym przez wydawcę punkcie wejścia opcji prywatności, dzięki czemu użytkownicy mogą w każdej chwili zarządzać tymi opcjami. Aby dowiedzieć się więcej o tym, która wiadomość wyświetla się użytkownikom w punkcie wejścia do ustawień prywatności, zapoznaj się z artykułem Dostępne typy wiadomości dla użytkowników.

Sprawdzanie, czy punkt wejścia opcji prywatności jest wymagany

Po wywołaniu funkcji requestConsentInfoUpdate() sprawdź, czy w Twojej aplikacji jest wymagany punkt wejścia opcji prywatności. W tym celu wywołaj funkcję getPrivacyOptionsRequirementStatus():

Java

/** Helper variable to determine if the privacy options form is required. */
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}
GoogleMobileAdsConsentManager.java

Kotlin

/** Helper variable to determine if the privacy options form is required. */
val isPrivacyOptionsRequired: Boolean
  get() =
    consentInformation.privacyOptionsRequirementStatus ==
      ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED
GoogleMobileAdsConsentManager.kt

Dodawanie widocznego elementu do aplikacji

Jeśli punkt wejścia prywatności jest wymagany, dodaj do aplikacji widoczny i interaktywny element interfejsu przedstawiający formularz opcji prywatności. Jeśli nie jest wymagany punkt wejścia dotyczący prywatności, skonfiguruj element interfejsu tak, aby nie był widoczny ani interaktywny.

Java

if (googleMobileAdsConsentManager.isPrivacyOptionsRequired()) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu();
}
MyActivity.java

Kotlin

if (googleMobileAdsConsentManager.isPrivacyOptionsRequired) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu()
}
MainActivity.kt

Wyświetl formularz opcji prywatności.

Gdy użytkownik wejdzie w interakcję z Twoim elementem, wyświetl formularz opcji prywatności:

Java

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener);
GoogleMobileAdsConsentManager.java

Kotlin

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

Wyślij żądanie

Zanim wyślesz prośbę o reklamy w aplikacji, sprawdź, czy masz zgodę użytkownika za pomocą canRequestAds(). Uzyskując zgodę, można to sprawdzić w dwóch miejscach:

• Po wyrażeniu zgody w bieżącej sesji.
• Natychmiast po zakończeniu rozmowy requestConsentInfoUpdate(). Możliwe, że zgoda została uzyskana w poprzedniej sesji. Zalecamy, aby nie czekać na zakończenie wywołania zwrotnego i w razie potrzeby zacząć wczytywać reklamy jak najszybciej po uruchomieniu aplikacji.

Uwaga: canRequestAds() zawsze zwraca false, dopóki nie wywołasz requestConsentInfoUpdate()

Jeśli podczas uzyskiwania zgody użytkowników wystąpi błąd, musisz sprawdzić, czy możesz wysyłać żądania reklam. Pakiet UMP SDK używa stanu zgody z poprzedniej sesji.

Ten kod sprawdza, czy możesz wysyłać żądania reklam podczas procesu uzyskiwania zgody:

Java

googleMobileAdsConsentManager.gatherConsent(
    this,
    consentError -> {
      if (consentError != null) {
        // Consent not obtained in current session.
        Log.w(
            TAG,
            String.format("%s: %s", consentError.getErrorCode(), consentError.getMessage()));
      }

      if (googleMobileAdsConsentManager.canRequestAds()) {
        initializeMobileAdsSdk();
      }
      // ...
    });

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds()) {
  initializeMobileAdsSdk();
}

Kotlin

googleMobileAdsConsentManager.gatherConsent(this) { error ->
  if (error != null) {
    // Consent not obtained in current session.
    Log.d(TAG, "${error.errorCode}: ${error.message}")
  }

  if (googleMobileAdsConsentManager.canRequestAds) {
    initializeMobileAdsSdk()
  }
  // ...
}

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds) {
  initializeMobileAdsSdk()
}

Ten kod konfiguruje pakiet SDK do reklam mobilnych Google po uzyskaniu zgody użytkownika:

Java

private void initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return;
  }
  new Thread(
          () -> {
            // Initialize the Google Mobile Ads SDK on a background thread.
            MobileAds.initialize(this, initializationStatus -> {});

            // Load an ad on the main thread.
            runOnUiThread(this::loadBanner);
          })
      .start();
}
MyActivity.java

Kotlin

private fun initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return
  }
  CoroutineScope(Dispatchers.IO).launch {
    // Initialize the Google Mobile Ads SDK on a background thread.
    MobileAds.initialize(this@MainActivity) {}

    runOnUiThread {
      // Load an ad on the main thread.
      loadBanner()
    }
  }
}
MainActivity.kt

Testowanie

Jeśli chcesz przetestować integrację z aplikacją podczas jej programowania, wykonaj te czynności, aby automatycznie zarejestrować urządzenie testowe. Zanim opublikujesz aplikację, usuń kod, który ustawia te identyfikatory testowych urządzeń.

Uwaga: od wersji 2.2.0 emulatory nie muszą być dodawane do listy identyfikatorów urządzeń, ponieważ są domyślnie urządzeniami testowymi.

1. Zadzwoń do firmy requestConsentInfoUpdate().

2. Sprawdź w logu, czy w danych wyjściowych znajduje się komunikat podobny do tego poniżej. Zawiera on identyfikator urządzenia i sposób dodawania go jako urządzenia testowego:

   Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
   

3. Skopiuj identyfikator urządzenia testowego do schowka.

4. Zmień kod, aby wywoływał funkcję ConsentDebugSettings.Builder().TestDeviceHashedIds i przekazywał listę identyfikatorów urządzeń testowych.

   Java

   ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
       .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
       .build();
   
   ConsentRequestParameters params = new ConsentRequestParameters
       .Builder()
       .setConsentDebugSettings(debugSettings)
       .build();
   
   consentInformation = UserMessagingPlatform.getConsentInformation(this);
   // Include the ConsentRequestParameters in your consent request.
   consentInformation.requestConsentInfoUpdate(
       this,
       params,
       // ...
   );
   

   Kotlin

   val debugSettings = ConsentDebugSettings.Builder(this)
       .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
       .build()
   
   val params = ConsentRequestParameters
       .Builder()
       .setConsentDebugSettings(debugSettings)
       .build()
   
   consentInformation = UserMessagingPlatform.getConsentInformation(this)
   // Include the ConsentRequestParameters in your consent request.
   consentInformation.requestConsentInfoUpdate(
       this,
       params,
       // ...
   )
   

Wymuś użycie lokalizacji geograficznej

Dzięki pakietowi UMP SDK możesz przy użyciu setDebugGeography() przetestować działanie aplikacji w taki sposób, jakby urządzenie znajdowało się w różnych regionach, np. Europejskim Obszarze Gospodarczym czy Wielkiej Brytanii. Pamiętaj, że ustawienia debugowania działają tylko na urządzeniach testowych.

Java

ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build();

ConsentRequestParameters params = new ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build();

consentInformation = UserMessagingPlatform.getConsentInformation(this);
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
);

Kotlin

val debugSettings = ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build()

val params = ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build()

consentInformation = UserMessagingPlatform.getConsentInformation(this)
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
)

Zresetuj stan zgody użytkownika

Podczas testowania aplikacji za pomocą pakietu SDK UMP warto zresetować stan pakietu SDK, aby przeprowadzić symulację pierwszej instalacji aplikacji u użytkownika. Pakiet SDK udostępnia do tego metodę reset().

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

Uwaga: ta metoda jest przeznaczona tylko do testów. Nie wywołuj funkcji reset() w kodzie produkcyjnym.

Przykłady w GitHubie

Pełny przykład integracji pakietu UMP SDK omówionego na tej stronie znajdziesz w plikach Java BannerExample i Kotlin BannerExample.