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)

Nachrichtentyp 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 anhand der in Ihrem Projekt festgelegten AdMob-Anwendungs-ID erstellt wurde.

Weitere Informationen finden Sie unter Datenschutz und Mitteilungen.

SDK Installieren

1. Folgen Sie der Anleitung zum Installieren des Google Mobile Ads (GMA) C++ SDKs. Das UMP C++ SDK ist im GMA C++ SDK enthalten.

2. Konfigurieren Sie die AdMob-App-ID Ihrer App im Projekt, bevor Sie fortfahren.

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

Hinweis: Die GetInstance()-Methoden haben einen optionalen Ausgabeparameter firebase::InitResult, der firebase::kInitResultSuccess zurückgibt, wenn das SDK erfolgreich initialisiert wurde, oder firebase::kInitResultFailedMissingDependency, wenn in Ihrer Anwendung erforderliche Abhängigkeiten fehlen. Wenn dieser Fehler auftritt, prüfen Sie, ob Sie alle Installationsschritte für Ihre Plattform ausgeführt haben.

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

Hinweis :Sie müssen das Google Mobile Ads C++ SDK nicht initialisieren, bevor Sie das User Messaging Platform SDK initialisieren.

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:

1. Rufe OnCompletion() auf und gib dabei deine eigene Callback-Funktion an, die aufgerufen wird, wenn der Vorgang abgeschlossen ist.
2. 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() von 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.

Hinweis: Für den von RequestConsentInfoUpdate() zurückgegebenen Fehlercode wird die Enum-Klasse ConsentRequestError verwendet. Für alle anderen Vorgänge wird ConsentFormError verwendet.

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.

Hinweis: Im UMP C++ SDK geben alle asynchronen Vorgänge firebase::Future<void> zurück.

Einwilligungsinformationen des Nutzers abrufen

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 Gemäß einigen Datenschutzmitteilungen müssen Nutzer in Apps jederzeit ihre Datenschutzoptionen ändern können.

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

Warnung :Wenn Sie andere Methoden zur Überprüfung des Einwilligungsstatus verwenden, z. B. den Cache in Ihrer App oder einen zuvor gespeicherten Einwilligungsstring, kann dies zu einem TCF 3.3-Fehler führen, wenn die Einwilligung abgelaufen ist.

Formular für Datenschutzmitteilungen laden und anzeigen

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.

Wichtiger Hinweis: Wenn für keine Formulare mit Datenschutzmitteilungen die Einwilligung des Nutzers vor der Anfrage von Anzeigen erforderlich ist, wird der Rückruf sofort aufgerufen.

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

Hinweis: Je nach Plattform ist FormParent entweder eine JNI-jobject-Referenz auf eine Android-Activity oder ein Verweis auf eine iOS-UIViewController, die in einen FormParent-Typ umgewandelt wird.

Wenn Sie Aktionen ausführen müssen, nachdem der Nutzer eine Auswahl getroffen oder das Formular geschlossen hat, fügen Sie diese Logik in den Code ein, der Future verarbeitet, der von LoadAndShowConsentFormIfRequired() zurückgegeben wird.

Datenschutzoptionen

Einige Formulare für Datenschutzmitteilungen werden über einen vom Publisher gerenderten Einstiegspunkt für Datenschutzoptionen angezeigt, über den Nutzer ihre Datenschutzoptionen jederzeit verwalten können. Weitere Informationen dazu, welche Mitteilung Ihre Nutzer am Einstiegspunkt für die 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:

An den folgenden Stellen können Sie prüfen, ob Sie Anzeigen anfordern können, während Sie die Einwilligung einholen:

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

Wichtig : ConsentInfo::GetInstance()‑> CanRequestAds() gibt immer false zurück, bis RequestConsentInfoUpdate() aufgerufen wurde.

Wenn bei der Einwilligungserhebung 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 die Abfrage der Updateschleife verwendet. Sie können aber auch OnCompletion-Callbacks verwenden, um asynchrone Vorgänge zu überwachen. Verwenden Sie die Methode, die Ihrer Codestruktur am besten entspricht.

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

1. Rufen Sie einfach RequestConsentInfoUpdate() an.

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

3. Kopieren Sie die ID des Testgeräts in die Zwischenablage.

4. Ändern Sie Ihren Code so, dass ConsentRequestParameters.debug_settings.debug_device_ids auf eine Liste Ihrer Testgeräte-IDs gesetzt 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, damit Sie die Erstinstallation eines Nutzers simulieren können. Dazu bietet das SDK die Methode Reset().

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

Achtung :Diese Methode ist nur für Tests vorgesehen. Reset() darf nicht in Produktionscode aufgerufen werden.