Checkout tersemat

Integrasi Checkout tersemat memungkinkan checkout berbasis web Anda disematkan di platform Google. Gunakan jalur ini jika produk Anda memerlukan logika yang kompleks (misalnya, penyesuaian) yang tidak dapat didukung oleh Native API. Anda akan menerapkan UI checkout yang akan disematkan dalam alur checkout melalui iframe.

Apa itu checkout tersemat?

Checkout tersemat (EC) memungkinkan host (seperti Google Penelusuran atau Agen AI) untuk menampilkan checkout berbasis web yang ada dalam aplikasi mereka (menggunakan iframe atau webview). Tidak seperti pengalihan web standar, hal ini memungkinkan komunikasi dua arah. Host dapat "mendelegasikan" tugas tertentu seperti memilih alamat tersimpan atau membayar dengan kredensial tersimpan untuk memberikan pengalaman yang lebih cepat dan terasa seperti aplikasi native, sementara Anda tetap menjadi Pedagang yang Tercatat dan menangani pembuatan pesanan yang sebenarnya.

Checklist penerapan penjual

Untuk mendukung Embedded Checkout, Anda harus menerapkan persyaratan berikut di seluruh UCP API dan aplikasi checkout frontend Anda.

1. Mengaktifkan penemuan (UCP API)

Anda harus menyatakan bahwa checkout Anda mendukung ekstensi sematan dalam respons API UCP.

  • Tindakan: Tambahkan objek kemampuan dev.ucp.shopping.embedded_checkout ke array kemampuan respons UCP Anda.
  • Persyaratan: Sertakan URL spesifikasi dan skema.
  • Opsional: Jika Anda memerlukan autentikasi (misalnya, token JWT) untuk memuat checkout, tetapkan auth.required ke benar.
"capabilities": [
  {
    "name": "dev.ucp.shopping.embedded_checkout",
    "version": "2026-01-11",
    "spec": "https://ucp.dev/specs/shopping/embedded_checkout",
    "config": {
        "auth": { "required": true }
    }
  }
]

2. Menangani inisialisasi URL (frontend)

Saat host memuat continue_url, host akan menambahkan parameter kueri tertentu. Frontend Anda harus segera mem-parsingnya setelah dimuat.

  • Tindakan: Parse parameter kueri URL berikut:
    • ec_version: Versi protokol (misalnya, 2026-01-11).
    • ec_auth: (Jika berlaku) Validasi token autentikasi yang diberikan oleh host, jika Anda menetapkan auth.required: true.
    • ec_delegate: Daftar tindakan yang dipisahkan koma yang ingin ditangani host secara native (misalnya, payment.credential, fulfillment.address_change, payment.instruments_change).

3. Membangun komunikasi (frontend)

Komunikasi terjadi menggunakan postMessage dengan format JSON-RPC 2.0.

  • Tindakan: Terapkan pemroses untuk peristiwa message.
  • Persyaratan: Anda harus memvalidasi asal setiap pesan untuk memastikan pesan tersebut cocok dengan host.
  • Dukungan native: Untuk host aplikasi native, periksa dan gunakan global yang disuntikkan (misalnya, window.EmbeddedCheckoutProtocolConsumer) jika postMessage tidak tersedia.

4. Melakukan handshake (frontend)

Segera setelah checkout dirender, Anda harus memberi tahu host bahwa Anda sudah siap dan mengonfirmasi delegasi yang Anda setujui.

  • Tindakan: Kirim permintaan ec.ready segera setelah memuat.
  • Payload: Sertakan array delegate yang mencantumkan kemampuan yang Anda setujui untuk ditangani host.
  • Contoh: Jika URL yang diminta adalah ec_delegate=payment.credential dan Anda menerima, sertakan "payment.credential" dalam 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. Menerapkan logika delegasi (frontend)

Jika Anda menyetujui pendelegasian dalam handshake, Anda harus mengubah perilaku UI untuk menghindari konflik.

  • Tindakan: Menyembunyikan elemen UI yang relevan untuk tugas yang didelegasikan.
  • Contoh: Jika fulfillment.address_change didelegasikan, sembunyikan formulir alamat Anda dan tampilkan tombol "Ubah Alamat".
  • Tindakan: Saat pengguna mengklik tombol tersebut, kirim pesan _request (misalnya, ec.fulfillment.address_change_request) ke host.
  • Tindakan: Tunggu respons host. Respons akan berisi data baru (misalnya, alamat yang dipilih).
  • Persyaratan: Perbarui status checkout Anda menggunakan penggantian gaya PUT (ganti seluruh bagian objek) berdasarkan data yang ditampilkan oleh 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. Mengirim update siklus proses & status (frontend)

Anda harus terus memberi tahu host tentang status checkout agar mereka dapat memperbarui UI atau menangani error.

  • Tindakan: Kirim notifikasi (pesan tanpa ID) saat status berubah:
    • ec.start: Saat checkout terlihat sepenuhnya.
    • ec.line_items.change: Jika konten atau total keranjang diperbarui.
    • ec.buyer.change: Jika detail pembeli diperbarui.
    • ec.complete: Saat pesanan berhasil dilakukan.
    • ec.error: Jika terjadi error kritis.

7. Menerapkan keamanan (server/header)

Anda harus memastikan bahwa proses checkout Anda tidak dapat disematkan oleh pelaku kejahatan.

  • Tindakan: Terapkan header Kebijakan Keamanan Konten (CSP).
  • Persyaratan: Tetapkan frame-ancestors <host_origin>; untuk mengizinkan penyematan hanya oleh host tepercaya.
  • Navigasi: Logika blok yang mengarahkan pengguna keluar dari alur checkout (misalnya, menghapus link "Lanjutkan Belanja" yang mengarah ke halaman beranda Anda). Pengecualian diizinkan untuk verifikasi 3DS atau pengalihan pembayaran pihak ketiga.