Rozpocznij

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

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 w swoim koncie Ad Managera. Pakiet SDK UMP próbuje wyświetlić wiadomość dotyczącą prywatności utworzoną na podstawie identyfikatora aplikacji Ad Managera 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 Ad Managera. 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>

Zbieranie zgody

Aby uzyskać zgodę, wykonaj te czynności:

1. Prośba o najnowsze informacje o zgodzie użytkownika.
2. W razie potrzeby 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(). Ta prośba sprawdza te kwestie:

• Czy wymagana jest zgoda użytkownika. Może to być na przykład pierwsza zgoda na wykorzystanie danych lub zgoda udzielona wcześniej 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.

W razie potrzeby wczytaj i pokaż formularz dotyczący 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.

Ten 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:

// 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

// 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ącej prywatności są wyświetlane w miejscu wejścia opcji prywatności przygotowanym przez wydawcę, co pozwala użytkownikom w dowolnym momencie zarządzać opcjami prywatności. 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 wymagany jest punkt wejścia opcji prywatności

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

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

/** 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.

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

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:

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

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

Wyślij żądanie

Zanim poprosisz o wyświetlanie reklam w aplikacji, sprawdź, czy użytkownik udzielił zgody za pomocą canRequestAds(). Podczas zbierania zgody należy sprawdzić 2 miejsca:

• Po wyrażeniu zgody w bieżącej sesji.
• Natychmiast po zakończeniu rozmowy 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, dzięki czemu można jak najszybciej rozpocząć wczytywanie reklam po uruchomieniu aplikacji.

Jeśli podczas procesu zbierania zgód wystąpi błąd, sprawdź, czy możesz nadal 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:

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

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:

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

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ę w aplikacji podczas jej tworzenia, wykonaj te czynności, aby zarejestrować urządzenie testowe za pomocą kodu. Zanim opublikujesz aplikację, usuń kod, który ustawia te identyfikatory testowych urządzeń.

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 instrukcje dodania go jako urządzenia testowego:

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

3. Skopiuj identyfikator testowego urządzenia 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. DebugGeography Pamiętaj, że ustawienia debugowania działają tylko na urządzeniach testowych.

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,
    ...
);

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,
    ...
)

Resetowanie stanu zgody

Podczas testowania aplikacji za pomocą pakietu UMP SDK warto zresetować jego stan, aby móc symulować pierwsze uruchomienie aplikacji przez użytkownika. W tym celu pakiet SDK udostępnia metodę reset().

consentInformation.reset();

consentInformation.reset()

Przykłady w GitHub

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