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) to narzędzie do ochrony prywatności i wiadomości, które pomoże Ci zarządzać wyborami użytkowników dotyczącymi 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

Utwórz wiadomości dla użytkowników za pomocą jednej z dostępnych opcji wiadomości dla użytkowników 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 build.gradle aplikacji zsynchronizuj projekt z plikami Gradle.

Dodawanie identyfikatora 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 na wykorzystanie danych, wykonaj te czynności:

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

Prośba o informacje dotyczące zgody

Za każdym razem, gdy uruchamiasz aplikację, powinnaś poprosić o zaktualizowanie informacji o zgodzie użytkownika, używając do tego tagu 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 wiadomości dotyczące ochrony prywatności wymagają, aby aplikacje umożliwiały użytkownikom zmianę opcji prywatności w dowolnym momencie.

Ostrzeżenie: w przypadku wygaśnięcia zgody na wykorzystanie danych inne sposoby sprawdzania stanu zgody, np. pamięć podręczna w aplikacji lub zapisany wcześniej ciąg tekstowy zgody, mogą spowodować pojawienie się błędu dotyczącego przejrzystości i uzyskiwania zgody na przetwarzanie danych w wersji 3.3.

W razie potrzeby wczytaj i pokaż formularz wiadomości o ochronie prywatności

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

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.

Poniższy kod pokazuje, jak poprosić o najnowsze informacje o zgodzie użytkownika. W razie potrzeby kod wczyta i wyświetli formularz z wiadomością dotyczącą 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 wymagany jest punkt wejścia dotyczący prywatności, dodaj do aplikacji widoczny i interaktywny element interfejsu, który przedstawia 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świetlanie formularza opcji prywatności

Gdy użytkownik wejdzie w interakcję z 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 poprosisz o wyświetlanie reklam w aplikacji, sprawdź, czy użytkownik wyraził na to zgodę za pomocą canRequestAds(). Podczas zbierania zgody należy sprawdzić 2 miejsca:

• Po wyrażeniu zgody w bieżącej sesji.
• Zaraz po nawiązaniu połączenia z firmą requestConsentInfoUpdate(). Możliwe, że zgoda została uzyskana w poprzedniej sesji. W ramach najlepszej praktyki dotyczącej opóźnień zalecamy, aby nie czekać na zakończenie wywołania zwrotnego, aby można było jak najszybciej rozpocząć wczytywanie reklam po uruchomieniu aplikacji.

Uwaga: funkcja canRequestAds() zawsze zwraca wartość false, dopóki nie wywołasz funkcji 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()
}

Po uzyskaniu zgody użytkownika kod ten konfiguruje pakiet SDK do reklam mobilnych Google:

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 emulatorów nie trzeba dodawać do listy identyfikatorów urządzeń, ponieważ domyślnie są to urządzenia testowe.

1. Zadzwoń do firmy requestConsentInfoUpdate().

2. Sprawdź dane wyjściowe dziennika pod kątem komunikatu podobnego do tego, który zawiera identyfikator urządzenia i informacje o dodaniu 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. Zmodyfikuj kod, aby wywołać funkcję ConsentDebugSettings.Builder().TestDeviceHashedIds i przekazać 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,
       // ...
   )
   

Wymuszenie lokalizacji geograficznej

Pakiet SDK UMP umożliwia testowanie działania aplikacji tak, jakby urządzenie znajdowało się w różnych regionach, np. w Europejskim Obszarze Gospodarczym lub Wielkiej Brytanii. Aby to zrobić, użyj parametru setDebugGeography(). 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 UMP SDK warto zresetować stan pakietu SDK, aby można było symulować pierwsze uruchomienie aplikacji przez użytkownika. W tym celu pakiet SDK udostępnia metodę reset().

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

Uwaga: ta metoda jest przeznaczona tylko do testów. Nie należy wywoływać metody reset() w kodzie produkcyjnym.

Przykłady w GitHub

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