Wie man AdMob-Datenschutzzustimmungen in Capacitor handhabt

Um die AdMob-GDPR-Zustimmung in einer Capacitor-Anwendung zu handhaben, verwenden Sie Googles User Messaging Platform (UMP) SDK: Fordern Sie bei jeder Startanforderung die Zustimmungsinformationen an, zeigen Sie das Zustimmungsformular an, wenn erforderlich, und initialisieren Sie die Anzeigen nur dann canRequestAds ist wahr. Sie benötigen auch einen Datenschutzeinstellungspunkt, damit Benutzer ihre Wahl ändern können, und auf iOS sollte der UMP-Fluss vor dem App-Tracking-Transparenz-Anforderung erfolgen. Diese Anleitung zeigt den vollständigen Fluss mit zwei Konfigurationen: einer Plugin, das UMP in JavaScript einhüllt, und @capgo/capacitor-admob mit einer kleinen nativen Zustimmungsbrücke.

Was UMP tut und warum AdMob es benötigt

Seit Januar 2024 verlangt Google von Verlagen, die Anzeigen an Benutzer in der EEA, im Vereinigten Königreich und in der Schweiz bereitstellen, die Verwendung eines von Google zertifizierten Consent-Management-Plattformen (CMP) zu verwenden, die mit dem IAB-Transparenz- und Consent-Framework (TCF) integriert ist. Der UMP SDK ist Googles eigene zertifizierte CMP, kostenlos und in der AdMob-Konsole integriert.

UMP tut drei Dinge für Sie:

1. Ermittelt, ob der Benutzer in einer Region ist, in der der Einwilligungserfordernis unterliegt.
2. Zeigt die von Ihnen in AdMob konfigurierte Einwilligungsnachricht in der Sprache des Benutzers an.
3. Speichert die von dem Benutzer getroffenen Entscheidungen als TC-String auf dem Gerät (die Standard- IABTCF_ Schlüssel in UserDefaults auf iOS und SharedPreferences auf Android), die die Google Mobile Ads SDK und die Mediationspartner lesen, wenn sie Anzeigen anfragen.

Sie können UMP auch für die US-Bundesstaatsdatenschutzvorschriften verwenden, die AdMob als "US-Staaten"-Nachrichten bezeichnet, aus der gleichen Konsole.

Schritt 1: Erstellen Sie die Nachrichten in AdMob

In der AdMob-Konsole gehen Sie zu Daten schutz & Nachrichten:

• Erstelle ein europäische Vorschriften Nachricht (GDPR). Wähle, welche Apps davon betroffen sind, die Sprachen und deine Liste der Werbepartner.
• Optionell erstelle eine US Bundesstaaten Nachricht.
• Erstelle auf iOS eine IDFA-Erklärung Nachdem Sie die App Tracking Transparency beantragen möchten, zeigt UMP eine Nachricht an, bevor das System die ATT-Anzeige zeigt.
• Veröffentliche die Nachrichten. Eine nicht veröffentlichte Nachricht wird nie angezeigt.

Wenn die Form in deiner App später nie erscheint, ist eine nicht veröffentlichte oder nicht zugewiesene Nachricht das erste, was du überprüfen solltest.

Schritt 2: Bestimmen Sie die Reihenfolge der Aktionen

Die für die meisten Apps geeignete Reihenfolge ist:

1. Die App startet.
2. Bitten Einwilligungsinformationen aktualisieren mit UMP (jede Start).
3. Wenn erforderlich, laden und zeigen Sie das Einwilligungsfeld.
4. Wenn canRequestAds wahr ist, starten Sie die Mobile Ads SDK und laden Sie Anzeigen.
5. Zeigen Sie auf der Einstellungsseite ein „Datenschutz-Einstellungen“-Eintrag an, wenn UMP sagt, dass Datenschutzeinstellungen erforderlich sind.

Google ermöglicht auch das Starten der Mobile Ads SDK parallel zum Einwilligungsantrag, wenn canRequestAds wahr war, bereits aus einer vorherigen Sitzung. Das verkürzt die Zeit bis zum ersten Anzeigen für wiederkehrende Benutzer.

Option A: Ein Plugin, das UMP in JavaScript einhüllt

@capacitor-community/admob (Version 8 unterstützt Capacitor 8) offenbart UMP-Methode direkt: requestConsentInfo, showConsentForm, showPrivacyOptionsForm und resetConsentInfo.

bun add @capacitor-community/admob
bunx cap sync

import {
  AdMob,
  AdmobConsentStatus,
  AdmobConsentDebugGeography,
} from '@capacitor-community/admob';

