Jetzt loslegen

Gemäß der Google-Richtlinie zur Einwilligung der Nutzer in der EU müssen Sie Ihren Nutzern im Europäischen Wirtschaftsraum (EWR) sowie im Vereinigten Königreich bestimmte Informationen offenlegen und ihre Einwilligung zur Verwendung von Cookies oder anderen lokalen Speicherverfahren, sofern gesetzlich erforderlich, sowie zur Verwendung von personenbezogenen Daten wie der Werbe-ID für Anzeigen einholen. Die Richtlinie entspricht den Anforderungen der EU-Datenschutzrichtlinie für elektronische Kommunikation und der EU-Datenschutz-Grundverordnung (DSGVO).

Google bietet das User Messaging Platform (UMP) SDK, um Publisher bei der Umsetzung dieser Richtlinie zu unterstützen. Das UMP SDK wurde aktualisiert und unterstützt jetzt die neuesten IAB-Standards. All diese Konfigurationen können jetzt bequem unter AdMob „Datenschutz und Mitteilungen“ verwaltet werden.

Voraussetzungen

• Arbeiten Sie den Startleitfaden durch.

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

• Wenn Sie an DSGVO-bezogenen Anforderungen arbeiten, lesen Sie den Artikel Auswirkungen der IAB-Anforderungen auf Mitteilungen zur Einwilligung der Nutzer in der EU

Mitteilungstyp erstellen

Sie können Nutzermitteilungen mit einem der verfügbaren Mitteilungstypen für Nutzer auf dem Tab Datenschutz und Mitteilungen in Ihrem AdMob erstellen. Das UMP SDK versucht, eine Nutzernachricht anzuzeigen, die mit der im Projekt festgelegten AdMob Anwendungs-ID erstellt wurde. Wenn für Ihre Anwendung keine Meldung konfiguriert ist, gibt das SDK einen Fehler zurück.

Weitere Informationen finden Sie unter Informationen zu Datenschutz und Mitteilungen.

SDK Installieren

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

2. Bevor du fortfährst, musst du die AdMob-App-ID deiner App im Projekt konfigurieren.

3. Initialisieren Sie im Code das UMP SDK, indem Sie ConsentInfo::GetInstance() aufrufen.

   • Unter Android müssen Sie das vom NDK bereitgestellte JNIEnv und Activity übergeben. Das müssen Sie nur beim ersten Aufruf von GetInstance() tun.
   • Wenn Sie in Ihrer App bereits das Firebase C++ SDK verwenden, können Sie beim ersten Aufruf von GetInstance() auch ein 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
   

Die nachfolgenden ConsentInfo::GetInstance()-Aufrufe geben alle dieselbe Instanz zurück.

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

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

Hinweis :Sie müssen das Google Mobile Ads C++ SDK vor der Initialisierung des User Messaging Platform SDK nicht initialisieren.

Future zum Überwachen asynchroner Vorgänge verwenden

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

Alle UMP C++-Funktionen und -Methodenaufrufe, die asynchron arbeiten, geben ein Future zurück und liefern auch die Funktion „Letztes Ergebnis“, um das Future aus dem letzten Vorgang abzurufen.

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

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

Nach Abschluss des asynchronen Vorgangs sollten Sie die error() der Future prüfen, um den Fehlercode des Vorgangs zu erhalten. Wenn der Fehlercode 0 (kConsentRequestSuccess oder kConsentFormSuccess) lautet, wurde der Vorgang erfolgreich abgeschlossen. Prüfen Sie andernfalls den Fehlercode und error_message(), um die Ursache zu ermitteln.

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

Abschluss-Callback

Das folgende Beispiel zeigt, wie Sie mit OnCompletion einen Abschluss-Callback festlegen, der nach Abschluss des asynchronen Vorgangs aufgerufen wird.

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

Schleifenabfrage aktualisieren

In diesem Beispiel werden die Ergebnisse nach dem Start eines asynchronen Vorgangs beim Start der App an anderer Stelle in der Updateschleife des Spiels überprüft (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.

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

Anfrage zur Einwilligungserklärung

Sie sollten bei jedem Start der App mit RequestConsentInfoUpdate()eine Aktualisierung der Einwilligungsinformationen des Nutzers anfordern. Damit wird bestimmt, ob der Nutzer seine Einwilligung geben muss, falls dies noch nicht geschehen ist oder die Einwilligung abgelaufen ist.

#include "firebase/gma/ump.h"

namespace ump = ::firebase::gma::ump;

void MyApplicationStart() {
  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>& result) {
      if (result.error() != ump::kConsentRequestSuccess) {
        LogMessage("Error requesting consent update: %s", result.error_message());
      } else {
        // Consent status is now available.
      }
    });
}

