Встроенная форма оформления заказа

Интеграция со встроенной формой оформления заказа позволяет встраивать вашу веб-форму оформления заказа в интерфейсы Google. Используйте этот вариант, если ваш продукт требует сложной логики (например, персонализации), которую не поддерживает нативный API. Вам потребуется реализовать пользовательский интерфейс оформления заказа, который будет встроен в процесс оформления заказа через iframe.

Что такое встроенная процедура оформления заказа?

Встроенная форма оформления заказа (EC) позволяет хосту (например, Google Поиску или агенту искусственного интеллекта) отображать вашу существующую веб-форму оформления заказа в своем приложении (используя iframe или webview). В отличие от стандартного веб-перенаправления, это обеспечивает двустороннюю связь. Хост может «делегировать» определенные задачи, такие как выбор сохраненного адреса или оплата с помощью сохраненных учетных данных, чтобы обеспечить более быструю и удобную для пользователя обработку, в то время как вы остаетесь продавцом и занимаетесь фактическим созданием заказа.

Контрольный список внедрения для продавцов

Для поддержки встроенной функции оформления заказа необходимо реализовать следующие требования как в вашем UCP API, так и в вашем приложении для оформления заказа на стороне клиента.

1. Включить обнаружение (UCP API)

В ответах API UCP необходимо указать, что ваша система оформления заказа поддерживает встроенное расширение.

  • Действие : Добавьте объект возможностей dev.ucp.shopping.embedded_checkout в массив возможностей ответа UCP.
  • Требование : Укажите URL-адреса спецификации и схемы.
  • Необязательно : если для загрузки страницы оформления заказа требуется аутентификация (например, токен JWT), установите auth.required в значение 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. Обработка инициализации URL (фронтенд)

Когда хост загружает ваш continue_url , он добавляет определенные параметры запроса. Ваш фронтенд должен немедленно обработать их после загрузки.

  • Действие : Проанализируйте следующие параметры запроса URL:
    • ec_version : Версия протокола (например, 2026-01-11 ).
    • ec_auth : (Если применимо) Проверить токен аутентификации, предоставленный хостом, если вы установили auth.required: true .
    • ec_delegate : Список действий, разделенных запятыми, которые хост хочет обрабатывать нативно (например, payment.credential , fulfillment.address_change , payment.instruments_change ).

3. Наладьте коммуникацию (фронтенд)

Обмен данными осуществляется с помощью postMessage в формате JSON-RPC 2.0.

  • Действие : Реализовать обработчик событий message .
  • Требование : Необходимо проверить источник каждого сообщения, чтобы убедиться, что он соответствует хосту.
  • Поддержка нативных приложений: для нативных приложений проверяйте наличие и используйте внедренные глобальные переменные (например, window.EmbeddedCheckoutProtocolConsumer ), если postMessage недоступен.

4. Выполните рукопожатие (фронтенд)

Как только завершится оформление заказа, вы должны сообщить хостинг-провайдеру о своей готовности и подтвердить, какие делегирования вы принимаете.

  • Действие : Немедленно после загрузки отправьте запрос ec.ready .
  • Полезная нагрузка : Включите массив delegate , в котором перечислены возможности, которые вы разрешаете хосту обрабатывать.
  • Пример : Если URL-адрес запрашивает ec_delegate=payment.credential , и вы принимаете запрос, добавьте "payment.credential" в полезную нагрузку 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. Реализуйте логику делегирования (фронтенд).

Если вы приняли делегирование полномочий в ходе рукопожатия, вам необходимо изменить поведение пользовательского интерфейса, чтобы избежать конфликтов.

  • Действие : Скрыть соответствующие элементы пользовательского интерфейса для делегированных задач.
  • Пример : Если fulfillment.address_change делегирована, скройте форму ввода адреса и вместо нее отобразите кнопку «Изменить адрес».
  • Действие : Когда пользователь нажимает эту кнопку, отправьте сообщение _request (например, ec.fulfillment.address_change_request ) на хост.
  • Действие : Дождитесь ответа от хоста. Ответ будет содержать новые данные (например, выбранный адрес).
  • Требование : Обновите состояние оформления заказа, используя замену в стиле PUT (замените весь раздел объекта) на основе данных, возвращаемых хостом. 
// 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. Отправка обновлений жизненного цикла и состояния (фронтенд)

Вы должны постоянно информировать организатора мероприятия о статусе оформления заказа, чтобы он мог обновить свой пользовательский интерфейс или обработать ошибки.

  • Действие : Отправлять уведомления (сообщения без идентификатора) при изменении состояния:
    • ec.start : Когда страница оформления заказа полностью видна.
    • ec.line_items.change : Если обновляется содержимое корзины или итоговая сумма.
    • ec.buyer.change : Если данные покупателя обновляются.
    • ec.complete : Когда заказ успешно оформлен.
    • ec.error : Если произошла критическая ошибка.

7. Обеспечьте безопасность (сервер/заголовки)

Вы должны убедиться, что ваша форма оформления заказа не может быть встроена злоумышленниками.

  • Действие : Внедрить заголовки политики безопасности контента (CSP).
  • Требование : Установите frame-ancestors <host_origin>; чтобы разрешить встраивание только доверенными хостами.
  • Навигация : Заблокируйте логику, которая перенаправляет пользователя с этапа оформления заказа (например, удалите ссылки «Продолжить покупки», ведущие на главную страницу). Исключения допускаются для верификации 3DS или перенаправлений на платежи сторонних сервисов.