Konfigurowanie pakietu SDK UMP

Pakiet SDK platformy do personalizowania wiadomości wyświetlanych użytkownikom (UMP) od Google to narzędzie do zarządzania ustawieniami prywatności i wyświetlania wiadomości. Więcej informacji znajdziesz w artykule Prywatność i wyświetlanie wiadomości.

Wymagania wstępne

• Android API na poziomie 21 lub wyższym,

Tworzenie typu wiadomości

Utwórz wiadomości dla użytkowników, korzystając z jednego 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.

Instalowanie za pomocą Gradle

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

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

Po wprowadzeniu zmian w pliku build.gradle aplikacji zsynchronizuj 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 informacji o zgodzie użytkownika

Aby uzyskać informacje o zgodzie użytkownika, wykonaj te czynności:

Zadeklaruj instancję ConsentInformation:

private final ConsentInformation consentInformation;

private lateinit var consentInformation: ConsentInformation

Zainicjuj instancję ConsentInformation:

consentInformation = UserMessagingPlatform.getConsentInformation(context);

consentInformation = UserMessagingPlatform.getConsentInformation(context)

Przy każdym uruchomieniu aplikacji należy poprosić o aktualizację informacji o zgodzie użytkownika, używając metody requestConsentInfoUpdate(). To żądanie sprawdza:

• Czy zgoda jest wymagana? Na przykład zgoda jest wymagana po raz pierwszy lub poprzednia decyzja o zgodzie wygasła.
• Czy wymagany jest punkt wejścia opcji prywatności. Niektóre wiadomości dotyczące prywatności wymagają, aby aplikacje umożliwiały użytkownikom modyfikowanie opcji prywatności w dowolnym momencie.

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () -> // Called when consent information is successfully updated.
    requestConsentError -> // Called when there's an error updating consent information.
GoogleMobileAdsConsentManager.java

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
  activity,
  params,
  {
    // Called when consent information is successfully updated.
  },
  { requestConsentError ->
    // Called when there's an error updating consent information.
  },
)
GoogleMobileAdsConsentManager.kt

Wczytywanie i wyświetlanie formularza wiadomości dotyczącej prywatności

Po otrzymaniu najbardziej aktualnego stanu zgody wywołaj metodę loadAndShowConsentFormIfRequired(), aby wczytać formularze wymagane do uzyskania zgody użytkownika. Po wczytaniu formularze są natychmiast wyświetlane.

UserMessagingPlatform.loadAndShowConsentFormIfRequired(
    activity,
    formError -> {
      // Consent gathering process is complete.
    });
GoogleMobileAdsConsentManager.java

UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
  // Consent gathering process is complete.
}
GoogleMobileAdsConsentManager.kt

Opcje prywatności

Niektóre formularze wiadomości dotyczących prywatności są wyświetlane z punktu wejścia opcji prywatności renderowanego przez wydawcę, co umożliwia użytkownikom zarządzanie opcjami prywatności w dowolnym momencie. Aby dowiedzieć się więcej o tym, która wiadomość wyświetla się użytkownikom w punkcie wejścia do opcji związanych z prywatnością, przeczytaj artykuł Dostępne typy wiadomości dla użytkowników.

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

Po wywołaniu requestConsentInfoUpdate() sprawdź getPrivacyOptionsRequirementStatus(), aby określić, czy w aplikacji jest wymagany punkt wejścia opcji prywatności. Jeśli jest on wymagany, dodaj do aplikacji widoczny i interaktywny element interfejsu, który wyświetla formularz opcji prywatności. Jeśli punkt wejścia do ustawień prywatności nie jest wymagany, skonfiguruj element interfejsu tak, aby nie był widoczny i nie można było z nim wejść w interakcję.

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

Pełną listę stanów wymagań dotyczących opcji prywatności znajdziesz w artykule ConsentInformation.PrivacyOptionsRequirementStatus.

Wyświetlanie formularza opcji dotyczących prywatności

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

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

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

Wysyłanie żądań reklam po uzyskaniu zgody użytkownika

Zanim wyślesz żądanie reklamy, użyj canRequestAds(), aby sprawdzić, czy masz zgodę użytkownika:

consentInformation.canRequestAds();

consentInformation.canRequestAds()

Poniżej znajdziesz miejsca, w których możesz sprawdzić, czy możesz wysyłać żądania reklam podczas zbierania zgody:

• Po uzyskaniu zgody przez pakiet SDK UMP w bieżącej sesji.
• Natychmiast po wywołaniu metody requestConsentInfoUpdate(). Pakiet SDK UMP mógł uzyskać zgodę w poprzedniej sesji aplikacji.

Jeśli podczas procesu uzyskiwania zgody wystąpi błąd, sprawdź, czy możesz wysyłać żądania reklam. Pakiet SDK UMP używa stanu zgody z poprzedniej sesji aplikacji.

Zapobieganie zbędnym żądaniom reklam

Gdy sprawdzasz canRequestAds() po uzyskaniu zgody i wywołaniu requestConsentInfoUpdate(), upewnij się, że Twoja logika zapobiega zbędnym żądaniom reklamy, które mogą spowodować, że oba sprawdzenia zwrócą true. Na przykład za pomocą zmiennej logicznej.

Testowanie

Jeśli chcesz przetestować integrację w aplikacji podczas jej tworzenia, wykonaj te czynności, aby zarejestrować urządzenie testowe w kodzie. Przed opublikowaniem aplikacji usuń kod, który ustawia te identyfikatory urządzeń testowych.

1. Zadzwoń do firmy requestConsentInfoUpdate().

2. Sprawdź, czy w danych wyjściowych dziennika znajduje się komunikat podobny do tego w przykładzie poniżej, który zawiera identyfikator urządzenia i informacje o tym, jak dodać je jako urządzenie testowe:

   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ć metodę 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,
       // ...
   )
   

Wymuszanie 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 (EOG), Wielkiej Brytanii i Szwajcarii, za pomocą setDebugGeography(). 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 użytkownika

Podczas testowania aplikacji za pomocą pakietu SDK UMP warto zresetować stan pakietu SDK, aby zasymulować pierwszą instalację aplikacji przez użytkownika. Pakiet SDK udostępnia w tym celu metodę reset().

consentInformation.reset();

consentInformation.reset()

Przykłady na GitHubie

Pełny przykład integracji pakietu SDK UMP opisanej na tej stronie znajdziesz w projektach BannerExample w języku Java i BannerExample w języku Kotlin.