Analiza el rendimiento de los agentes de UCP (alfa)

Experimental: Esta función está en versión alfa (experimental) y está sujeta a cambios.

La API de Merchant Reports te permite recuperar de forma programática las métricas de rendimiento de la confirmación de compra y las conversiones del Protocolo de comercio universal (UCP) en las plataformas de Google, incluido el Modo IA en la Búsqueda y Gemini. Estos informes proporcionan las mismas estadísticas de rendimiento disponibles en el panel de análisis de UCP de Merchant Center, lo que te ayuda a supervisar los embudos de conversión, los pedidos completados, las transferencias de carritos y la participación a nivel del producto.

La sub-API de Reporting proporciona dos vistas para analizar el rendimiento de las UCP:

• UcpAgenticPerformanceView (ucp_agentic_performance_view): Proporciona métricas del embudo de conversiones, los pedidos, las cancelaciones y las transferencias de carritos a nivel de la cuenta segmentadas por fecha y país del cliente.
• UcpAgenticProductPerformanceView (ucp_agentic_product_performance_view): Proporciona métricas de clics en el botón de compra (offer_id) a nivel del producto, segmentadas por fecha y país del cliente.

Antes de comenzar

Antes de consultar las vistas de rendimiento del UCP, asegúrate de cumplir con los siguientes requisitos:

• Usa el extremo v1alpha: Envía tus consultas de MCQL al método accounts.reports.search de v1alpha. Para obtener detalles sobre la ejecución de solicitudes de informes, consulta la sección Comienza a usar la API de Merchant Reports.
• Solo para cuentas hoja: Tanto ucp_agentic_performance_view como ucp_agentic_product_performance_view solo están disponibles para los tipos de cuentas hoja (cuentas independientes y subcuentas individuales). El servicio de informes no admite cuentas avanzadas (cuentas de varios clientes). Para recuperar el rendimiento de los UCP en una cuenta avanzada, consulta cada cuenta secundaria de forma individual.
• Filtro de fecha obligatorio: Debes especificar una condición en date en la cláusula WHERE de cada consulta para ambas vistas.

Analiza el rendimiento de los UCP a nivel de la cuenta

Usa ucp_agentic_performance_view para hacer un seguimiento de tu embudo de conversión general de UCP, desde los clics en el botón de compra y la vinculación de la cuenta hasta las compras completadas y las transferencias de carrito.

Métricas de precios y monedas

ucp_agentic_performance_view maneja las métricas de moneda y Price de la misma manera que los informes de rendimiento:

• Métricas de Price: Las siguientes métricas devuelven un objeto Price que contiene un valor de amount_micros y un currency_code:
  • purchase_value
  • average_order_value
  • average_purchase_product_value
  • average_cart_value
  • average_cart_product_value
• Métricas que no son de precio: Las siguientes métricas no tienen una moneda asociada:
  • buy_button_clicks
  • accounts_linked
  • account_linking_rate
  • purchase_count
  • cancellations
  • average_purchase_product_count
  • cart_transfers
  • average_cart_product_count

Importante: Si incluyes métricas de embudo o de recuento (como buy_button_clicks) en la misma consulta que las métricas de valor de Price, las filas devueltas se separarán por moneda. Dado que las métricas como buy_button_clicks no tienen una moneda asociada por sí solas, combinarlas con las métricas de Price puede dividir u omitir filas sin valores de compra. Para evitar esto y obtener totales precisos, ejecuta dos consultas separadas:

1. Métricas generales del embudo y de recuento (independientes de la moneda): Selecciona solo las métricas que no sean de precios para obtener recuentos agregados independientes de la moneda.
2. Métricas de valor de compra y de carrito (por moneda): Selecciona las métricas de Price junto con sus respectivos recuentos de pedidos y carritos para analizar los ingresos y el valor por moneda.

Consulta 1: Recupera las métricas generales del embudo (independientes de la moneda)

Usa la siguiente consulta para recuperar el embudo de conversiones general, el recuento de pedidos y las métricas de transferencia del carrito independientemente de la moneda (sin incluir las métricas de valor de 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'

Nota: Dado que average_cart_value es una métrica de Price con un currency_code asociado, omítela de la consulta general del embudo y, en su lugar, inclúyela en la consulta del valor de la compra y del carrito.

La respuesta devuelve métricas agregadas del embudo para cada país 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
      }
    }
  ]
}

Consulta 2: Recupera las métricas de valor de compra y del carrito (por moneda)

Usa la siguiente consulta para recuperar los valores de compra, los valores promedio de los pedidos y los valores de transferencia del carrito segmentados por moneda:

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 respuesta devuelve una fila independiente para cada moneda presente en las métricas de valor de la compra o del carrito:

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

Analiza el rendimiento de la UCP a nivel del producto

Usa ucp_agentic_product_performance_view para ver qué productos individuales reciben clics en el botón de compra directamente desde las plataformas de Google.

Recupera los clics en el botón de compra por producto

Usa la siguiente consulta para recuperar los clics en el botón de compra a nivel del producto para una fecha 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'

También puedes omitir date de la cláusula SELECT para agregar los clics en un intervalo de fechas con 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 respuesta devuelve los clics agregados en el botón de compra para cada oferta coincidente:

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