Rozpocznij

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

Wymagania wstępne

• Android API na poziomie 21 lub wyższym (w przypadku Androida),

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.

Więcej informacji znajdziesz w artykule Prywatność i wyświetlanie wiadomości.

Instalowanie pakietu SDK

1. Wykonaj czynności opisane w sekcji Instalowanie pakietu Firebase C++ SDK. Pakiet UMP C++ SDK jest dołączony do pakietu Firebase C++ SDK.

2. Zanim przejdziesz dalej, upewnij się, że w projekcie skonfigurowano identyfikator aplikacji w AdMob.

3. W kodzie zainicjuj pakiet SDK UMP, wywołując funkcję ConsentInfo::GetInstance().

   • Na Androidzie musisz przekazać JNIEnv i Activity dostarczone przez NDK. Wystarczy to zrobić tylko przy pierwszym połączeniu z numerem GetInstance().
   • Jeśli używasz już w aplikacji pakietu Firebase C++ SDK, możesz przekazać firebase::App przy pierwszym wywołaniu GetInstance().

   #include "firebase/ump/ump.h"
   
   namespace ump = ::firebase::ump;
   
   // Initialize using a firebase::App
   void InitializeUserMessagingPlatform(const firebase::App& app) {
     ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(app);
   }
   
   // Initialize without a firebase::App
   #ifdef ANDROID
   void InitializeUserMessagingPlatform(JNIEnv* jni_env, jobject activity) {
     ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(jni_env, activity);
   }
   #else  // non-Android
   void InitializeUserMessagingPlatform() {
     ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
   }
   #endif
   

Kolejne wywołania metody ConsentInfo::GetInstance() zwracają tę samą instancję.

Uwaga: metody GetInstance() mają opcjonalny parametr wyjściowy firebase::InitResult, który zwraca wartość firebase::kInitResultSuccess, jeśli pakiet SDK został pomyślnie zainicjowany, lub firebase::kInitResultFailedMissingDependency, jeśli w aplikacji brakuje wymaganych zależności. Jeśli wystąpi ten błąd, upewnij się, że zostały wykonane wszystkie kroki instalacji dla Twojej platformy.

Jeśli nie chcesz już używać pakietu SDK UMP, możesz go wyłączyć, usuwając instancję ConsentInfo:

void ShutdownUserMessagingPlatform() {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
  delete consent_info;
}

Uwaga: nie musisz inicjować pakietu Firebase C++ SDK przed zainicjowaniem pakietu SDK platformy do personalizowania wiadomości wyświetlanych użytkownikom.

Używanie Future do monitorowania operacji asynchronicznych

firebase::Future umożliwia określenie stanu ukończenia wywołań metod asynchronicznych.

Wszystkie wywołania funkcji i wywołania metod UMP w C++, które działają asynchronicznie, zwracają obiekt Future, a także udostępniają funkcję „ostatni wynik”, która umożliwia pobranie obiektu Future z ostatniej operacji.

Wynik z Future możesz uzyskać na 2 sposoby:

1. Wywołaj funkcję OnCompletion(), przekazując własną funkcję wywołania zwrotnego, która jest wywoływana po zakończeniu operacji.
2. Okresowo sprawdzaj status() w Future. Gdy stan zmieni się z kFutureStatusPending na kFutureStatusCompleted, operacja została zakończona.

Po zakończeniu operacji asynchronicznej sprawdź error() obiektu Future, aby uzyskać kod błędu operacji. Jeśli kod błędu to 0 (kConsentRequestSuccess lub kConsentFormSuccess), operacja zakończyła się powodzeniem. W przeciwnym razie sprawdź kod błędu i error_message(), aby dowiedzieć się, co poszło nie tak.

Uwaga: kod błędu zwracany przez RequestConsentInfoUpdate() używa typu wyliczeniowego ConsentRequestError, a wszystkie inne operacje używają typu wyliczeniowego ConsentFormError.

Wywołanie zwrotne po zakończeniu

Oto przykład użycia metody OnCompletion do ustawienia wywołania zwrotnego, które jest wywoływane po zakończeniu operacji asynchronicznej.

void MyApplicationStart() {
  // [... other app initialization code ...]

  ump::ConsentInfo *consent_info = ump::ConsentInfo::GetInstance();

  // See the section below for more information about RequestConsentInfoUpdate.
  firebase::Future<void> result = consent_info->RequestConsentInfoUpdate(...);

  result.OnCompletion([](const firebase::Future<void>& req_result) {
    if (req_result.error() == ump::kConsentRequestSuccess) {
      // Operation succeeded. You can now call LoadAndShowConsentFormIfRequired().
    } else {
      // Operation failed. Check req_result.error_message() for more information.
    }
  });
}

Odpytywanie pętli aktualizacji