export async function initAdsWithConsent(isDebug: boolean) {
  await AdMob.initialize();

  let info = await AdMob.requestConsentInfo(
    isDebug
      ? {
          debugGeography: AdmobConsentDebugGeography.EEA,
          testDeviceIdentifiers: ['YOUR_TEST_DEVICE_ID'],
        }
      : undefined,
  );

  if (info.isConsentFormAvailable && info.status === AdmobConsentStatus.REQUIRED) {
    info = await AdMob.showConsentForm();
  }

  // The enum value is the string 'REQUIRED'
  const showPrivacyEntry = String(info.privacyOptionsRequirementStatus) === 'REQUIRED';

  return { canRequestAds: info.canRequestAds, showPrivacyEntry };
}

export async function openPrivacyOptions() {
  await AdMob.showPrivacyOptionsForm();
}

Dieses Plugin ist die einzige Ausnahme in der Reihenfolge oben: Sein README erfordert AdMob.initialize() vorher requestConsentInfo()und auf iOS kann die Zustimmungserklärung nicht vorhergezeigt werden, bis initialize() hat gelaufen. initialize() startet den SDK , lädt jedoch keine Anzeigen, daher ist die Regel, nie eine Anzeige zu laden, bis canRequestAds ist wahr. Wenn Sie benötigen, dass der SDK stehen bleibt, bis der Benutzer geantwortet hat, verwenden Sie Option B, bei der der Konsent läuft, bevor AdMob.start().

Überprüfen canRequestAds vor jeder Anzeigenaufladung, nicht nur bei der Startzeit, weil der Benutzer den Konsent aus der Datenschutzoptionenform zurückziehen kann.

Option B: @capgo/capacitor-admob mit einem nativen UMP-Bridge

@capgo/capacitor-admob gibt Ihnen AdMob.start(), Anzeigenanforderungskonfiguration, Banner, interstitielle, rewardierte und rewardierte interstitielle Anzeigen, plus iOS-Tracking-Autorisierung. Es wrappt UMP nicht, daher fügen Sie ein kleines app-lokales Plugin hinzu, das den Konsent-Flow läuft, bevor Sie die Funktion aufrufen. AdMob.start().

bun add @capgo/capacitor-admob
bunx cap sync

Fügen Sie das UMP SDK hinzu

• iOS: Hinzufügen Sie Googles GoogleUserMessagingPlatform Paket mit Swift Package Manager (Capacitor 8 Projekte verwenden SPM standardmäßig), oder das CocoaPods-Pod des gleichen Namens, wenn Ihr Projekt CocoaPods noch verwendet.
• Android: im android/app/build.gradle:

dependencies {
    implementation "com.google.android.ump:user-messaging-platform:<latest version>"
}

Wenden Sie die neueste Version aus Googles Maven-Repository an.

iOS-Zustimmungs-Plugin

Erstellen Sie ios/App/App/ConsentPlugin.swift:

import Capacitor
import UserMessagingPlatform

@objc(ConsentPlugin)
public class ConsentPlugin: CAPPlugin, CAPBridgedPlugin {
    public let identifier = "ConsentPlugin"
    public let jsName = "Consent"
    public let pluginMethods: [CAPPluginMethod] = [
        CAPPluginMethod(name: "gather", returnType: CAPPluginReturnPromise),
        CAPPluginMethod(name: "showPrivacyOptions", returnType: CAPPluginReturnPromise),
    ]

    @objc func gather(_ call: CAPPluginCall) {
        let parameters = RequestParameters()
        DispatchQueue.main.async {
            ConsentInformation.shared.requestConsentInfoUpdate(with: parameters) { error in
                if let error = error {
                    call.reject(error.localizedDescription)
                    return
                }
                guard let vc = self.bridge?.viewController else {
                    call.reject("No view controller")
                    return
                }
                ConsentForm.loadAndPresentIfRequired(from: vc) { formError in
                    if let formError = formError {
                        call.reject(formError.localizedDescription)
                        return
                    }
                    call.resolve(self.state())
                }
            }
        }
    }

    @objc func showPrivacyOptions(_ call: CAPPluginCall) {
        DispatchQueue.main.async {
            guard let vc = self.bridge?.viewController else {
                call.reject("No view controller")
                return
            }
            ConsentForm.presentPrivacyOptionsForm(from: vc) { formError in
                if let formError = formError {
                    call.reject(formError.localizedDescription)
                    return
                }
                call.resolve(self.state())
            }
        }
    }

    private func state() -> [String: Any] {
        return [
            "canRequestAds": ConsentInformation.shared.canRequestAds,
            "privacyOptionsRequired":
                ConsentInformation.shared.privacyOptionsRequirementStatus == .required,
        ]
    }
}

