Acquisto rapido incorporato

L'integrazione dell'Acquisto rapido incorporato consente di incorporare l'acquisto rapido basato sul web nelle piattaforme Google. Utilizza questo percorso se il tuo prodotto richiede una logica complessa (ad es. personalizzazioni) che l'API nativa non può supportare. Implementerai un'interfaccia utente di pagamento che verrà incorporata nel flusso di pagamento tramite un iframe.

Che cos'è l'Acquisto rapido incorporato?

Il pagamento incorporato (EC) consente a un host (come la Ricerca Google o un agente AI) di visualizzare il tuo pagamento esistente basato sul web all'interno della sua applicazione (utilizzando un iframe o una webview). A differenza di un reindirizzamento web standard, questo consente la comunicazione bidirezionale. L'host può "delegare" attività specifiche come la selezione di un indirizzo salvato o il pagamento con una credenziale memorizzata per offrire un'esperienza più rapida e nativa, mentre tu rimani il commerciante registrato e gestisci la creazione effettiva dell'ordine.

Elenco di controllo per l'implementazione per i commercianti

Per supportare Embedded Checkout, devi implementare i seguenti requisiti nell'API UCP e nell'applicazione di pagamento frontend.

1. Abilitare il rilevamento (API UCP)

Devi dichiarare che il tuo checkout supporta l'estensione incorporata nelle risposte dell'API UCP.

• Azione: aggiungi l'oggetto funzionalità dev.ucp.shopping.embedded_checkout all'array delle funzionalità di risposta UCP.
• Requisito: includi gli URL delle specifiche e dello schema.
• (Facoltativo): se per caricare il pagamento è necessaria l'autenticazione (ad esempio, un token JWT), imposta auth.required su 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. Inizializzazione dell'URL dell'handle (frontend)

Quando l'host carica il tuo continue_url, aggiunge parametri di query specifici. Il frontend deve analizzarli immediatamente al caricamento.

• Azione: analizza i seguenti parametri di query dell'URL:
  • ec_version: la versione del protocollo (ad es. 2026-01-11).
  • ec_auth: (se applicabile) convalida il token di autenticazione fornito dall'host, se hai impostato auth.required: true.
  • ec_delegate: un elenco separato da virgole di azioni che l'host vuole gestire in modo nativo (ad es. payment.credential, fulfillment.address_change, payment.instruments_change).

3. Stabilire la comunicazione (frontend)

La comunicazione avviene tramite postMessage utilizzando il formato JSON-RPC 2.0.

• Azione: implementa un listener per gli eventi message.
• Requisito: devi convalidare l'origine di ogni messaggio per assicurarti che corrisponda all'host.
• Supporto nativo: per gli host di app native, controlla e utilizza le variabili globali inserite (ad es. window.EmbeddedCheckoutProtocolConsumer) se postMessage non è disponibile.

4. Eseguire l'handshake (frontend)

Non appena viene visualizzato il pagamento, devi comunicare all'host che sei pronto e confermare le deleghe che accetti.

• Azione: invia la richiesta ec.ready immediatamente dopo il caricamento.
• Payload: includi un array delegate che elenca le funzionalità che accetti di lasciare gestire all'host.
• Esempio: se l'URL ha richiesto ec_delegate=payment.credential e tu accetti, includi "payment.credential" nel payload ec.ready.

// 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. Implementare la logica di delega (frontend)

Se hai accettato una delega nell'handshake, devi modificare il comportamento della UI per evitare conflitti.

• Azione: nascondi gli elementi UI pertinenti per le attività delegate.
• Esempio: se fulfillment.address_change è delegato, nascondi il modulo dell'indirizzo e mostra invece un pulsante "Modifica indirizzo".
• Azione: quando l'utente fa clic su questo pulsante, invia un messaggio _request (ad es. ec.fulfillment.address_change_request) all'host.
• Azione: attendi la risposta dell'organizzatore. La risposta conterrà i nuovi dati (ad es. l'indirizzo selezionato).
• Requisito: aggiorna lo stato del pagamento utilizzando una sostituzione in stile PUT (sostituisci l'intera sezione dell'oggetto) in base ai dati restituiti dall'host.

// 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. Inviare aggiornamenti del ciclo di vita e dello stato (frontend)

Devi tenere informato l'host sullo stato del pagamento in modo che possa aggiornare la propria interfaccia utente o gestire gli errori.

• Azione: invia notifiche (messaggi senza ID) quando lo stato cambia:
  • ec.start: Quando il pagamento è completamente visibile.
  • ec.line_items.change: Se i contenuti o i totali del carrello vengono aggiornati.
  • ec.buyer.change: Se i dettagli dell'acquirente vengono aggiornati.
  • ec.complete: quando l'ordine viene effettuato correttamente.
  • ec.error: se si verifica un errore critico.

7. Applica la sicurezza (server/intestazioni)

Devi assicurarti che il tuo checkout non possa essere incorporato da malintenzionati.

• Azione: implementa le intestazioni Content Security Policy (CSP).
• Requisito: imposta frame-ancestors <host_origin>; per consentire l'incorporamento solo da host attendibili.
• Navigazione: blocca la logica che allontana l'utente dal flusso di pagamento (ad es. rimuovi i link "Continua lo shopping" che rimandano alla home page). Sono consentite eccezioni per la verifica 3DS o i reindirizzamenti di pagamento di terze parti.