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

Wiadomości dla użytkowników możesz tworzyć w jednym 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, aby zainstalować pakiet SDK do reklam mobilnych Google (GMA) w C++. Pakiet SDK UMP C++ jest zawarty w pakiecie GMA C++ SDK.

  2. Zanim przejdziesz dalej, skonfiguruj identyfikator aplikacji AdMob w projekcie.

  3. W kodzie zainicjuj pakiet UMP SDK, 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ć 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ą 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 zakończenia wywołań metod 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:

  1. Wywołaj funkcję OnCompletion(), podając własną funkcję wywołania zwrotnego, która zostanie wywołana po zakończeniu operacji.
  2. 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 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++.

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

  1. Prośba o najnowsze informacje o zgodzie użytkownika.
  2. 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 wyświetl formularz wiadomości dotyczącej ochrony prywatności

Po otrzymaniu najnowszego stanu zgody wywołaj funkcję LoadAndShowConsentFormIfRequired(), aby załadować formularze wymagane do uzyskania zgody użytkownika. 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 musisz wykonać jakieś działania po dokonaniu wyboru lub zamknięciu formularza przez użytkownika, umieść tę logikę w kodzie, który obsługuje polecenie Future zwrócone przez 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ę 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.

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 procesu zbierania zgód wystąpi błąd, sprawdź, czy możesz nadal wysyłać żądania reklam. Pakiet UMP SDK używa stanu zgody z poprzedniej sesji.

Pełny przykład poniżej korzysta z odpytywania w pętlę aktualizacji, ale do monitorowania operacji asynchronicznych możesz też używać wywołań zwrotnych OnCompletion. 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ń.

  1. Zadzwoń do firmy RequestConsentInfoUpdate().

  2. 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]

  3. Skopiuj identyfikator testowego urządzenia do schowka.

  4. Zmodyfikuj kod, aby umieścić ConsentRequestParameters.debug_settings.debug_device_ids na liście 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);
}

Podczas testowania aplikacji za pomocą pakietu SDK UMP warto zresetować stan pakietu SDK, aby przeprowadzić symulację pierwszej instalacji aplikacji u użytkownika. Pakiet SDK udostępnia do tego metodę Reset().

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