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
- Android API na poziomie 21 lub wyższym (w przypadku Androida)
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 ochrony prywatności i wyświetlania wiadomości.
Instalowanie pakietu SDK
Wykonaj czynności, aby zainstalować pakiet SDK do reklam mobilnych Google (GMA) w C++. Pakiet SDK UMP C++ jest zawarty w pakiecie GMA C++ SDK.
Zanim przejdziesz dalej, skonfiguruj identyfikator aplikacji AdMob w projekcie.
Zainicjuj pakiet UMP SDK w kodzie, wywołując funkcję
ConsentInfo::GetInstance()
.- W przypadku Androida musisz przekazać wartości
JNIEnv
iActivity
udostępnione przez NDK. Wystarczy to zrobić tylko podczas pierwszego połączenia zGetInstance()
. - Jeśli używasz już w aplikacji pakietu SDK Firebase C++, możesz podać
firebase::App
przy pierwszym wywołaniu funkcjiGetInstance()
.
#include "firebase/gma/ump.h" namespace ump = ::firebase::gma::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
- W przypadku Androida musisz przekazać wartości
Kolejne wywołania funkcji ConsentInfo::GetInstance()
zwracają ten sam element.
Gdy nie będziesz już używać pakietu UMP SDK, możesz go wyłączyć, usuwając instancję ConsentInfo
:
void ShutdownUserMessagingPlatform() {
ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
delete consent_info;
}
Korzystanie z Future
do monitorowania operacji asynchronicznych
firebase::Future
umożliwia określenie stanu wykonania wywołań asynchronicznych.
Wszystkie funkcje i wywołania metod UMP C++, które działają asynchronicznie, zwracają wartość Future
, a także udostępniają funkcję „last result” (ostatni wynik) do pobierania wartości Future
z ostatniej operacji.
Wynik funkcji Future
można uzyskać na 2 sposoby:
- Wywołaj funkcję
OnCompletion()
, podając własną funkcję wywołania zwrotnego, która zostanie wywołana po zakończeniu operacji. - Co jakiś czas sprawdzaj
Future
status()
. Gdy stan zmieni się zkFutureStatusPending
nakFutureStatusCompleted
, operacja zostanie zakończona.
Po zakończeniu operacji asynchronicznej sprawdź Future
error()
, aby uzyskać kod błędu operacji. Jeśli kod błędu to 0
(kConsentRequestSuccess
lub kConsentFormSuccess
), operacja została wykonana pomyślnie. W przeciwnym razie sprawdź kod błędu i error_message()
, aby określić, co poszło nie tak.
Zakończenie połączenia zwrotnego
Oto przykład użycia funkcji OnCompletion
do ustawienia funkcji wywołania zwrotnego po zakończeniu, która jest wywoływana 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.
}
});
}
Aktualizowanie sondowania pętli
W tym przykładzie po uruchomieniu aplikacji, gdy rozpocznie się operacja asynchroniczna, wyniki są sprawdzane w innym miejscu, w funkcji pętli aktualizacji gry (która działa raz na każdy kadr).
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 SDK Firebase C++ i dokumentacji pakietu SDK GMA C++.
Pobieranie informacji o zgodzie użytkownika
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:
- 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.
#include "firebase/gma/ump.h"
namespace ump = ::firebase::gma::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.
});
}
Wczytywanie i prezentowanie formularza wiadomości dotyczącej 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.
#include "firebase/gma/ump.h"
namespace ump = ::firebase::gma::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.
}
});
}
});
}
Przykład sprawdzania ukończenia za pomocą cyklu odpytywania (zamiast wywołania zwrotnego zakończenia) znajdziesz wyżej.
Jeśli po dokonaniu przez użytkownika wyboru lub zamknięciu formularza musisz wykonać jakieś czynności, umieść tę logikę w kodzie, który obsługuje wartość Future
zwracaną przez funkcję LoadAndShowConsentFormIfRequired()
.
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.
Prośba o reklamy z uwzględnieniem zgody użytkownika
Zanim wyślesz żądanie reklamy, użyj
ConsentInfo::GetInstance()‑>
CanRequestAds()
, aby sprawdzić, czy użytkownik wyraził zgodę:
W tych miejscach możesz sprawdzić, czy możesz wyświetlać reklamy podczas zbierania zgody:
- Gdy pakiet UMP SDK uzyska zgodę w bieżącej sesji.
- Natychmiast po zakończeniu rozmowy
RequestConsentInfoUpdate()
. Pakiet SDK UMP mógł uzyskać zgodę w poprzedniej sesji aplikacji.
Jeśli podczas zbierania zgody wystąpi błąd, sprawdź, czy możesz poprosić o reklamy. Pakiet SDK UMP korzysta ze stanu zgody z poprzedniej sesji aplikacji.
Ten pełny przykład wykorzystuje sprawdzanie w pętli aktualizacji, ale do monitorowania operacji asynchronicznych możesz również używać wywołań zwrotnychOnCompletion
. Użyj tej metody, która lepiej pasuje do struktury Twojego kodu.
#include "firebase/future.h"
#include "firebase/gma/gma.h"
#include "firebase/gma/ump.h"
namespace gma = ::firebase::gma;
namespace ump = ::firebase::gma::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 za pomocą kodu. Zanim opublikujesz aplikację, usuń kod, który ustawia te identyfikatory testowych urządzeń.
- Zadzwoń do firmy
RequestConsentInfoUpdate()
. 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:
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]
Skopiuj identyfikator testowego urządzenia do schowka.
Zmodyfikuj kod, aby ustawić parametr
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); }
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.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
Podczas testowania aplikacji za pomocą pakietu UMP SDK warto zresetować jego stan, aby móc symulować pierwsze uruchomienie aplikacji przez użytkownika.
Pakiet SDK udostępnia do tego celu metodę Reset()
.
ConsentInfo::GetInstance()->Reset();