Analizzare il rendimento dell'agente UCP (alpha)

L'API Merchant Reports ti consente di recuperare in modo programmatico le metriche sul rendimento delle conversioni e del pagamento dell'Universal Commerce Protocol (UCP) su tutte le piattaforme Google, tra cui AI Mode nella Ricerca e Gemini. Questi report forniscono gli stessi insight sul rendimento disponibili nella dashboard di analisi 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 sub-API Reporting fornisce due visualizzazioni per l'analisi del rendimento della piattaforma di contenuti utente:

  • UcpAgenticPerformanceView (ucp_agentic_performance_view): fornisce metriche a livello di account relative a funnel di conversione, ordini, annullamenti e trasferimenti del carrello, 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 viste sul rendimento della piattaforma di fatturazione unificata, assicurati di soddisfare i seguenti requisiti:

  • Utilizza l'endpoint v1alpha: invia le tue query MCQL al metodo accounts.reports.search v1alpha. Per maggiori dettagli sull'esecuzione delle richieste di report, consulta la sezione Inizia a utilizzare l'API Merchant Reports.
  • Tipi di account supportati: sia ucp_agentic_performance_view che ucp_agentic_product_performance_view supportano gli account secondari (account autonomi e singoli subaccount), nonché gli account avanzati (account multi-cliente o account aggregatore). Per dettagli ed esempi, consulta Esegui query a livello di account avanzato.
  • Filtro per data obbligatorio: devi specificare una condizione su date nella clausola WHERE di ogni query per entrambe le visualizzazioni.

Analizza il rendimento UCP 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: alle seguenti metriche non è associata una valuta:
    • buy_button_clicks
    • accounts_linked
    • account_linking_rate
    • purchase_count
    • cancellations
    • average_purchase_product_count
    • cart_transfers
    • average_cart_product_count
  1. Metriche relative alla canalizzazione complessiva e al conteggio (indipendenti dalla valuta): seleziona solo le metriche non relative ai prezzi 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 le metriche relative al funnel di conversione complessivo, al numero di ordini e al 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 di 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"
        }
      }
    }
  ]
}

Analizza il rendimento di 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"
      }
    }
  ]
}

Query a livello di account avanzato

Puoi eseguire query sia su ucp_agentic_performance_view che su ucp_agentic_product_performance_view specificando un account avanzato (account multi-cliente o account aggregatore) nel parametro parent della richiesta accounts.reports.search, ad esempio accounts/{advanced_account_id}.

In entrambe le visualizzazioni, la colonna account_id contiene sempre l'ID account Merchant Center foglia (l'ID subaccount individuale quando esegui query in un account avanzato o l'ID account autonomo quando esegui query in un account autonomo). Quando esegui una query a livello di account avanzato, l'inclusione di account_id nella clausola SELECT determina il modo in cui vengono raggruppate le metriche:

  • Ometti account_id (aggregato a livello di account avanzato): quando account_id non è selezionato, la risposta aggrega le metriche di tutti i subaccount appartenenti all'account avanzato.
  • Seleziona account_id (suddiviso per subaccount): quando è selezionato account_id, la risposta segmenta le statistiche per account_id foglia, restituendo righe separate per ogni subaccount nell'account avanzato.

Recuperare le metriche aggregate in un account avanzato

Per recuperare le metriche totali della canalizzazione UCP aggregate a livello di account avanzato, invia la richiesta utilizzando l'ID account avanzato come risorsa parent e ometti account_id dalla clausola 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'

La risposta restituisce una singola riga aggregata per data e paese del cliente in tutti i subaccount dell'account avanzato:

{
  "results": [
    {
      "ucpAgenticPerformanceView": {
        "date": {
          "year": 2026,
          "month": 9,
          "day": 20
        },
        "customerCountryCode": "US",
        "buyButtonClicks": "730",
        "accountsLinked": "140",
        "accountLinkingRate": 0.65,
        "purchaseCount": "110",
        "cancellations": "5"
      }
    }
  ]
}

Recupera le metriche suddivise per subaccount

Per suddividere i risultati per subaccount quando esegui una query su un account avanzato, includi account_id nella clausola 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'

Poiché account_id contiene sempre l'ID account foglia, la risposta restituisce una riga separata per ogni subaccount nell'account avanzato:

{
  "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"
      }
    }
  ]
}
Indietro
Analyze YouTube Affiliate Performance (Alpha)
Avanti
Use Merchant Center Query Language