Analisar a performance do agente do UCP (Alfa)

A API Merchant Reports permite recuperar de forma programática as métricas de performance de finalização de compra e conversão do Protocolo de Comércio Universal (UCP, na sigla em inglês) 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 da 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 de compra no nível do produto (offer_id) segmentadas por data e país do cliente.

Antes de começar

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

  • Use o endpoint v1alpha: envie suas consultas MCQL para o método v1alpha accounts.reports.search. Para saber como executar solicitações de relatórios, consulte o artigo Começar a usar a API Merchant Reports.
  • Tipos de conta compatíveis: o ucp_agentic_performance_view e o ucp_agentic_product_performance_view são compatíveis com contas folha (contas independentes e subcontas individuais), além de contas avançadas (contas de múltiplos clientes ou contas de agregador). Para detalhes e exemplos, consulte Consultar no nível da conta avançada.
  • Filtro de data obrigatório: é preciso especificar uma condição em date na cláusula WHERE de cada consulta para as duas visualizações.

Analisar a performance da UCP no nível da conta

Use ucp_agentic_performance_view para acompanhar o 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

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

  • Métricas 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 não relacionadas a 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
  1. Métricas gerais de funil e contagem (independentes de moeda): selecione apenas métricas que não sejam de preço para receber contagens agregadas independentes de moeda.
  2. Métricas de valor de compra e do carrinho (por moeda): selecione as métricas de Price 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 (independentes de moeda)

Use a consulta a seguir para recuperar as métricas gerais de funil de conversão, contagem de pedidos e 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'

A resposta retorna métricas de funil agregadas 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: recuperar métricas de compra e valor do carrinho (por moeda)

Use a consulta a seguir para recuperar valores de compra, ticket médio 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 do 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 os cliques no botão de compra 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 período 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 de compra para cada oferta correspondente:

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

Consultar no nível da conta avançada

É possível consultar ucp_agentic_performance_view e ucp_agentic_product_performance_view especificando uma conta avançada (conta de múltiplos clientes ou conta de agregador) no parâmetro parent da solicitação accounts.reports.search, como accounts/{advanced_account_id}.

Em ambas as visualizações, a coluna account_id sempre contém o ID da conta folha do Merchant Center (o ID da subconta individual ao consultar uma conta avançada ou o ID da conta independente ao consultar uma conta independente). Ao consultar no nível da conta avançada, a inclusão de account_id na cláusula SELECT determina como as métricas são agrupadas:

  • Omitir account_id (agregado no nível da conta avançada): quando account_id não está selecionado, a resposta agrega métricas de todas as subcontas que pertencem à conta avançada.
  • Selecione account_id (detalhado por subconta): quando account_id é selecionado, a resposta segmenta as estatísticas por account_id de folha, retornando linhas separadas para cada subconta na conta avançada.

Recuperar métricas agregadas em uma conta avançada

Para recuperar as métricas totais do funil de UCP agregadas no nível da conta avançada, envie a solicitação usando o ID da conta avançada como o recurso parent e omita account_id da cláusula 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'

A resposta retorna uma única linha agregada por data e país do cliente em todas as subcontas da conta avançada:

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

Recuperar métricas detalhadas por subconta

Para detalhar os resultados por subconta ao consultar uma conta avançada, inclua account_id na cláusula 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'

Como account_id sempre contém o ID da conta folha, a resposta retorna uma linha separada para cada subconta na conta avançada:

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