Diese Seite wurde von der Cloud Translation API übersetzt.

Jetzt starten

Das UMP SDK (User Messaging Platform) von Google ist ein Tool für Datenschutz und Mitteilungen, mit dem Sie Ihre Datenschutzeinstellungen verwalten können. Weitere Informationen finden Sie unter Datenschutz und Mitteilungen.

Vorbereitung

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

Mitteilungstyp erstellen

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

Weitere Informationen finden Sie unter Informationen zu Datenschutz und Mitteilungen.

SDK Installieren

Folgen Sie der Anleitung zum Installieren des Google Mobile Ads (GMA) C++ SDKs. Das UMP C++ SDK ist im GMA C++ SDK enthalten.
Bevor du fortfährst, musst du die AdMob-App-ID deiner App im Projekt konfigurieren.

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

Unter Android müssen Sie das vom NDK bereitgestellte JNIEnv und Activity übergeben. Sie müssen dies nur beim ersten Aufruf von GetInstance() tun.
Wenn Sie bereits das Firebase C++ SDK in Ihrer App verwenden, können Sie beim ersten Aufruf von GetInstance() eine firebase::App übergeben.

#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

Alle nachfolgenden Aufrufe von ConsentInfo::GetInstance() geben dieselbe Instanz zurück.

Wenn Sie das UMP SDK nicht mehr benötigen, können Sie es herunterfahren, indem Sie die Instanz ConsentInfo löschen:

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

`Future` zum Überwachen asynchroner Vorgänge verwenden

Mit einem firebase::Future können Sie den Abschlussstatus von asynchronen Methodenaufrufen ermitteln.

Alle UMP-C++-Funktionen und ‑Methodenaufrufe, die asynchron ausgeführt werden, geben eine Future zurück und bieten auch eine Funktion „Letztes Ergebnis“, mit der die Future aus dem letzten Vorgang abgerufen werden kann.

Es gibt zwei Möglichkeiten, ein Ergebnis aus einer Future zu erhalten:

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

Nach Abschluss des asynchronen Vorgangs sollten Sie den error() der Future prüfen, um den Fehlercode des Vorgangs zu erhalten. 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.

Rückruf nach Abschluss

Hier ist ein Beispiel dafür, wie Sie mit OnCompletion einen Abschluss-Callback festlegen, 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.
    }
  });
}

Update-Loop-Polling

In diesem Beispiel werden die Ergebnisse nach dem Start eines asynchronen Vorgangs beim Starten der App an anderer Stelle geprüft, 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 Dokumentation zum Firebase C++ SDK und in der Dokumentation zum GMA C++ SDK.

Einwilligung einholen

So holen Sie die Einwilligung ein:

Informationen zur aktuellen Nutzereinwilligung anfordern
Laden Sie bei Bedarf ein Einwilligungsformular hoch und legen Sie es vor.

Sie sollten bei jedem Start der App mithilfe von RequestConsentInfoUpdate() ein Update der Einwilligungsinformationen des Nutzers anfordern. Bei dieser Anfrage wird Folgendes geprüft:

Ob eine Einwilligung erforderlich ist Beispielsweise ist die Einwilligung zum ersten Mal erforderlich oder die vorherige Einwilligungsentscheidung ist abgelaufen.
Ob ein Einstiegspunkt für Datenschutzoptionen erforderlich ist Einige Datenschutzmitteilungen erfordern, dass Nutzer ihre Datenschutzoptionen jederzeit ändern können.

Formular für Datenschutzmitteilungen laden und präsentieren (falls erforderlich)

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.

Der folgende Code zeigt, wie Sie die neuesten Einwilligungsinformationen des Nutzers anfordern. Falls erforderlich, wird der Code geladen und ein Formular mit einer Datenschutzmitteilung angezeigt:

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

Oben findest du ein Beispiel für die Prüfung auf Abschluss mithilfe einer Update-Schleife statt eines Abschluss-Callbacks.

Wenn du Aktionen ausführen musst, nachdem der Nutzer eine Auswahl getroffen oder das Formular geschlossen hat, platziere diese Logik in den Code, der das von LoadAndShowConsentFormIfRequired() zurückgegebene Future verarbeitet.

Datenschutzoptionen

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

Anzeigenanfrage senden

Bevor Sie Anzeigen in Ihrer App anfordern, prüfen Sie, ob Sie über ConsentInfo::GetInstance()‑> CanRequestAds() die Einwilligung des Nutzers eingeholt haben. Es gibt zwei Möglichkeiten, die Einwilligung einzuholen:

Nachdem in der aktuellen Sitzung die Einwilligung eingeholt wurde.
Unmittelbar nach dem Anruf bei RequestConsentInfoUpdate(). Möglicherweise wurde die Einwilligung bereits in der vorherigen Sitzung erteilt. Als Best Practice für die Latenz empfehlen wir, nicht auf den Abschluss des Callbacks zu warten, damit du nach dem Start deiner App so schnell wie möglich mit dem Laden von Anzeigen beginnen kannst.

Wenn bei der Einwilligungsabfrage ein Fehler auftritt, sollten Sie trotzdem prüfen, ob Sie Anzeigen anfordern können. Das UMP SDK verwendet den Einwilligungsstatus aus der vorherigen Sitzung.

Im folgenden vollständigen Beispiel wird die Abfrage der Update-Schleife verwendet. Sie können aber auch OnCompletion-Callbacks verwenden, um asynchrone Vorgänge zu überwachen. Verwenden Sie die Technik, die am besten zu Ihrer Codestruktur passt.

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

Test

Wenn Sie die Integration in Ihrer App während der Entwicklung testen möchten, können Sie Ihr Testgerät wie unten beschrieben programmatisch 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 Protokollausgabe nach einer Meldung, die Ihrer Geräte-ID und der Anleitung zum Hinzufügen als Testgerät ähnelt:

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 des Testgeräts in die Zwischenablage.

Ändern Sie den Code so, dass für ConsentRequestParameters.debug_settings.debug_device_ids 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 mithilfe von debug_settings.debug_geography testen, als befände sich das Gerät in verschiedenen Regionen, z. B. im EWR oder im Vereinigten Königreich. Die Debug-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

Wenn Sie Ihre App mit dem UMP SDK testen, kann es hilfreich sein, den Status des SDK zurückzusetzen, um die erste Installation eines Nutzers zu simulieren. Dazu bietet das SDK die Methode Reset().

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