Ta strona została przetłumaczona przez Cloud Translation API.

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

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 i Activity udostępnione przez NDK. Wystarczy to zrobić tylko podczas pierwszego połączenia z GetInstance().
Jeśli używasz już w aplikacji pakietu SDK Firebase C++, możesz podać firebase::App przy pierwszym wywołaniu funkcji GetInstance().

#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

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::Futureumoż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 Futurestatus(). Gdy stan zmieni się z kFutureStatusPending na kFutureStatusCompleted, operacja zostanie ukończona.

Po zakończeniu operacji asynchronicznej sprawdź Futureerror(), 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ść Futurezwracaną 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 techniki, 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();