Ein Beispiel für die Prüfung des Abschlusses mithilfe von Aktualisierungsschleifenabfragen finden Sie oben.

Warnung: Wenn Sie den Einwilligungsstatus auf andere Weise prüfen, z. B. über den App-Cache oder einen zuvor gespeicherten Einwilligungsstring, kann es zu einem TCF 3.3-Fehler kommen, wenn die Einwilligung abgelaufen ist.

Einwilligungsformular laden und bei Bedarf einblenden

Nachdem Sie den aktuellen Einwilligungsstatus erhalten haben, rufen SieLoadAndShowConsentFormIfRequired() in der KlasseConsentInfo auf, um ein Einwilligungsformular zu laden. Wenn der Einwilligungsstatus erforderlich ist, lädt das SDK ein Formular und zeigt es sofort aus dem bereitgestellten FormParentan. Die Future erledigt , nachdem das Formular geschlossen wurde. Ist keine Einwilligung erforderlich, wird der Future erledigt .

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

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 consent form: %s", form_result.error_message());
          } else {
            // Either the form was shown and completed by the user, or consent was not required.
          }
        });
      }
    });
}

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.

Anzeigenanfrage senden

Bevor Sie Anzeigen in Ihrer App anfordern, prüfen Sie, ob Sie über ConsentInfo::GetInstance()‑>CanRequestAds()die Einwilligung des Nutzers eingeholt haben. Beim Einholen der Einwilligung müssen Sie zwei Stellen prüfen:

1. Sobald in der aktuellen Sitzung die Einwilligung eingeholt wurde.
2. Unmittelbar nach Ihrem 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.

Hinweis: ConsentInfo::GetInstance()‑>CanRequestAds() Es wird immer false zurückgegeben, bis Sie angerufen haben RequestConsentInfoUpdate()

Wenn beim Einholen der Einwilligung ein Fehler auftritt, sollten Sie trotzdem versuchen, Anzeigen anzufordern. Das UMP SDK verwendet den Einwilligungsstatus aus der vorherigen Sitzung.

Im folgenden vollständigen Beispiel werden Aktualisierungsschleifenabfragen verwendet. Sie können jedoch 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 consent 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;
      }
    }
  }
}

Datenschutzoptionen

Bei einigen Einwilligungsformularen muss der Nutzer seine Einwilligung jederzeit ändern. Führe bei Bedarf die folgenden Schritte aus, um eine Schaltfläche für Datenschutzoptionen zu implementieren.

Folgende Schritte sind hierzu nötig:

1. Implementieren Sie ein UI-Element, z. B. eine Schaltfläche auf der Einstellungsseite Ihrer App, über das ein Formular mit Datenschutzoptionen ausgelöst werden kann.
2. Sobald LoadAndShowConsentFormIfRequired() abgeschlossen ist, prüfen SiegetPrivacyOptionsRequirementStatus() , um zu bestimmen, ob das UI-Element angezeigt werden soll, über das das Formular für Datenschutzoptionen angezeigt werden kann.
3. Wenn ein Nutzer mit Ihrem UI-Element interagiert, rufen SieshowPrivacyOptionsForm() auf, um das Formular aufzurufen, sodass der Nutzer seine Datenschutzoptionen jederzeit aktualisieren kann.

Testen

Wenn du die Integration in deine App während der Entwicklung testen möchtest, folge dieser Anleitung, um dein Testgerät programmatisch zu registrieren. Entferne den Code, mit dem diese Testgeräte-IDs festgelegt werden, bevor du deine App veröffentlichst.

1. Rufen Sie uns unter RequestConsentInfoUpdate()an.

2. Suchen Sie in der Logausgabe nach einer Nachricht ähnlich der folgenden. Sie enthält Ihre Geräte-ID und wie Sie sie als Testgerät hinzufügen können:

   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 Testgeräte-ID in die Zwischenablage.

4. Ändern Sie den Code so, dass ConsentRequestParameters.debug_settings.debug_device_ids eine Liste Ihrer Testgeräte-IDs übergeben 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 testen, als würde sich das Gerät mithilfe von ConsentRequestParameters.debug_settings.debug_geographyim EWR oder Vereinigten Königreich befinden. 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

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. Das SDK bietet dazu die Methode Reset() .

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

Achtung :Diese Methode ist nur für Testzwecke gedacht. Im Produktionscode solltest du Reset() nicht aufrufen.