Pierwsze kroki z Universal Commerce Protocol (UCP) w Google

Pierwsze kroki z Universal Commerce Protocol (UCP) w Google — przewodnik krok po kroku (2026)

UCP to otwarty standard, który pozwala uruchomić zakup „w rozmowie” w powierzchniach Google opartych o GenAI (m.in. AI Mode w Search oraz Gemini) — od odkrycia produktu, przez checkout, aż po aktualizacje po zakupie. Integrując UCP, nadal Ty jesteś Merchant of Record (sprzedawcą), zachowujesz relację z klientem i logikę biznesową.

0) Zanim zaczniesz: dwa równoległe tory wdrożenia

W praktyce wdrożenie UCP w Google ma zawsze dwa tory, które możesz prowadzić równolegle:

Merchant Center (dane + kwalifikacja ofert) → żeby Google mogło w ogóle „widzieć” Twoje produkty i oznaczyć je jako gotowe do natywnego zakupu.
Integracja techniczna UCP (profil + checkout + webhooks) → żeby Google mogło tworzyć sesje checkoutu, finalizować płatność i odbierać statusy po zakupie.

1) Merchant Center: przygotuj konto i feed pod „native commerce”

Krok 1.1 — dopnij bazę: dostawa, zwroty, dane produktów

Google traktuje Merchant Center jako „źródło prawdy” do odkrywania oferty, więc zanim wejdziesz w UCP zadbaj o kompletność ustawień (shipping/returns, dane firmy, feed).

Krok 1.2 — upewnij się, że ID z feedu = ID oczekiwane przez Checkout API

UCP mocno opiera się na spójności identyfikatorów. Jeśli id w feedzie nie pasuje do tego, czego używa Twoje API checkoutu, Google przewiduje mapowanie przez atrybut merchant_item_id.

Krok 1.3 — dodaj atrybuty pod kwalifikację „native checkout”

W przewodniku Merchant Center są opisane sposoby dodania atrybutów do produktów (np. przez supplemental feed albo przez API) oraz przykłady struktur (np. native_commerce, consumer_notice, merchant item id).

Praktyczna wskazówka ACO (Agentic Commerce Optimization):
Traktuj te atrybuty jak „sygnały gotowości” dla agentów: jeśli dane są niespójne lub niekompletne, agent (i Google) będzie częściej przerywał ścieżkę zakupową.

2) Formalny start w Google: „interest form” + akceptacja

Krok 2.1 — dołącz do listy oczekujących / procesu wdrożenia

Zanim integracja pojawi się w AI Mode / Gemini, musi zostać zatwierdzona przez Google — w dokumentacji jest to wprost opisane jako etap po przygotowaniu Merchant Center.

3) Opublikuj Business Profile: /.well-known/ucp

To jest kluczowy element „negocjacji możliwości” (capabilities) między Twoim serwerem a Google.

Krok 3.1 — wystaw manifest UCP pod:

/.well-known/ucp

W profilu deklarujesz m.in.:

wersję protokołu,
jakie services wspierasz (np. shopping),
bindingi transportu (REST / MCP / A2A),
listę capabilities (np. checkout, fulfillment, discount),
konfigurację płatności i signing_keys do weryfikacji podpisów.

ACO tip:
To jest Twój „agentic surface contract”. Im czytelniej i stabilniej ogłaszasz capabilities, tym mniej wyjątków i „fallbacków” w trakcie zakupu.

4) Wybierz ścieżkę checkoutu

Google opisuje dwie ścieżki:

Ścieżka A (zalecana): Native checkout

W native checkout Google wyświetla własny UI do wrażliwych danych płatności i dostawy (deterministycznie), a Twoje API odpowiada za sesję i wyliczenia (podatki/dostawa/total).

Krok 4.1 — zaimplementuj podstawowe endpointy REST checkoutu

W dokumentacji jako fundament pojawiają się operacje tworzenia/odczytu/aktualizacji oraz finalizacji sesji (plus opcjonalne anulowanie).

Minimalny zestaw, który praktycznie musisz mieć „od początku”:

POST /checkout-sessions (utwórz sesję)
PUT /checkout-sessions/{id} (aktualizuj sesję: adres, dostawa, instrument)
POST /checkout-sessions/{id}/complete (finalizacja i utworzenie zamówienia)

Dodatkowo (silnie zalecane dla jakości obsługi):

GET /checkout-sessions/{id} (pobierz sesję)
POST /checkout-sessions/{id}/cancel (anuluj sesję)

Krok 4.2 — dopilnuj „twardych” zasad agentowego checkoutu

Z perspektywy ACO liczą się 3 rzeczy:

Idempotency – Google używa nagłówków typu idempotency-key / request-id w przykładach; Twoje API musi reagować stabilnie na ponowienia (retry).
Dynamiczne przeliczenia – po zmianie adresu i metody dostawy masz ponownie policzyć podatki i shipping oraz zwrócić pełen obiekt sesji.
Deterministyczna finalizacja – płatność jest domykana w UI Google; agent nie powinien „kombinować” w tej fazie.

