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 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 UMP C++ SDK jest zawarty w pakiecie SDK GMA C++.
Zanim przejdziesz dalej, skonfiguruj identyfikator aplikacji AdMob w projekcie.

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

W przypadku Androida musisz przekazać wartości JNIEnv i Activity udostępnione przez NDK. Wykonując tę czynność tylko przy pierwszym połączeniu z GetInstance().
Jeśli używasz już w aplikacji pakietu SDK Firebase C++, możesz podać wartość 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ą tę samą instancję.

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 OnCompletion(), przekazując własną funkcję wywołania zwrotnego, która jest wywoływana po zakończeniu operacji.
Co jakiś czas sprawdzaj Futurestatus(). Gdy stan zmieni się z kFutureStatusPending na kFutureStatusCompleted, operacja została 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 ukończona. W przeciwnym razie sprawdź kod błędu i error_message(), aby ustalić, co poszło nie tak.

Zakończenie oddzwaniania

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

Zbieranie zgody

Aby uzyskać zgodę użytkowników, wykonaj te czynności:

Prośba o aktualne informacje o zgodzie użytkownika.
W razie potrzeby wyświetl formularz zgody.

Za każdym razem, gdy uruchamiasz aplikację, powinnaś poprosić o zaktualizowanie informacji o zgodzie użytkownika, używając do tego tagu RequestConsentInfoUpdate(). To żądanie sprawdza, czy:

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.

W razie potrzeby wczytaj i pokaż formularz wiadomości o ochronie prywatności

Po uzyskaniu najbardziej aktualnego stanu zgody wywołaj LoadAndShowConsentFormIfRequired(), aby wczytać wszelkie formularze wymagane do uzyskiwania zgody użytkowników. Po wczytaniu formularze pojawią się od razu.

Poniższy kod pokazuje, jak poprosić o najnowsze informacje o zgodzie użytkownika. W razie potrzeby kod wczyta i wyświetli formularz z wiadomością dotyczącą prywatności:

#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ące prywatności są wyświetlane w punktach wejścia opcji prywatności przygotowanych przez wydawcę, co pozwala użytkownikom w dowolnym momencie zarządzać opcjami prywatności. Aby dowiedzieć się, którą wiadomość widzą użytkownicy w punkcie wprowadzania opcji prywatności, przeczytaj artykuł Dostępne typy wiadomości dla użytkowników.

Wyślij żądanie

Zanim wyślesz prośbę o reklamy w aplikacji, sprawdź, czy masz zgodę użytkownika za pomocą ConsentInfo::GetInstance()‑> CanRequestAds(). Podczas zbierania zgody należy sprawdzić 2 miejsca:

Po wyrażeniu zgody w bieżącej sesji.
Natychmiast po zakończeniu rozmowy RequestConsentInfoUpdate(). Możliwe, że zgoda została uzyskana w poprzedniej sesji. W ramach najlepszej praktyki dotyczącej opóźnień zalecamy, aby nie czekać na zakończenie wywołania zwrotnego, aby można było jak najszybciej rozpocząć wczytywanie reklam po uruchomieniu aplikacji.

Jeśli podczas uzyskiwania zgody użytkowników wystąpi błąd, musisz sprawdzić, czy możesz wysyłać żądania reklam. Pakiet UMP SDK używa stanu zgody z poprzedniej sesji.

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 informacje o dodaniu 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 urządzenia testowego 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ć stan pakietu SDK, aby można było symulować pierwsze uruchomienie aplikacji przez użytkownika. W tym celu pakiet SDK udostępnia metodę Reset().

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