Analisar a performance do agente do UCP (Alfa)

Experimental: este recurso está em fase Alfa (experimental) e sujeito a mudanças.

A API Merchant Reports permite recuperar de forma programática métricas de performance de conversão e finalização da compra do Protocolo de Comércio Universal (UCP) em todas as plataformas do Google, incluindo o Modo IA na Pesquisa e no Gemini. Esses relatórios oferecem os mesmos insights de performance disponíveis no painel de análise do UCP do Merchant Center, ajudando você a monitorar funis de conversão, pedidos concluídos, transferências de carrinho e engajamento no nível do produto.

A sub-API Reporting oferece duas visualizações para analisar a performance da UCP:

• UcpAgenticPerformanceView (ucp_agentic_performance_view): fornece métricas de funil de conversão, pedido, cancelamento e transferência de carrinho no nível da conta segmentadas por data e país do cliente.
• UcpAgenticProductPerformanceView (ucp_agentic_product_performance_view): fornece métricas de cliques no botão (offer_id) "Comprar" no nível do produto segmentadas por data e país do cliente.

Antes de começar

Antes de consultar as visualizações de performance da UCP, verifique se você atende aos seguintes requisitos:

• Use o endpoint v1alpha: envie suas consultas MCQL para o método accounts.reports.search do v1alpha. Para detalhes sobre a execução de solicitações de relatórios, consulte o Guia de início rápido da API Merchant Reports.
• Somente contas finais: ucp_agentic_performance_view e ucp_agentic_product_performance_view estão disponíveis apenas para tipos de contas finais (contas independentes e subcontas individuais). O serviço de relatórios não é compatível com contas avançadas (contas de múltiplos clientes). Para recuperar a performance da UCP em uma conta avançada, consulte cada subconta individualmente.
• Filtro de data obrigatório: especifique uma condição em date na cláusula WHERE de todas as consultas para as duas visualizações.

Analisar a performance da UCP no nível da conta

Use ucp_agentic_performance_view para acompanhar seu funil de conversão geral da UCP, desde cliques no botão de compra e vinculação de contas até compras concluídas e transferências de carrinho.

Métricas de moeda e preço

ucp_agentic_performance_view processa moedas e métricas de Price da mesma forma que os relatórios de performance:

• Métricas de Price: as métricas a seguir retornam um objeto Price que contém um valor amount_micros e um currency_code:
  • purchase_value
  • average_order_value
  • average_purchase_product_value
  • average_cart_value
  • average_cart_product_value
• Métricas sem preço: as métricas a seguir não têm uma moeda associada:
  • buy_button_clicks
  • accounts_linked
  • account_linking_rate
  • purchase_count
  • cancellations
  • average_purchase_product_count
  • cart_transfers
  • average_cart_product_count

Importante: incluir métricas de funil ou contagem (como buy_button_clicks) na mesma consulta que as métricas de valor Price separa as linhas retornadas por moeda. Como métricas como buy_button_clicks não têm uma moeda associada por si só, combiná-las com métricas de Price pode dividir ou omitir linhas sem valores de compra. Para evitar isso e receber totais precisos, execute duas consultas separadas:

1. Métricas gerais de funil e contagem (independentes da moeda): selecione apenas métricas não relacionadas a preços para receber contagens agregadas independentes da moeda.
2. Métricas de valor de compra e carrinho (por moeda): selecione as métricas Price junto com as contagens de pedidos e carrinhos correspondentes para analisar a receita e o valor por moeda.

Consulta 1: recuperar métricas gerais do funil (independente da moeda)

Use a consulta a seguir para extrair o funil de conversão geral, a contagem de pedidos e as métricas de transferência de carrinho, independentemente da moeda (sem métricas de valor Price incluídas):

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'

Observação: como average_cart_value é uma métrica de Price com um currency_code associado, omita-a da consulta geral do funil e inclua-a na consulta de valor de compra e carrinho.

A resposta retorna métricas agregadas do funil para cada país do 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
      }
    }
  ]
}

Consulta 2: extrair métricas de valor de compra e carrinho (por moeda)

Use a consulta a seguir para extrair valores de compra, valores médios de pedidos e valores de transferência de carrinho segmentados por moeda:

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

A resposta retorna uma linha separada para cada moeda presente nas métricas de valor da compra ou do carrinho:

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

Analisar a performance da UCP no nível do produto

Use ucp_agentic_product_performance_view para ver quais produtos individuais recebem cliques no botão de compra diretamente das plataformas do Google.

Recuperar cliques no botão "Comprar" por produto

Use a consulta a seguir para recuperar cliques no botão "Comprar" no nível do produto em uma data específica:

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

Também é possível omitir date da cláusula SELECT para agregar cliques em um intervalo de datas usando 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

A resposta retorna os cliques agregados no botão "Comprar" para cada oferta correspondente:

{
  "results": [
    {
      "ucpAgenticProductPerformanceView": {
        "accountId": "123456789",
        "customerCountryCode": "US",
        "offerId": "sku-10042",
        "title": "Lightweight Running Shoes - Blue / Size 10",
        "buyButtonClicks": "38"
      }
    }
  ]
}