Analizowanie wyników agenta UCP (alfa)

Interfejs Merchant Reports API umożliwia automatyczne pobieranie wskaźników skuteczności płatności i konwersji w ramach 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 UCP w Merchant Center, 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 „Kup” na poziomie produktu (offer_id) podzielone według daty i kraju klienta.

Zanim zaczniesz

Zanim zaczniesz wysyłać zapytania do widoków skuteczności UCP, upewnij się, że spełniasz te wymagania:

  • Użyj punktu końcowego v1alpha: wysyłaj zapytania MCQL do metody v1alpha accounts.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 i ucp_agentic_product_performance_view obsł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 date w klauzuli WHERE każ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 dotyczące cen: te dane zwracają obiekt Price zawierający zarówno wartość amount_micros, jak i currency_code:

    • purchase_value
    • average_order_value
    • average_purchase_product_value
    • average_cart_value
    • average_cart_product_value

  • Dane niezwiązane z ceną: te dane nie mają powiązanej waluty:

    • buy_button_clicks
    • accounts_linked
    • account_linking_attempts
    • account_linking_rate
    • purchase_count
    • cancellations
    • average_purchase_product_count
    • cart_transfers
    • average_cart_product_count
  1. 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.
  2. Dane dotyczące wartości zakupów i koszyka (według waluty): wybierz dane Price wraz 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żnie 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_attempts,
  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",
        "accountLinkingAttempts": "125",
        "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 zagregować 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 wybierzesz account_id, odpowiedź będzie zawierać dane zagregowane ze wszystkich subkont należących do konta zaawansowanego.
  • Wybierz account_id (z podziałem na subkonta): gdy wybierzesz account_id, odpowiedź będzie zawierać statystyki podzielone według account_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 zebrane 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_attempts,
  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",
        "accountLinkingAttempts": "200",
        "accountLinkingRate": 0.7,
        "purchaseCount": "110",
        "cancellations": "5"
      }
    }
  ]
}

pobieranie danych z podziałem na subkonta;

Aby podczas wysyłania zapytania do konta zaawansowanego podzielić wyniki według subkont, dodaj account_id we fragmencie kodu SELECT:

SELECT
  date,
  account_id,
  customer_country_code,
  buy_button_clicks,
  accounts_linked,
  account_linking_attempts,
  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",
        "accountLinkingAttempts": "125",
        "accountLinkingRate": 0.68,
        "purchaseCount": "64",
        "cancellations": "3"
      }
    },
    {
      "ucpAgenticPerformanceView": {
        "date": {
          "year": 2026,
          "month": 9,
          "day": 20
        },
        "accountId": "987654321",
        "customerCountryCode": "US",
        "buyButtonClicks": "310",
        "accountsLinked": "55",
        "accountLinkingAttempts": "100",
        "accountLinkingRate": 0.55,
        "purchaseCount": "46",
        "cancellations": "2"
      }
    }
  ]
}
Wstecz
Analyze YouTube Affiliate Performance (Alpha)
Dalej
Use Merchant Center Query Language