Rozpocznij

Wybierz platformę: Android iOS Unity Flutter

Pakiet SDK platformy do personalizowania wiadomości wyświetlanych użytkownikom od Google to narzędzie do ochrony prywatności i wyświetlania wiadomości, które pomaga zarządzać ustawieniami prywatności. Więcej informacji znajdziesz w artykule Prywatność i wyświetlanie wiadomości.

Wymagania wstępne

• Android w wersji API 21 lub nowszej.

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 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 Prywatność i wyświetlanie wiadomości.

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

Uzyskiwanie informacji o zgodzie użytkownika

Aby uzyskać informacje o stanie zgody użytkownika:

Zadeklaruj instancję ConsentInformation:

Java

private final ConsentInformation consentInformation;

Kotlin

private lateinit val consentInformation: ConsentInformation

Zainicjuj instancję ConsentInformation:

Java

consentInformation = UserMessagingPlatform.getConsentInformation(context);

Kotlin

consentInformation = UserMessagingPlatform.getConsentInformation(context)

Przy każdym uruchomieniu aplikacji należy prosić o aktualizację informacji o stanie zgody użytkownika za pomocą funkcji requestConsentInfoUpdate(). To żądanie sprawdza te kwestie:

• Czy wymagana jest zgoda. 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.

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.java

Kotlin

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

Ostrzeżenie: korzystanie z innych sposobów sprawdzania stanu zgody, np. z pamięci podręcznej w aplikacji lub wcześniej zapisanych ciągów znaków dotyczących zgody, może prowadzić do błędu TCF 3.3, jeśli zgoda wygasła.

Wczytywanie i wyświetlanie formularza komunikatu dotyczącego prywatności

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

Ważne: jeśli żadne formularze wiadomości o prywatności nie wymagają uzyskania zgody użytkownika przed wysłaniem prośby o wyświetlenie reklam, wywołanie zwrotne następuje natychmiast.

Java

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

Kotlin

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 w punkcie wejścia opcji prywatności renderowanym przez wydawcę, co umożliwia użytkownikom zarządzanie opcjami prywatności w dowolnym momencie. Więcej informacji o tym, która wiadomość wyświetla się użytkownikom w punkcie wejścia do opcji prywatności, znajdziesz w sekcji 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ź getPrivacyOptionsRequirementStatus(), aby określić, czy w Twojej aplikacji wymagany jest 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 był niewidoczny i nie można było z nim wchodzić w interakcję.

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

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

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

Wysyłanie próśb o reklamy po uzyskaniu zgody użytkownika

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

Java

consentInformation.canRequestAds();

Kotlin

consentInformation.canRequestAds()

Oto miejsca, w których możesz sprawdzić, czy możesz wysyłać prośby o reklamy podczas uzyskiwania zgody użytkowników:

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

Ważne: funkcja canRequestAds() zawsze zwraca wartość false, dopóki nie wywołasz funkcji requestConsentInfoUpdate()

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

Zapobieganie zbędnym żądaniom reklam

Podczas sprawdzania canRequestAds() po uzyskaniu zgody i po wywołaniu requestConsentInfoUpdate() upewnij się, że logika zapobiega zbędnym żądaniom reklam, które mogą spowodować, że oba sprawdzenia zwrócą wartość true. Na przykład w przypadku zmiennej logicznej.

Testowanie

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

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

1. Zadzwoń do firmy requestConsentInfoUpdate().

2. Sprawdź w danych wyjściowych dziennika komunikat podobny do tego 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ływać funkcję ConsentDebugSettings.Builder().TestDeviceHashedIds i przekazywać do niej 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 lub Wielkiej Brytanii, za pomocą DebugGeography. 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,
    ...
)

Resetowanie stanu zgody

Podczas testowania aplikacji z pakietem SDK UMP możesz zresetować stan pakietu SDK, aby symulować pierwsze wrażenia użytkownika po zainstalowaniu aplikacji. Pakiet SDK udostępnia do tego celu metodę reset().

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

Uwaga: ta metoda jest przeznaczona wyłącznie do celów testowych. Nie należy wywoływać funkcji reset() w kodzie produkcyjnym.

Przykłady w GitHubie

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