Registrieren Sie es von einer CAPBridgeViewController Unterklasse, und setzen Sie diese Klasse auf dem View Controller in Main.storyboard:

import Capacitor

class MainViewController: CAPBridgeViewController {
    override open func capacitorDidLoad() {
        bridge?.registerPluginInstance(ConsentPlugin())
    }
}

Android-Zustimmungs-Plugin

Erstellen android/app/src/main/java/com/example/app/ConsentPlugin.java (Verwenden Sie Ihren Paketnamen):

package com.example.app;

import com.getcapacitor.JSObject;
import com.getcapacitor.Plugin;
import com.getcapacitor.PluginCall;
import com.getcapacitor.PluginMethod;
import com.getcapacitor.annotation.CapacitorPlugin;
import com.google.android.ump.ConsentInformation;
import com.google.android.ump.ConsentRequestParameters;
import com.google.android.ump.UserMessagingPlatform;

@CapacitorPlugin(name = "Consent")
public class ConsentPlugin extends Plugin {

    @PluginMethod
    public void gather(PluginCall call) {
        ConsentInformation info = UserMessagingPlatform.getConsentInformation(getContext());
        ConsentRequestParameters params = new ConsentRequestParameters.Builder().build();

        getActivity().runOnUiThread(() ->
            info.requestConsentInfoUpdate(
                getActivity(),
                params,
                () -> UserMessagingPlatform.loadAndShowConsentFormIfRequired(getActivity(), formError -> {
                    if (formError != null) {
                        call.reject(formError.getMessage());
                        return;
                    }
                    call.resolve(state(info));
                }),
                requestError -> call.reject(requestError.getMessage())
            )
        );
    }

    @PluginMethod
    public void showPrivacyOptions(PluginCall call) {
        getActivity().runOnUiThread(() ->
            UserMessagingPlatform.showPrivacyOptionsForm(getActivity(), formError -> {
                if (formError != null) {
                    call.reject(formError.getMessage());
                    return;
                }
                call.resolve(state(UserMessagingPlatform.getConsentInformation(getContext())));
            })
        );
    }

    private JSObject state(ConsentInformation info) {
        JSObject ret = new JSObject();
        ret.put("canRequestAds", info.canRequestAds());
        ret.put(
            "privacyOptionsRequired",
            info.getPrivacyOptionsRequirementStatus() ==
                ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED
        );
        return ret;
    }
}

Registrieren Sie es in MainActivity.java vorher super.onCreate:

public class MainActivity extends BridgeActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        registerPlugin(ConsentPlugin.class);
        super.onCreate(savedInstanceState);
    }
}

Rufen Sie es aus TypeScript auf.

import { registerPlugin } from '@capacitor/core';
import { AdMob, BannerAd } from '@capgo/capacitor-admob';

interface ConsentState {
  canRequestAds: boolean;
  privacyOptionsRequired: boolean;
}

interface ConsentPlugin {
  gather(): Promise<ConsentState>;
  showPrivacyOptions(): Promise<ConsentState>;
}

const Consent = registerPlugin<ConsentPlugin>('Consent');

export async function startAds() {
  let state: ConsentState;
  try {
    state = await Consent.gather();
  } catch (err) {
    console.warn('Consent flow failed', err);
    return { showPrivacyEntry: false };
  }

  if (state.canRequestAds) {
    await AdMob.start();
    const banner = new BannerAd({
      adUnitId: 'ca-app-pub-3940256099942544/2934735716', // Google test banner (iOS)
      position: 'bottom',
    });
    await banner.show();
  }

  return { showPrivacyEntry: state.privacyOptionsRequired };
}

export const openPrivacyOptions = () => Consent.showPrivacyOptions();

Native code-Änderungen erfordern eine neue App-Store-Build. Anschließend können Sie die Zustimmungskopie in Ihren Einstellungen und die Werbeeinblendungslogik im Release mit einschließen. Capgo Live-Updates.

Schritt 3: Fügen Sie die Datenschutzoptionen-Eintragspunkt hinzu

When UMP reports that privacy options are required, Google expects a visible way to reopen the consent choices. Add a “Privacy settings” row to your settings page and hide it when not required:

const { showPrivacyEntry } = await startAds();
document.querySelector('#privacy-row')?.toggleAttribute('hidden', !showPrivacyEntry);
document.querySelector('#privacy-row')?.addEventListener('click', () => openPrivacyOptions());

Nachdem sich der Benutzer seine Auswahl geändert hat, lesen Sie canRequestAds wieder vor der nächsten Anzeigenanfrage.