W tym przykładzie po rozpoczęciu operacji asynchronicznej podczas uruchamiania aplikacji wyniki są sprawdzane w innym miejscu, w funkcji pętli aktualizacji gry (która jest uruchamiana raz na klatkę).

ump::ConsentInfo *g_consent_info = nullptr;
bool g_waiting_for_request = false;

void MyApplicationStart() {
  // [... other app initialization code ...]

  g_consent_info = ump::ConsentInfo::GetInstance();
  // See the section below for more information about RequestConsentInfoUpdate.
  g_consent_info->RequestConsentInfoUpdate(...);
  g_waiting_for_request = true;
}

// Elsewhere, in the game's update loop, which runs once per frame:
void MyGameUpdateLoop() {
  // [... other game logic here ...]

  if (g_waiting_for_request) {
    // Check whether RequestConsentInfoUpdate() has finished.
    // Calling "LastResult" returns the Future for the most recent operation.
    firebase::Future<void> result =
      g_consent_info->RequestConsentInfoUpdateLastResult();

    if (result.status() == firebase::kFutureStatusComplete) {
      g_waiting_for_request = false;
      if (result.error() == ump::kConsentRequestSuccess) {
        // Operation succeeded. You can call LoadAndShowConsentFormIfRequired().
      } else {
        // Operation failed. Check result.error_message() for more information.
      }
    }
  }
}

Więcej informacji o firebase::Future znajdziesz w dokumentacji pakietu Firebase C++ SDK i dokumentacji pakietu GMA C++ SDK.

Uwaga: w pakiecie SDK UMP w języku C++ wszystkie operacje asynchroniczne zwracają firebase::Future<void>.

Uzyskiwanie informacji o zgodzie użytkownika

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.

#include "firebase/ump/ump.h"

namespace ump = ::firebase::ump;

void MyApplicationStart(ump::FormParent parent) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  consent_info->RequestConsentInfoUpdate(params).OnCompletion(
    [*](const Future<void>& req_result) {
      if (req_result.error() != ump::kConsentRequestSuccess) {
        // req_result.error() is a kConsentRequestError enum.
        LogMessage("Error requesting consent update: %s", req_result.error_message());
      }
      // Consent information is successfully updated.
    });
}

Ostrzeżenie: nie zalecamy sprawdzania stanu zgody w inny sposób, np. w pamięci podręcznej aplikacji lub w zapisanych wcześniej ciągach tekstowych dotyczących zgody. Te metody mogą zwracać nieaktualne dane dotyczące zgody użytkownika.

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.

Ważne: jeśli żadne formularze wiadomości dotyczących prywatności nie wymagają uzyskania zgody użytkownika przed wysłaniem żądania reklamy, wywołanie zwrotne jest wywoływane natychmiast.

#include "firebase/ump/ump.h"

namespace ump = ::firebase::ump;

void MyApplicationStart(ump::FormParent parent) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  consent_info->RequestConsentInfoUpdate(params).OnCompletion(
    [*](const Future<void>& req_result) {
      if (req_result.error() != ump::kConsentRequestSuccess) {
        // req_result.error() is a kConsentRequestError enum.
        LogMessage("Error requesting consent update: %s", req_result.error_message());
      } else {
        consent_info->LoadAndShowConsentFormIfRequired(parent).OnCompletion(
        [*](const Future<void>& form_result) {
          if (form_result.error() != ump::kConsentFormSuccess) {
            // form_result.error() is a kConsentFormError enum.
            LogMessage("Error showing privacy message form: %s", form_result.error_message());
          } else {
            // Either the form was shown and completed by the user, or consent was not required.
          }
        });
      }
    });
}

Powyżej znajdziesz przykład sprawdzania ukończenia za pomocą pętli aktualizacji, a nie wywołania zwrotnego.

Uwaga: w zależności od platformy FormParent jest odwołaniem JNI jobject do obiektu Activity na Androidzie lub wskaźnikiem do obiektu UIViewController na iOS, rzutowanym na typ FormParent.

Jeśli chcesz wykonać jakieś działania po tym, jak użytkownik dokona wyboru lub zamknie formularz, umieść tę logikę w kodzie, który obsługuje obiekt Future zwracany przez LoadAndShowConsentFormIfRequired().

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 dotyczących prywatności, przeczytaj artykuł Dostępne typy wiadomości dla użytkowników.

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

Zanim wyślesz żądanie reklamy, użyj metody ConsentInfo::GetInstance()‑> CanRequestAds(), aby sprawdzić, czy użytkownik wyraził zgodę:

Oto 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 funkcji RequestConsentInfoUpdate(). Pakiet SDK UMP mógł uzyskać zgodę w poprzedniej sesji aplikacji.

Ważne: ConsentInfo::GetInstance()‑> CanRequestAds() zawsze zwraca false, dopóki nie wywołasz RequestConsentInfoUpdate()

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 ConsentInfo::GetInstance()‑> 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.

