UCP temsilci performansını analiz etme (alfa)

Merchant Reports API, Google Arama'da AI Modu ve Gemini dahil olmak üzere Google platformlarındaki Evrensel Ticaret Protokolü (UCP) ödeme ve dönüşüm performansı metriklerini programatik olarak almanıza olanak tanır. Bu raporlar, Merchant Center UCP analiz kontrol panelinde bulunan performans analizlerinin aynısını sunarak dönüşüm hunilerini, tamamlanan siparişleri, alışveriş sepeti aktarımlarını ve ürün düzeyinde etkileşimi izlemenize yardımcı olur.

Raporlama alt API'si, UCP performansını analiz etmek için iki görünüm sunar:

  • UcpAgenticPerformanceView (ucp_agentic_performance_view): Tarihe ve müşterinin ülkesine göre segmentlere ayrılmış hesap düzeyinde dönüşüm hunisi, sipariş, iptal ve alışveriş sepeti aktarma metrikleri sağlar.
  • UcpAgenticProductPerformanceView (ucp_agentic_product_performance_view): Tarihe ve müşterinin ülkesine göre segmentlere ayrılmış ürün düzeyinde (offer_id) satın alma düğmesi tıklama metrikleri sağlar.

Başlamadan önce

UCP performans görünümlerini sorgulamadan önce aşağıdaki şartları karşıladığınızdan emin olun:

  • v1alpha uç noktasını kullanın: MCQL sorgularınızı v1alpha accounts.reports.search yöntemine gönderin. Rapor isteklerini yürütme hakkında ayrıntılı bilgi için Merchant Reports API'yi kullanmaya başlama başlıklı makaleyi inceleyin.
  • Desteklenen hesap türleri: Hem ucp_agentic_performance_view hem de ucp_agentic_product_performance_view, yaprak hesapları (bağımsız hesaplar ve bireysel alt hesaplar) ve gelişmiş hesapları (çok müşterili hesaplar veya toplayıcı hesaplar) destekler. Ayrıntılar ve örnekler için Gelişmiş hesap düzeyinde sorgu başlıklı makaleyi inceleyin.
  • Zorunlu tarih filtresi: Her iki görünüm için de her sorgunun WHERE yan tümcesinde date ile ilgili bir koşul belirtmeniz gerekir.

Hesap düzeyinde UCP performansını analiz etme

Satın alma düğmesi tıklamaları ve hesap bağlamadan tamamlanan satın alma işlemlerine ve alışveriş sepeti aktarımlarına kadar genel UCP dönüşüm huninizi izlemek için ucp_agentic_performance_view kullanın.

Para birimi ve fiyat metrikleri

ucp_agentic_performance_view, para birimi ve Price metriklerini performans raporlarıyla aynı şekilde işler:

  • Price metrikleri: Aşağıdaki metrikler, hem amount_micros değeri hem de currency_code içeren bir Price nesnesi döndürür:
    • purchase_value
    • average_order_value
    • average_purchase_product_value
    • average_cart_value
    • average_cart_product_value
  • Fiyat dışı metrikler: Aşağıdaki metriklerin ilişkili bir para birimi yoktur:
    • buy_button_clicks
    • accounts_linked
    • account_linking_rate
    • purchase_count
    • cancellations
    • average_purchase_product_count
    • cart_transfers
    • average_cart_product_count
  1. Genel dönüşüm hunisi ve sayım metrikleri (para biriminden bağımsız): Para biriminden bağımsız toplam sayıları almak için yalnızca fiyat dışı metrikleri seçin.
  2. Satın alma ve alışveriş sepeti değeri metrikleri (para birimine göre): Para birimi başına geliri ve değeri analiz etmek için Price metriklerini ilgili sipariş ve alışveriş sepeti sayılarıyla birlikte seçin.

1. sorgu: Genel dönüşüm hunisi metriklerini alma (para biriminden bağımsız)

Para biriminden bağımsız olarak genel dönüşüm hunisi, sipariş sayısı ve alışveriş sepeti aktarım metriklerini almak için aşağıdaki sorguyu kullanın (Price değer metrikleri dahil değildir):

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'

Yanıtta, her müşteri ülkesi için toplu dönüşüm hunisi metrikleri döndürülür:

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

2. sorgu: Satın alma ve alışveriş sepeti değeri metriklerini alma (para birimine göre)

Satın alma değerlerini, ortalama sipariş değerlerini ve para birimine göre segmentlere ayrılmış alışveriş sepeti aktarım değerlerini almak için aşağıdaki sorguyu kullanın:

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

Yanıt, satın alma veya alışveriş sepeti değeri metriklerinde bulunan her para birimi için ayrı bir satır döndürür:

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

Ürün düzeyinde UCP performansını analiz etme

Doğrudan Google platformlarından satın alma düğmesi tıklamaları alan ürünleri görmek için ucp_agentic_product_performance_view kullanın.

"Satın al" düğmesi tıklamalarını ürüne göre alma

Belirli bir tarihte ürün düzeyinde satın alma düğmesi tıklamalarını almak için aşağıdaki sorguyu kullanın:

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

BETWEEN kullanarak bir tarih aralığındaki tıklamaları toplamak için SELECT ifadesinden date değerini de çıkarabilirsiniz:

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

Yanıt, eşleşen her teklif için toplam satın alma düğmesi tıklama sayısını döndürür:

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

Gelişmiş hesap düzeyinde sorgulama

accounts.reports.search isteğinin parent parametresinde accounts/{advanced_account_id} gibi bir gelişmiş hesap (çok müşterili hesap veya toplayıcı hesap) belirterek hem ucp_agentic_performance_view hem de ucp_agentic_product_performance_view için sorgu gönderebilirsiniz.

Her iki görünümde de account_id sütunu her zaman yaprak Merchant Center hesap kimliğini (gelişmiş bir hesap altında sorgulama yaparken bağımsız alt hesap kimliğini veya bağımsız bir hesabı sorgularken bağımsız hesap kimliğini) içerir. Gelişmiş hesap düzeyinde sorgulama yaparken SELECT ifadesine account_id ekleyip eklememeniz, metriklerin nasıl gruplandırılacağını belirler:

  • account_id değerini atla (gelişmiş hesap düzeyinde toplanır): account_id seçilmediğinde yanıt, gelişmiş hesaba ait tüm alt hesaplardaki metrikleri toplar.
  • account_id seçin (alt hesaba göre dökümü yapılır): account_id seçildiğinde yanıt, istatistikleri alt account_id'e göre segmentlere ayırır ve gelişmiş hesabın altındaki her alt hesap için ayrı satırlar döndürür.

Gelişmiş bir hesaptaki toplu metrikleri alma

Gelişmiş hesap düzeyinde toplanan toplam UCP dönüşüm hunisi metriklerini almak için isteği, parent kaynağı olarak gelişmiş hesap kimliğinizi kullanarak gönderin ve SELECT ifadesinden account_id değerini çıkarın:

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'

Yanıt, gelişmiş hesabın tüm alt hesaplarında tarih ve müşteri ülkesi başına tek bir toplu satır döndürür:

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

Alt hesaba göre dökümü yapılan metrikleri alma

Gelişmiş bir hesapta sorgu yaparken sonuçları alt hesaba göre dökümünü almak için SELECT ifadesine account_id ekleyin:

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'

account_id her zaman yaprak hesap kimliğini içerdiğinden yanıt, gelişmiş hesabın altındaki her alt hesap için ayrı bir satır döndürür:

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