Krok 4.3 — obsłuż płatności przez payment handler

W odpowiedzi na tworzenie sesji zwracasz m.in. konfigurację payment.handlers (np. Google Pay handler) wraz z parametrami obsługiwanymi przez PSP/tokenizację.

Ścieżka B (opcjonalna): Embedded checkout (iframe/webview)

Ta ścieżka jest dla firm z bardzo niestandardowym checkoutem (konfiguratory, rozbudowane koszyki, specyficzne kroki), gdzie native checkout może być zbyt ograniczający.

Krok 4B.1 — zadeklaruj capability embedded checkout

Dodajesz dev.ucp.shopping.embedded_checkout w capabilities i podajesz spec/schema, a opcjonalnie wymagasz auth.

Krok 4B.2 — zbuduj komunikację host ↔ iframe (JSON-RPC + postMessage)

Google opisuje komunikację jako JSON-RPC 2.0 (postMessage), z obowiązkową walidacją origin.

Krok 4B.3 — zabezpiecz osadzanie (CSP frame-ancestors)

Musisz wdrożyć CSP tak, aby tylko zaufane hosty mogły osadzać checkout (ochrona przed złośliwym iframe).

5) Wybierz tryb identyfikacji użytkownika

Masz dwa warianty:

Wariant domyślny: guest checkout

Nie implementujesz linkowania kont – ale wtedy musisz wspierać checkout bez logowania.

Wariant zaawansowany: Identity Linking (OAuth 2.0)

Jeśli chcesz lojalność, personalizację, „member pricing”, historię zamówień itd. — wdrażasz OAuth 2.0 Authorization Code Flow + plik discovery.

Krok 5.1 — wdroż OAuth 2.0 Authorization Code + client_secret_basic

To jest wymagane wprost w core requirements.

Krok 5.2 — opublikuj metadata pod:

/.well-known/oauth-authorization-server

Krok 5.3 — obsłuż scope UCP dla checkout lifecycle

Dokumentacja wskazuje scope ucp:scopes:checkout_session.

Krok 5.4 — rozważ „Google Streamlined Linking”

To opcjonalna warstwa (JWT assertions), która może uprościć UX i zwiększyć konwersję, bo cały flow odbywa się w UI Google.

6) Po zakupie: webhooks i lifecycle zamówienia

UCP w Google nie kończy się na complete. Po utworzeniu zamówienia masz wypychać statusy do Google webhookami.

Krok 6.1 — wysyłaj event „Order Created” natychmiast po potwierdzeniu

endpoint: POST /webhooks/partners/{partner_id}/events/order
payload: pełna encja order (nie skrót).

Krok 6.2 — wysyłaj pełny order przy każdej zmianie (shipping/cancel)

Wymóg „full entity again” jest podkreślony wprost — nie wysyłasz patcha, tylko cały obiekt.

ACO tip:
To jest krytyczne dla „agentowej obsługi posprzedażowej”: jeśli Google ma spójne statusy, agent może odpowiadać użytkownikowi bez przerzucania go do supportu.

7) Checklista jakości (ACO) — żeby to realnie konwertowało

Stabilność i odporność

Idempotency dla create/update/complete (retry-safe).
Zawsze zwracaj pełny stan sesji po update.

Spójność danych

ID produktu spójne między feedem a checkout API (lub mapowanie).
Ceny/podatki/dostawa liczone „tu i teraz” po zmianie adresu.

Bezpieczeństwo i zaufanie

Profile + signing keys w business profile do weryfikacji podpisów.
Przy embedded checkout: CSP frame-ancestors tylko dla hostów zaufanych.

Post-purchase „agent ready”

Webhooki order lifecycle zawsze pełnym obiektem.

FAQ (krótkie, ale „agent-friendly”)

Czy UCP zabiera mi klienta?
W założeniu nie: UCP jest projektowany tak, abyś pozostawał Merchant of Record i zachował relację/dane, a standard ma redukować porzucanie koszyka w ścieżkach agentowych.

Gdzie to będzie działać?
Google wskazuje AI Mode w Search oraz Gemini (web), jako pierwsze powierzchnie zakupowe.

Co wybrać: native czy embedded?
Native — jeśli chcesz najszybciej wejść w agentowy zakup i korzystać z deterministycznego UI Google. Embedded — jeśli masz checkout wymagający niestandardowej logiki/UI, której native nie ogarnie.

Czy muszę wdrożyć logowanie?
Nie, ale wtedy musisz wspierać guest checkout. Jeśli chcesz benefity konta/lojalność — wdrażasz Identity Linking w OAuth 2.0.

Co po zakupie?
Musisz wypychać statusy zamówienia do Google webhookami (order created + kolejne update’y).