Poniższy kompletny przykład wykorzystuje odpytywanie w pętli aktualizacji, ale do monitorowania operacji asynchronicznych możesz też użyć wywołań zwrotnych OnCompletion. Użyj techniki, która lepiej pasuje do struktury kodu.

#include "firebase/future.h"
#include "firebase/gma/gma.h"
#include "firebase/ump/ump.h"

namespace gma = ::firebase::gma;
namespace ump = ::firebase::ump;
using firebase::Future;

ump::ConsentInfo* g_consent_info = nullptr;
// State variable for tracking the UMP consent flow.
enum { kStart, kRequest, kLoadAndShow, kInitGma, kFinished, kErrorState } g_state = kStart;
bool g_ads_allowed = false;

void MyApplicationStart() {
  g_consent_info = ump::ConsentInfo::GetInstance(...);

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  g_consent_info->RequestConsentInfoUpdate(params);
  // CanRequestAds() can return a cached value from a previous run immediately.
  g_ads_allowed = g_consent_info->CanRequestAds();
  g_state = kRequest;
}

// This function runs once per frame.
void MyGameUpdateLoop() {
  // [... other game logic here ...]

  if (g_state == kRequest) {
    Future<void> req_result = g_consent_info->RequestConsentInfoUpdateLastResult();

    if (req_result.status() == firebase::kFutureStatusComplete) {
      g_ads_allowed = g_consent_info->CanRequestAds();
      if (req_result.error() == ump::kConsentRequestSuccess) {
        // You must provide the FormParent (Android Activity or iOS UIViewController).
        ump::FormParent parent = GetMyFormParent();
        g_consent_info->LoadAndShowConsentFormIfRequired(parent);
        g_state = kLoadAndShow;
      } else {
        LogMessage("Error requesting consent status: %s", req_result.error_message());
        g_state = kErrorState;
      }
    }
  }
  if (g_state == kLoadAndShow) {
    Future<void> form_result = g_consent_info->LoadAndShowConsentFormIfRequiredLastResult();

    if (form_result.status() == firebase::kFutureStatusComplete) {
      g_ads_allowed = g_consent_info->CanRequestAds();
      if (form_result.error() == ump::kConsentRequestSuccess) {
        if (g_ads_allowed) {
          // Initialize GMA. This is another asynchronous operation.
          firebase::gma::Initialize();
          g_state = kInitGma;
        } else {
          g_state = kFinished;
        }
        // Optional: shut down the UMP SDK to save memory.
        delete g_consent_info;
        g_consent_info = nullptr;
      } else {
        LogMessage("Error displaying privacy message form: %s", form_result.error_message());
        g_state = kErrorState;
      }
    }
  }
  if (g_state == kInitGma && g_ads_allowed) {
    Future<gma::AdapterInitializationStatus> gma_future = gma::InitializeLastResult();

    if (gma_future.status() == firebase::kFutureStatusComplete) {
      if (gma_future.error() == gma::kAdErrorCodeNone) {
        g_state = kFinished;
        // TODO: Request an ad.
      } else {
        LogMessage("Error initializing GMA: %s", gma_future.error_message());
        g_state = kErrorState;
      }
    }
  }
}

Testowanie

Jeśli chcesz przetestować integrację w aplikacji podczas jej tworzenia, wykonaj te czynności, aby zarejestrować urządzenie testowe w sposób zautomatyzowany. 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, który zawiera identyfikator urządzenia i informacje o tym, jak dodać je jako urządzenie testowe:

   Android

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

   iOS

   <UMP SDK>To enable debug mode for this device,
   set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]
   

3. Skopiuj identyfikator urządzenia testowego do schowka.

4. Zmodyfikuj kod, aby ustawić ConsentRequestParameters.debug_settings.debug_device_ids na listę identyfikatorów urządzeń testowych.

   void MyApplicationStart() {
     ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...);
   
     ump::ConsentRequestParameters params;
     params.tag_for_under_age_of_consent = false;
     params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"};
   
     consent_info->RequestConsentInfoUpdate(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ą debug_settings.debug_geography. Pamiętaj, że ustawienia debugowania działają tylko na urządzeniach testowych.

void MyApplicationStart() {
  ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...);

  ump::ConsentRequestParameters params;
  params.tag_for_under_age_of_consent = false;
  params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"};
  // Geography appears as EEA for debug devices.
  params.debug_settings.debug_geography = ump::kConsentDebugGeographyEEA

  consent_info->RequestConsentInfoUpdate(params);
}

Resetowanie stanu zgody użytkownika

Podczas testowania aplikacji za pomocą pakietu SDK UMP warto zresetować stan pakietu SDK, aby zasymulować pierwsze uruchomienie aplikacji przez użytkownika. Pakiet SDK udostępnia metodę Reset(), która umożliwia wykonanie tej czynności.

  ConsentInfo::GetInstance()->Reset();

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