Analyser les performances de l'agent UCP (alpha)

L'API Merchant Reports vous permet de récupérer de manière programmatique les métriques de performances de paiement et de conversion de l'Universal Commerce Protocol (UCP) sur les surfaces Google, y compris le Mode IA dans la recherche et Gemini. Ces rapports fournissent les mêmes insights sur les performances que ceux disponibles dans le tableau de bord d'analyse UCP de Merchant Center. Ils vous aident à surveiller les entonnoirs de conversion, les commandes finalisées, les transferts de panier et l'engagement au niveau du produit.

La sous-API Reporting fournit deux vues pour analyser les performances de l'UCP :

  • UcpAgenticPerformanceView (ucp_agentic_performance_view) : fournit des métriques sur l'entonnoir de conversion, les commandes, les annulations et les transferts de panier au niveau du compte, segmentées par date et par pays du client.
  • UcpAgenticProductPerformanceView (ucp_agentic_product_performance_view) : fournit des métriques sur les clics sur le bouton d'achat au niveau du produit (offer_id) segmentées par date et par pays du client.

Avant de commencer

Avant d'interroger les vues de performances UCP, assurez-vous de remplir les conditions suivantes :

  • Utilisez le point de terminaison v1alpha : envoyez vos requêtes MCQL à la méthode v1alpha accounts.reports.search. Pour en savoir plus sur l'exécution des demandes de rapport, consultez Premiers pas avec l'API Merchant Reports.
  • Types de comptes compatibles : ucp_agentic_performance_view et ucp_agentic_product_performance_view sont compatibles avec les comptes feuilles (comptes individuels et sous-comptes individuels) ainsi qu'avec les comptes avancés (multicomptes ou comptes d'agrégateur). Pour en savoir plus et voir des exemples, consultez Interroger au niveau du compte avancé.
  • Filtre de date obligatoire : vous devez spécifier une condition sur date dans la clause WHERE de chaque requête pour les deux vues.

Analyser les performances des promotions marchandes au niveau du compte

Utilisez ucp_agentic_performance_view pour suivre l'ensemble de votre entonnoir de conversion UCP, des clics sur le bouton d'achat et de l'association de comptes aux achats finalisés et aux transferts de paniers.

Métriques de devises et de prix

ucp_agentic_performance_view gère les métriques de devise et de Price de la même manière que les rapports sur les performances :

  • Métriques Price : les métriques suivantes renvoient un objet Price contenant à la fois une valeur amount_micros et une valeur currency_code :
    • purchase_value
    • average_order_value
    • average_purchase_product_value
    • average_cart_value
    • average_cart_product_value
  • Métriques non liées au prix : les métriques suivantes ne sont pas associées à une devise :
    • buy_button_clicks
    • accounts_linked
    • account_linking_rate
    • purchase_count
    • cancellations
    • average_purchase_product_count
    • cart_transfers
    • average_cart_product_count
  1. Métriques globales de l'entonnoir et du nombre (indépendantes de la devise) : sélectionnez uniquement des métriques non liées au prix pour obtenir des nombres agrégés indépendants de la devise.
  2. Métriques de valeur d'achat et de panier (par devise) : sélectionnez les métriques Price ainsi que le nombre de commandes et de paniers correspondants pour analyser les revenus et la valeur par devise.

Requête 1 : Récupérer les métriques globales de l'entonnoir (indépendamment de la devise)

Utilisez la requête suivante pour récupérer les métriques globales de l'entonnoir de conversion, du nombre de commandes et du transfert de panier, indépendamment de la devise (sans inclure les métriques de valeur 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 réponse renvoie des métriques d'entonnoir agrégées pour chaque pays client :

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

Requête 2 : Récupérer les métriques sur les achats et la valeur du panier (par devise)

Utilisez la requête suivante pour récupérer les valeurs des achats, les valeurs moyennes de la commande et les valeurs de transfert de panier segmentées par devise :

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 réponse renvoie une ligne distincte pour chaque devise présente dans les métriques de valeur d'achat ou de panier :

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

Analyser les performances de l'UCP au niveau du produit

Utilisez ucp_agentic_product_performance_view pour voir quels produits individuels enregistrent des clics sur le bouton d'achat directement depuis les surfaces Google.

Récupérer les clics sur le bouton "Acheter" par produit

Utilisez la requête suivante pour récupérer les clics sur le bouton d'achat au niveau du produit pour une date spécifique :

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

Vous pouvez également omettre date de la clause SELECT pour agréger les clics sur une plage de dates à l'aide de 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 réponse renvoie le nombre cumulé de clics sur le bouton d'achat pour chaque offre correspondante :

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

Requête au niveau du compte avancé

Vous pouvez interroger à la fois ucp_agentic_performance_view et ucp_agentic_product_performance_view en spécifiant un compte avancé (compte multicompte ou compte d'agrégateur) dans le paramètre parent de la requête accounts.reports.search, par exemple accounts/{advanced_account_id}.

Dans les deux vues, la colonne account_id contient toujours l'ID de compte Merchant Center feuille (l'ID du sous-compte individuel lors de l'interrogation d'un compte avancé, ou l'ID du compte individuel lors de l'interrogation d'un compte individuel). Lorsque vous interrogez au niveau du compte avancé, l'inclusion ou non de account_id dans la clause SELECT détermine la façon dont les métriques sont regroupées :

  • Omettre account_id (agrégé au niveau du compte avancé) : lorsque account_id n'est pas sélectionné, la réponse agrège les métriques de tous les sous-comptes appartenant au compte avancé.
  • Sélectionnez account_id (réparti par sous-compte) : lorsque account_id est sélectionné, la réponse segmente les statistiques par feuille account_id, en renvoyant des lignes distinctes pour chaque sous-compte du compte avancé.

Récupérer des métriques agrégées dans un compte avancé

Pour récupérer les métriques de l'entonnoir de conversion total de la plate-forme de paiement unifiée agrégées au niveau du compte avancé, envoyez la requête en utilisant l'ID de votre compte avancé comme ressource parent et omettez account_id de la clause 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 réponse renvoie une seule ligne agrégée par date et par pays du client pour tous les sous-comptes du compte avancé :

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

Récupérer les métriques par sous-compte

Pour ventiler les résultats par sous-compte lors de l'interrogation d'un compte avancé, incluez account_id dans la clause 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'

Étant donné que account_id contient toujours l'ID du compte feuille, la réponse renvoie une ligne distincte pour chaque sous-compte du compte avancé :

{
  "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"
      }
    }
  ]
}
Précédent
Analyze YouTube Affiliate Performance (Alpha)
Suivant
Use Merchant Center Query Language