Diese Seite wurde von der Cloud Translation API übersetzt.

Los gehts

Das Google User Messaging Platform (UMP) SDK ist ein Datenschutz- und Mitteilungstool, mit dem Sie Datenschutzeinstellungen verwalten können. Weitere Informationen finden Sie hier.

Vorbereitung

Android-API-Level 21 oder höher (für Android)

Nachrichtentyp erstellen

Erstellen Sie Nutzermitteilungen mit einem der verfügbaren Nutzermitteilungstypen auf dem Tab Datenschutz und Mitteilungen Ihres AdMob-Kontos. Das UMP SDK versucht, eine Datenschutzmitteilung anzuzeigen, die anhand der in Ihrem Projekt festgelegten AdMob-App-ID erstellt wurde.

Weitere Informationen finden Sie unter Datenschutz und Mitteilungen.

SDK Installieren

Folgen Sie der Anleitung, um das Firebase C++ SDK zu installieren. Das UMP C++ SDK ist im Firebase C++ SDK enthalten.
Konfigurieren Sie die AdMob-App-ID Ihrer App im Projekt, bevor Sie fortfahren.

Initialisieren Sie das UMP SDK in Ihrem Code, indem Sie ConsentInfo::GetInstance() aufrufen.

Unter Android müssen Sie die vom NDK bereitgestellten JNIEnv und Activity übergeben. Das ist nur beim ersten Aufruf von GetInstance() erforderlich.
Wenn Sie das Firebase C++ SDK bereits in Ihrer App verwenden, können Sie beim ersten Aufruf von GetInstance() auch ein firebase::App übergeben.

#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

Bei nachfolgenden Aufrufen von ConsentInfo::GetInstance() wird immer dieselbe Instanz zurückgegeben.

Wenn Sie das UMP SDK nicht mehr verwenden, können Sie es beenden, indem Sie die ConsentInfo-Instanz löschen:

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

`Future` verwenden, um asynchrone Vorgänge zu überwachen

Mit firebase::Future können Sie den Abschlussstatus asynchroner Methodenaufrufe ermitteln.

Alle UMP C++-Funktionen und Methodenaufrufe, die asynchron ausgeführt werden, geben ein Future zurück. Außerdem gibt es eine Funktion für das „letzte Ergebnis“, mit der das Future des letzten Vorgangs abgerufen werden kann.

Es gibt zwei Möglichkeiten, ein Ergebnis von einer Future abzurufen:

Rufen Sie OnCompletion() auf und übergeben Sie Ihre eigene Callback-Funktion, die aufgerufen wird, wenn der Vorgang abgeschlossen ist.
Prüfen Sie regelmäßig die Future der status(). Wenn sich der Status von kFutureStatusPending in kFutureStatusCompleted ändert, ist der Vorgang abgeschlossen.

Nach Abschluss des asynchronen Vorgangs sollten Sie den Fehlercode des Vorgangs aus error() von Future abrufen. Wenn der Fehlercode 0 (kConsentRequestSuccess oder kConsentFormSuccess) ist, wurde der Vorgang erfolgreich abgeschlossen. Andernfalls prüfen Sie den Fehlercode und error_message(), um herauszufinden, was schiefgelaufen ist.

Callback für Abschluss

Hier sehen Sie ein Beispiel für die Verwendung von OnCompletion zum Festlegen eines Completion-Callbacks, der aufgerufen wird, wenn der asynchrone Vorgang abgeschlossen ist.

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.
    }
  });
}

Aktualisierung von Schleifen-Polling

In diesem Beispiel werden die Ergebnisse nach dem Start eines asynchronen Vorgangs beim Start der App an anderer Stelle geprüft, nämlich in der Update-Schleifenfunktion des Spiels (die einmal pro Frame ausgeführt wird).

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

Weitere Informationen zu firebase::Future finden Sie in der Firebase C++ SDK-Dokumentation und in der GMA C++ SDK-Dokumentation.

Einwilligungsinformationen des Nutzers abrufen

Sie sollten bei jedem Start der App mit RequestConsentInfoUpdate() eine Aktualisierung der Einwilligungsinformationen des Nutzers anfordern. Bei dieser Anfrage wird Folgendes geprüft:

