Interfejs Merchant Reports API umożliwia automatyczne pobieranie wskaźników skuteczności płatności i konwersji w ramach protokołu Universal Commerce Protocol (UCP) na platformach Google, w tym w Trybie AI w wyszukiwarce i Gemini. Te raporty zawierają te same statystyki skuteczności, które są dostępne w panelu statystyk platformy handlowej Merchant Center UCP, co pomaga monitorować ścieżki konwersji, zrealizowane zamówienia, przeniesienia koszyka i zaangażowanie na poziomie produktu.
Podrzędny interfejs API raportowania udostępnia 2 widoki do analizowania skuteczności UCP:
UcpAgenticPerformanceView(ucp_agentic_performance_view): zawiera dane o ścieżce konwersji, zamówieniach, anulowaniach i przeniesieniach koszyka na poziomie konta, podzielone według daty i kraju klienta.UcpAgenticProductPerformanceView(ucp_agentic_product_performance_view): zawiera dane o kliknięciach przycisku kupowania na poziomie produktu (offer_id) podzielone według daty i kraju klienta.
Zanim zaczniesz
Zanim wyślesz zapytanie do widoków skuteczności UCP, upewnij się, że spełniasz te wymagania:
- Użyj punktu końcowego
v1alpha: wysyłaj zapytania MCQL do metodyv1alphaaccounts.reports.search. Szczegółowe informacje o wykonywaniu żądań raportów znajdziesz w artykule Pierwsze kroki z interfejsem Merchant Reports API. - Obsługiwane rodzaje kont: zarówno
ucp_agentic_performance_view, jak iucp_agentic_product_performance_viewobsługują konta podrzędne (samodzielne konta i indywidualne subkonta) oraz konta zaawansowane (multikonta klientów lub konta agregatora). Szczegółowe informacje i przykłady znajdziesz w artykule Zapytanie na poziomie konta zaawansowanego. - Wymagany filtr daty: musisz określić warunek dla
datew klauzuliWHEREkażdego zapytania w przypadku obu widoków.
Analizowanie skuteczności UCP na poziomie konta
Używaj ucp_agentic_performance_view do śledzenia ogólnej ścieżki konwersji UCP, od kliknięć przycisku zakupu i połączenia konta po sfinalizowane zakupy i przeniesienia koszyka.
Dane o walucie i cenie
ucp_agentic_performance_view obsługuje walutę i dane Price w taki sam sposób jak raporty skuteczności:
- Dane
Price: te dane zwracają obiektPricezawierający zarówno wartośćamount_micros, jak icurrency_code:purchase_valueaverage_order_valueaverage_purchase_product_valueaverage_cart_valueaverage_cart_product_value
- Dane niezwiązane z ceną: te dane nie mają powiązanej waluty:
buy_button_clicksaccounts_linkedaccount_linking_ratepurchase_countcancellationsaverage_purchase_product_countcart_transfersaverage_cart_product_count
- Ogólne dane dotyczące ścieżki i liczby (niezależne od waluty): wybierz tylko dane niezwiązane z ceną, aby uzyskać zagregowane liczby niezależne od waluty.
- Dane dotyczące wartości zakupów i koszyka (według waluty): wybierz dane
Pricewraz z odpowiadającą im liczbą zamówień i koszyków, aby analizować przychody i wartość według waluty.
Zapytanie 1. Pobieranie ogólnych danych ścieżki (niezależnych od waluty)
Aby pobrać ogólne dane dotyczące ścieżki konwersji, liczby zamówień i przeniesienia koszyka niezależnie od waluty (bez danych o wartości Price), użyj tego zapytania:
SELECT
date,
account_id,
customer_country_code,
buy_button_clicks,
accounts_linked,
account_linking_rate,
purchase_count,
cancellations,
average_purchase_product_count,
cart_transfers,
average_cart_product_count
FROM ucp_agentic_performance_view
WHERE date = '2026-09-20'
Odpowiedź zwraca zagregowane dane ścieżki dla każdego kraju klienta:
{
"results": [
{
"ucpAgenticPerformanceView": {
"date": {
"year": 2026,
"month": 9,
"day": 20
},
"accountId": "123456789",
"customerCountryCode": "US",
"buyButtonClicks": "420",
"accountsLinked": "85",
"accountLinkingRate": 0.68,
"purchaseCount": "64",
"cancellations": "3",
"averagePurchaseProductCount": 1.75,
"cartTransfers": "52",
"averageCartProductCount": 2.1
}
}
]
}
Zapytanie 2. Pobieranie danych o wartości zakupów i koszyka (według waluty)
Aby pobrać wartości zakupów, średnie wartości zamówień i wartości przeniesienia koszyka podzielone według waluty, użyj tego zapytania:
SELECT
date,
account_id,
customer_country_code,
purchase_count,
purchase_value,
average_order_value,
average_purchase_product_count,
average_purchase_product_value,
average_cart_value,
average_cart_product_value
FROM ucp_agentic_performance_view
WHERE date = '2026-09-20' AND purchase_count > 0
Odpowiedź zwraca osobny wiersz dla każdej waluty występującej w danych o wartości zakupu lub koszyka:
{
"results": [
{
"ucpAgenticPerformanceView": {
"date": {
"year": 2026,
"month": 9,
"day": 20
},
"accountId": "123456789",
"customerCountryCode": "US",
"purchaseCount": "64",
"purchaseValue": {
"amountMicros": "5120000000",
"currencyCode": "USD"
},
"averageOrderValue": {
"amountMicros": "80000000",
"currencyCode": "USD"
},
"averagePurchaseProductCount": 1.75,
"averagePurchaseProductValue": {
"amountMicros": "45714285",
"currencyCode": "USD"
},
"cartTransfers": "52",
"averageCartValue": {
"amountMicros": "94500000",
"currencyCode": "USD"
},
"averageCartProductCount": 2.1,
"averageCartProductValue": {
"amountMicros": "45000000",
"currencyCode": "USD"
}
}
}
]
}
Analizowanie skuteczności UCP na poziomie produktu
Użyj ucp_agentic_product_performance_view, aby sprawdzić, które produkty uzyskują kliknięcia przycisku Kup bezpośrednio z platform Google.
Pobieranie liczby kliknięć przycisku Kup według produktu
Aby pobrać kliknięcia przycisku Kup na poziomie produktu w przypadku konkretnej daty, użyj tego zapytania:
SELECT
date,
account_id,
customer_country_code,
offer_id,
title,
buy_button_clicks
FROM ucp_agentic_product_performance_view
WHERE date = '2026-09-20'
Możesz też pominąć date w klauzuli SELECT, aby agregować kliknięcia w zakresie dat za pomocą BETWEEN:
SELECT
account_id,
customer_country_code,
offer_id,
title,
buy_button_clicks
FROM ucp_agentic_product_performance_view
WHERE date BETWEEN '2026-09-01' AND '2026-09-20'
ORDER BY buy_button_clicks DESC
Odpowiedź zwraca zagregowane kliknięcia przycisku kupowania dla każdej pasującej oferty:
{
"results": [
{
"ucpAgenticProductPerformanceView": {
"accountId": "123456789",
"customerCountryCode": "US",
"offerId": "sku-10042",
"title": "Lightweight Running Shoes - Blue / Size 10",
"buyButtonClicks": "38"
}
}
]
}
Zapytanie na poziomie konta zaawansowanego
Możesz wysyłać zapytania zarówno do ucp_agentic_performance_view, jak i do ucp_agentic_product_performance_view, podając konto zaawansowane (multikonto klientów lub konto pośrednika) w parametrze parent żądania accounts.reports.search, np. accounts/{advanced_account_id}.
W obu widokach kolumna account_id zawsze zawiera identyfikator konta Merchant Center leaf (identyfikator pojedynczego subkonta w przypadku zapytania dotyczącego konta zaawansowanego lub identyfikator samodzielnego konta w przypadku zapytania dotyczącego samodzielnego konta). Podczas wysyłania zapytania na poziomie konta zaawansowanego to, czy uwzględnisz account_id w klauzuli SELECT, określa sposób grupowania danych:
- Pomiń
account_id(zagregowane na poziomie konta zaawansowanego): jeśli nie wybierzeszaccount_id, odpowiedź będzie zawierać dane zagregowane ze wszystkich subkont należących do konta zaawansowanego. - Wybierz
account_id(z podziałem na subkonta): gdy wybierzeszaccount_id, odpowiedź będzie zawierać statystyki podzielone wedługaccount_id, zwracając osobne wiersze dla każdego subkonta na koncie zaawansowanym.
Pobieranie danych zbiorczych na koncie zaawansowanym
Aby pobrać łączne dane ścieżki UCP na poziomie konta zaawansowanego, wyślij żądanie, używając identyfikatora konta zaawansowanego jako zasobu parent i pomijając account_id w klauzuli SELECT:
SELECT
date,
customer_country_code,
buy_button_clicks,
accounts_linked,
account_linking_rate,
purchase_count,
cancellations
FROM ucp_agentic_performance_view
WHERE date = '2026-09-20'
Odpowiedź zwraca 1 zagregowany wiersz na datę i kraj klienta na wszystkich subkontach konta zaawansowanego:
{
"results": [
{
"ucpAgenticPerformanceView": {
"date": {
"year": 2026,
"month": 9,
"day": 20
},
"customerCountryCode": "US",
"buyButtonClicks": "730",
"accountsLinked": "140",
"accountLinkingRate": 0.65,
"purchaseCount": "110",
"cancellations": "5"
}
}
]
}
pobieranie danych z podziałem na subkonta;
Aby podzielić wyniki według subkonta podczas wysyłania zapytania do konta zaawansowanego, dodaj account_id w klauzuli SELECT:
SELECT
date,
account_id,
customer_country_code,
buy_button_clicks,
accounts_linked,
account_linking_rate,
purchase_count,
cancellations
FROM ucp_agentic_performance_view
WHERE date = '2026-09-20'
Ponieważ account_id zawsze zawiera identyfikator konta podrzędnego, odpowiedź zwraca osobny wiersz dla każdego subkonta na koncie zaawansowanym:
{
"results": [
{
"ucpAgenticPerformanceView": {
"date": {
"year": 2026,
"month": 9,
"day": 20
},
"accountId": "123456789",
"customerCountryCode": "US",
"buyButtonClicks": "420",
"accountsLinked": "85",
"accountLinkingRate": 0.68,
"purchaseCount": "64",
"cancellations": "3"
}
},
{
"ucpAgenticPerformanceView": {
"date": {
"year": 2026,
"month": 9,
"day": 20
},
"accountId": "987654321",
"customerCountryCode": "US",
"buyButtonClicks": "310",
"accountsLinked": "55",
"accountLinkingRate": 0.61,
"purchaseCount": "46",
"cancellations": "2"
}
}
]
}