Eingebetteter Direktkauf

Mit der Integration des eingebetteten Direktkaufs kann Ihr webbasierter Direktkauf in Google-Produkte eingebettet werden. Verwenden Sie diesen Pfad, wenn Ihr Produkt eine komplexe Logik (z.B. Anpassungen) erfordert, die von der Native API nicht unterstützt wird. Sie implementieren eine Benutzeroberfläche für die Kasse, die über ein iFrame in den Kassiervorgang eingebettet wird.

Was ist der eingebettete Direktkauf?

Mit der eingebetteten Kaufabwicklung kann ein Host (z. B. die Google Suche oder ein KI-Agent) Ihre vorhandene webbasierte Kaufabwicklung in seiner Anwendung (über ein iFrame oder eine WebView) anzeigen. Im Gegensatz zu einer standardmäßigen Webweiterleitung ist hier eine bidirektionale Kommunikation möglich. Der Host kann bestimmte Aufgaben wie die Auswahl einer gespeicherten Adresse oder die Zahlung mit gespeicherten Anmeldedaten „delegieren“, um eine schnellere, native Erfahrung zu ermöglichen. Sie bleiben jedoch der Händler und kümmern sich um die eigentliche Auftragserstellung.

Checkliste für die Implementierung durch Händler

Um den eingebetteten Zahlungsvorgang zu unterstützen, müssen Sie die folgenden Anforderungen in Ihrer UCP API und Ihrer Frontend-Zahlungsvorgangsanwendung implementieren.

1. Erkennung aktivieren (UCP API)

Sie müssen in Ihren UCP API-Antworten angeben, dass Ihr Checkout die eingebettete Erweiterung unterstützt.

  • Aktion: Fügen Sie das dev.ucp.shopping.embedded_checkout-Funktionsobjekt Ihrem UCP-Antwortfunktionen-Array hinzu.
  • Anforderung: Geben Sie die Spezifikations- und Schema-URLs an.
  • Optional: Wenn Sie für das Laden der Kaufabwicklung eine Authentifizierung (z.B. ein JWT-Token) benötigen, setzen Sie auth.required auf „true“.
"capabilities": [
  {
    "name": "dev.ucp.shopping.embedded_checkout",
    "version": "2026-01-11",
    "spec": "https://ucp.dev/specs/shopping/embedded_checkout",
    "config": {
        "auth": { "required": true }
    }
  }
]

2. Alias-URL-Initialisierung (Frontend)

Wenn der Host Ihre continue_url lädt, werden bestimmte Suchparameter angehängt. Ihr Frontend muss diese sofort nach dem Laden parsen.

  • Aktion: Analysiere die folgenden URL-Suchparameter:
    • ec_version: Die Protokollversion (z.B. 2026-01-11).
    • ec_auth: (Falls zutreffend) Validieren Sie das vom Host bereitgestellte Auth-Token, wenn Sie auth.required: true festlegen.
    • ec_delegate: Eine durch Kommas getrennte Liste von Aktionen, die der Host nativ ausführen möchte (z.B. payment.credential, fulfillment.address_change, payment.instruments_change).

3. Kommunikation herstellen (Frontend)

Die Kommunikation erfolgt über postMessage im JSON-RPC 2.0-Format.

  • Aktion: Implementieren Sie einen Listener für message-Ereignisse.
  • Anforderung: Sie müssen den Ursprung jeder Nachricht validieren, um sicherzustellen, dass er mit dem Host übereinstimmt.
  • Native Unterstützung: Bei nativen App-Hosts müssen Sie nach injizierten globalen Variablen suchen und diese verwenden (z.B. window.EmbeddedCheckoutProtocolConsumer), wenn postMessage nicht verfügbar ist.

4. Handshake durchführen (Frontend)

Sobald der Checkout gerendert wird, müssen Sie dem Host mitteilen, dass Sie bereit sind, und bestätigen, welche Delegierungen Sie akzeptieren.

  • Aktion: Senden Sie die ec.ready-Anfrage unmittelbar nach dem Laden.
  • Nutzlast: Fügen Sie ein delegate-Array mit den Funktionen ein, die der Host verarbeiten darf.
  • Beispiel: Wenn die angeforderte URL ec_delegate=payment.credential lautet und Sie die Anfrage akzeptieren, fügen Sie "payment.credential" in die ec.ready-Nutzlast ein.
// Example: Sending the ec.ready message
const hostWindow = window.parent;
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "ready_1",
  "method": "ec.ready",
  "params": {
    "delegate": ["payment.credential"] // List capabilities you accept to delegate
  }
}), "*");

5. Delegierungslogik implementieren (Frontend)

Wenn Sie eine Delegation im Handshake akzeptiert haben, müssen Sie das Verhalten Ihrer Benutzeroberfläche ändern, um Konflikte zu vermeiden.

  • Aktion: Blenden Sie die relevanten UI-Elemente für delegierte Aufgaben aus.
  • Beispiel: Wenn fulfillment.address_change delegiert ist, blenden Sie das Adressformular aus und zeigen Sie stattdessen die Schaltfläche „Adresse ändern“ an.
  • Aktion: Wenn der Nutzer auf die Schaltfläche klickt, senden Sie eine _request-Nachricht (z.B. ec.fulfillment.address_change_request) an den Host.
  • Aktion: Warten Sie auf die Antwort des Hosts. Die Antwort enthält die neuen Daten, z.B. die ausgewählte Adresse.
  • Anforderung: Aktualisieren Sie den Checkout-Status mit einem PUT-ähnlichen Ersetzen (ersetzen Sie den gesamten Objektbereich) basierend auf den vom Host zurückgegebenen Daten.
// Example: requesting payment credential
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "req_1",
  "method": "ec.payment.credential_request",
  "params": {
      "checkout": currentCheckoutState // Pass the full current checkout object
  }
}), "*");

6. Lebenszyklus- und Statusaktualisierungen senden (Frontend)

Sie müssen den Host über den Status des Check-outs auf dem Laufenden halten, damit er seine Benutzeroberfläche aktualisieren oder Fehler beheben kann.

  • Aktion: Benachrichtigungen (Nachrichten ohne ID) bei Statusänderungen senden:
    • ec.start: Wenn die Kaufabwicklung vollständig sichtbar ist.
    • ec.line_items.change: Wenn der Warenkorbinhalt oder die Gesamtsumme aktualisiert wird.
    • ec.buyer.change: Wenn Käuferdetails aktualisiert werden.
    • ec.complete: Wenn die Bestellung erfolgreich aufgegeben wurde.
    • ec.error: Wenn ein kritischer Fehler auftritt.

7. Sicherheit erzwingen (Server/Header)

Sie müssen dafür sorgen, dass Ihre Kaufabwicklung nicht von böswilligen Akteuren eingebettet werden kann.

  • Maßnahme: Implementieren Sie CSP-Header (Content Security Policy).
  • Anforderung: Legen Sie frame-ancestors <host_origin>; fest, damit das Einbetten nur durch vertrauenswürdige Hosts zulässig ist.
  • Navigation: Blocklogik, die den Nutzer vom Bezahlvorgang wegführt (z.B. Entfernen von „Weiter einkaufen“-Links, die zur Startseite führen). Ausnahmen sind für die 3DS-Überprüfung oder Zahlungsweiterleitungen an Drittanbieter zulässig.