Ob eine Einwilligung erforderlich ist Das ist beispielsweise der Fall, wenn die Einwilligung zum ersten Mal erforderlich ist oder die vorherige Einwilligungserklärung abgelaufen ist.
Ob ein Einstiegspunkt für Datenschutzoptionen erforderlich ist Bei einigen Datenschutzmitteilungen müssen Apps Nutzern die Möglichkeit geben, ihre Datenschutzeinstellungen jederzeit zu ändern.

#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.
    });
}

Datenschutzmitteilungsformular laden und präsentieren

Nachdem Sie den aktuellen Einwilligungsstatus erhalten haben, rufen Sie LoadAndShowConsentFormIfRequired() auf, um alle Formulare zu laden, die zum Einholen der Nutzereinwilligung erforderlich sind. Nach dem Laden werden die Formulare sofort angezeigt.

#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.
          }
        });
      }
    });
}

Oben finden Sie ein Beispiel dafür, wie Sie den Abschluss mithilfe von Update-Loop-Polling anstelle eines Completion-Callbacks prüfen.

Wenn Sie Aktionen ausführen müssen, nachdem der Nutzer eine Auswahl getroffen oder das Formular geschlossen hat, platzieren Sie diese Logik im Code, der die von LoadAndShowConsentFormIfRequired() zurückgegebene Future verarbeitet.

Datenschutzoptionen

Einige Formulare für Datenschutzmitteilungen werden über einen vom Publisher gerenderten Einstiegspunkt für Datenschutzoptionen präsentiert. So können Nutzer ihre Datenschutzoptionen jederzeit verwalten. Weitere Informationen dazu, welche Mitteilung Ihre Nutzer am Einstiegspunkt für Datenschutzoptionen sehen, finden Sie unter Verfügbare Arten von Nutzermitteilungen.

Anzeigen mit Nutzereinwilligung anfordern

Bevor Sie Anzeigen anfordern, prüfen Sie mit ConsentInfo::GetInstance()‑> CanRequestAds(), ob Sie die Einwilligung des Nutzers eingeholt haben:

Hier finden Sie eine Liste der Stellen, an denen Sie Anzeigen anfordern können, während Sie die Einwilligung einholen:

Nachdem das UMP SDK die Einwilligung in der aktuellen Sitzung eingeholt hat.
Unmittelbar nach dem Aufrufen von RequestConsentInfoUpdate(). Das UMP SDK hat möglicherweise in der vorherigen App-Sitzung die Einwilligung eingeholt.

Wenn während des Prozesses zum Einholen der Einwilligung ein Fehler auftritt, prüfen Sie, ob Sie Anzeigen anfordern können. Das UMP SDK verwendet den Einwilligungsstatus aus der vorherigen App-Sitzung.

Im folgenden vollständigen Beispiel wird das Polling im Aktualisierungszyklus verwendet. Sie können aber auch OnCompletion-Callbacks verwenden, um asynchrone Vorgänge zu überwachen. Verwenden Sie die Technik, die besser zu Ihrer Codestruktur passt.

#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;
      }
    }
  }
}

Test

Wenn Sie die Integration während der Entwicklung in Ihrer App testen möchten, folgen Sie dieser Anleitung, um Ihr Testgerät programmatisch zu registrieren. Entfernen Sie den Code, mit dem diese Testgeräte-IDs festgelegt werden, bevor Sie Ihre App veröffentlichen.

Rufen Sie einfach RequestConsentInfoUpdate() an.

Suchen Sie in der Log-Ausgabe nach einer Meldung, die dem folgenden Beispiel ähnelt. Dort finden Sie Ihre Geräte-ID und eine Anleitung dazu, wie Sie sie als Testgerät hinzufügen:

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]

Kopieren Sie die ID Ihres Testgeräts in die Zwischenablage.

Ändern Sie Ihren Code so, dass ConsentRequestParameters.debug_settings.debug_device_ids auf eine Liste Ihrer Testgeräte-IDs festgelegt wird.

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);
}

Geografie erzwingen

Mit dem UMP SDK können Sie das Verhalten Ihrer App so testen, als ob sich das Gerät in verschiedenen Regionen wie dem EWR oder dem Vereinigten Königreich befände. Dazu verwenden Sie debug_settings.debug_geography. Die Debugging-Einstellungen funktionieren nur auf Testgeräten.

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);
}

Einwilligungsstatus zurücksetzen

Beim Testen Ihrer App mit dem UMP SDK kann es hilfreich sein, den Status des SDK zurückzusetzen, um die erste Installation durch einen Nutzer zu simulieren. Das SDK bietet die Methode Reset(), um dies zu tun.

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