Schritt 4: Transparenz bei der App-Tracking auf iOS

ATT ist getrennt von der DSGVO. ATT kontrolliert den Zugriff auf die IDFA auf iOS. Die DSGVO-Einwilligung bestimmt, ob und wie personenbezogene Daten verarbeitet werden dürfen. Sie benötigen in der Regel beide für einen EU-Nutzer auf iOS.

• Hinzufügen NSUserTrackingUsageDescription zu Info.plist.
• Zeige dem UMP die IDFA-Erklärungsnachricht und löse ATT aus, wenn Sie diese Nachricht in AdMob konfiguriert haben. Ansonsten fordere ATT selbst nach dem Einwilligungsfluss an.

Mithilfe von @capgo/capacitor-admob Sie können das ATT-Status direkt lesen und anfordern:

import { AdMob, TrackingAuthorizationStatus } from '@capgo/capacitor-admob';

const { status } = await AdMob.trackingAuthorizationStatus();
if (status === TrackingAuthorizationStatus.notDetermined) {
  await AdMob.requestTrackingAuthorization();
}

Capgo hat auch einen eigenständigen App-Tracking-Transparenz-Plugin wenn Sie ATT für andere SDKs benötigen. Vergessen Sie nicht, das Tracking in Ihrem Datenschutzmanifest und in den App-Store-Privatsphäre-Labels zu deklarieren, siehe unsere Datenschutzmanifest-Anleitung.

Schritt 5: Testen mit Debug-Geographie

UMP zeigt das GDPR-Formular nur Benutzern in der EEA, UK oder der Schweiz. Um es in anderen Regionen zu testen:

• Laufen Sie die App einmal aus und finden Sie die Protokollzeile von UMP mit Ihrem Geräte-Hashed-Id.
• Fügen Sie es als Testgerät hinzu und setzen Sie die Debug-Geographie auf EEA. Mit der Community-Plugin-Pass debugGeography und testDeviceIdentifiers bis requestConsentInfo. In einer nativen Brücke setzen DebugSettings auf iOS und ConsentDebugSettings auf Android nur in Debug-Builds.
• Zwischen den Starts das Einverständnis zurücksetzen (resetConsentInfo() im Community-Plugin, ConsentInformation.reset() natürlich) so dass die Form wieder erscheint.

Nie Debug-Einstellungen in Release-Builds schicken. Sie auf einem Build-Flag gate.

Schritt 6: Fehler ohne Blockierung der App behandeln.

Konsentanforderungen können fehlschlagen: Keine Netzwerkverbindung, falsig konfigurierte App-ID oder keine veröffentlichte Nachricht. Fehlschlag als „keine Anzeigen für jetzt“ behandeln, nicht als Crash:

• Wenn requestConsentInfoUpdate fehlschlägt aber canRequestAds wahr war aus einer vorherigen Sitzung, können Sie immer noch Anzeigen anfragen.
• Wenn die Form nicht geladen wird, loggen Sie es und versuchen Sie es auf dem nächsten Start.
• Never show ads while the consent form is on screen.

Troubleshooting

Die Form wird nie angezeigt. Nachricht wurde nicht veröffentlicht, nicht diesem App-ID zugeordnet oder Sie befinden sich außerhalb der EU ohne Debug-Geografie. Überprüfen Sie die AdMob-App-ID in Info.plist and AndroidManifest.xml passt im Konsolenfenster.

Die Form zeigt jeden Start. Der Benutzer schloss es ohne Wahl, oder Sie rufen in der Produktion code.

canRequestAds fals für US-Benutzer. Sie veröffentlichten eine US-Staaten-Meldung und der Benutzer stimmte der Verwendung oder Weitergabe seiner Daten nicht zu. Dienen Sie nur limitierte Anzeigen über den SDK und umgehen Sie ihn nicht.

Mediationspartner erhalten keine Zustimmung. Stellen Sie sicher, dass jeder Partneradapter aktuell ist und in der Liste der Ad-Partner Ihres GDPR-Nachrichts aufgeführt ist.

Die iOS-ATT-Anzeige erscheint nie. NSUserTrackingUsageDescription ist fehlend oder der Benutzer hat in den Einstellungen „Zulassen, dass Apps nachzuverfolgen bitten“ deaktiviert.

Einhaltung über die Form hinaus

UMP handhabt die Anzeigen-Seite. Ihre App benötigt jedoch immer noch eine Datenschutzrichtlinie, die AdMob, die Datenaufbewahrungsregeln und einen Weg zur Behandlung von Datenanfragen enthält. Unsere GDPR-Kompatibilitätsliste umfasst den Rest der App.