Analizzare il rendimento dell'agente UCP (alpha)

L'API Merchant Reports consente di recuperare in modo programmatico le metriche sul rendimento delle conversioni e di checkout dell'Universal Commerce Protocol (UCP) sulle piattaforme Google, tra cui AI Mode nella Ricerca e Gemini. Questi report forniscono gli stessi approfondimenti sul rendimento disponibili nella dashboard di analisi dell'UCP di Merchant Center, aiutandoti a monitorare i funnel di conversione, gli ordini completati, i trasferimenti del carrello e il coinvolgimento a livello di prodotto.

La sotto-API Reporting fornisce due visualizzazioni per analizzare il rendimento di UCP:

  • UcpAgenticPerformanceView (ucp_agentic_performance_view): fornisce metriche sul funnel di conversione, sull'ordine, sull'annullamento e sul trasferimento del carrello a livello di account segmentate per data e paese del cliente.
  • UcpAgenticProductPerformanceView (ucp_agentic_product_performance_view): fornisce metriche sui clic sul pulsante Acquista a livello di prodotto (offer_id) segmentate per data e paese del cliente.

Prima di iniziare

Prima di eseguire query sulle visualizzazioni del rendimento UCP, assicurati di soddisfare i seguenti requisiti:

  • Utilizza l'endpoint v1alpha: invia le query MCQL al metodo v1alpha accounts.reports.search. Per informazioni dettagliate sull'esecuzione delle richieste di report, consulta la sezione Guida introduttiva all'API Merchant Reports.
  • Solo account foglia: sia ucp_agentic_performance_view che ucp_agentic_product_performance_view sono disponibili solo per i tipi di account foglia (account autonomi e subaccount individuali). Il servizio di reporting non supporta gli account avanzati (account multi-cliente). Per recuperare il rendimento UCP in un account avanzato, esegui query su ogni subaccount singolarmente.
  • Filtro della data obbligatorio: devi specificare una condizione per date nella clausola WHERE di ogni query per entrambe le visualizzazioni.

Analizzare il rendimento della protezione dei contenuti degli utenti a livello di account

Utilizza ucp_agentic_performance_view per monitorare il funnel di conversione UCP complessivo, dai clic sul pulsante Acquista e dal collegamento dell'account agli acquisti completati e ai trasferimenti del carrello.

Metriche relative a valuta e prezzo

ucp_agentic_performance_view gestisce la valuta e le metriche Price nello stesso modo dei report sul rendimento:

  • Metriche Price: le seguenti metriche restituiscono un oggetto Price contenente sia un valore amount_micros sia un valore currency_code:
    • purchase_value
    • average_order_value
    • average_purchase_product_value
    • average_cart_value
    • average_cart_product_value
  • Metriche non relative al prezzo: le seguenti metriche non hanno una valuta associata:
    • buy_button_clicks
    • accounts_linked
    • account_linking_rate
    • purchase_count
    • cancellations
    • average_purchase_product_count
    • cart_transfers
    • average_cart_product_count
  1. Metriche complessive della canalizzazione e di conteggio (indipendenti dalla valuta): seleziona solo le metriche non relative al prezzo per ottenere conteggi aggregati indipendenti dalla valuta.
  2. Metriche relative al valore di acquisto e del carrello (per valuta): seleziona le metriche Price insieme ai conteggi degli ordini e dei carrelli corrispondenti per analizzare le entrate e il valore per valuta.

Query 1: recupera le metriche complessive della canalizzazione (indipendenti dalla valuta)

Utilizza la seguente query per recuperare la canalizzazione delle conversioni complessiva, il conteggio degli ordini e le metriche di trasferimento del carrello indipendentemente dalla valuta (senza includere le metriche del valore Price):

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'

La risposta restituisce le metriche aggregate della canalizzazione per ogni paese del cliente:

{
  "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
      }
    }
  ]
}

Query 2: recupera le metriche relative al valore di acquisto e del carrello (per valuta)

Utilizza la seguente query per recuperare i valori di acquisto, i valori medi degli ordini e i valori di trasferimento del carrello segmentati per valuta:

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

La risposta restituisce una riga separata per ogni valuta presente nelle metriche relative al valore dell'acquisto o del carrello:

{
  "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"
        }
      }
    }
  ]
}

Analizzare il rendimento UCP a livello di prodotto

Utilizza ucp_agentic_product_performance_view per vedere quali singoli prodotti ricevono clic sul pulsante Acquista direttamente dalle piattaforme Google.

Recuperare i clic sul pulsante Acquista per prodotto

Utilizza la seguente query per recuperare i clic sul pulsante Acquista a livello di prodotto per una data specifica:

SELECT
  date,
  account_id,
  customer_country_code,
  offer_id,
  title,
  buy_button_clicks
FROM ucp_agentic_product_performance_view
WHERE date = '2026-09-20'

Puoi anche omettere date dalla clausola SELECT per aggregare i clic in un intervallo di date utilizzando 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

La risposta restituisce i clic aggregati sul pulsante Acquista per ogni offerta corrispondente:

{
  "results": [
    {
      "ucpAgenticProductPerformanceView": {
        "accountId": "123456789",
        "customerCountryCode": "US",
        "offerId": "sku-10042",
        "title": "Lightweight Running Shoes - Blue / Size 10",
        "buyButtonClicks": "38"
      }
    }
  ]
}
Indietro
Analyze YouTube Affiliate Performance (Alpha)
Avanti
Use Merchant Center Query Language