عملکرد عامل UCP را تجزیه و تحلیل کنید (آلفا)

آزمایشی: این ویژگی در مرحله آلفا (آزمایشی) است و ممکن است تغییر کند.

رابط برنامه‌نویسی کاربردی گزارش‌های فروشندگان (Merchant Reports API) به شما امکان می‌دهد تا معیارهای عملکرد پرداخت و تبدیل پروتکل تجارت جهانی (UCP) را به صورت برنامه‌نویسی شده در سطوح مختلف گوگل، از جمله حالت هوش مصنوعی در جستجو و Gemini، بازیابی کنید. این گزارش‌ها همان بینش‌های عملکردی موجود در داشبورد تحلیلی UCP مرکز بازرگانان را ارائه می‌دهند و به شما در نظارت بر قیف‌های تبدیل، سفارشات تکمیل شده، انتقال سبد خرید و تعامل در سطح محصول کمک می‌کنند.

زیر-API گزارش‌دهی دو دیدگاه برای تحلیل عملکرد UCP ارائه می‌دهد:

• UcpAgenticPerformanceView ( ucp_agentic_performance_view ) : معیارهای قیف تبدیل، سفارش، لغو و انتقال سبد خرید را در سطح حساب کاربری، بر اساس تاریخ و کشور مشتری ارائه می‌دهد.
• UcpAgenticProductPerformanceView ( ucp_agentic_product_performance_view ) : معیارهای کلیک دکمه خرید در سطح محصول ( offer_id ) را بر اساس تاریخ و کشور مشتری تقسیم‌بندی می‌کند.

قبل از اینکه شروع کنی

قبل از پرس و جو در مورد نمایش عملکرد UCP، مطمئن شوید که شرایط زیر را برآورده می‌کنید:

• از نقطه پایانی v1alpha استفاده کنید : کوئری‌های MCQL خود را به متد v1alpha accounts.reports.search ارسال کنید. برای جزئیات بیشتر در مورد اجرای درخواست‌های گزارش، به Merchant Reports API Get start مراجعه کنید.
• فقط حساب‌های کاربری برگ : هر دو ucp_agentic_performance_view و ucp_agentic_product_performance_view فقط برای انواع حساب‌های کاربری برگ (حساب‌های مستقل و زیرحساب‌های جداگانه) در دسترس هستند. سرویس گزارش‌گیری از حساب‌های کاربری پیشرفته (حساب‌های چند کلاینتی) پشتیبانی نمی‌کند. برای بازیابی عملکرد UCP در یک حساب کاربری پیشرفته، هر زیرحساب را به صورت جداگانه جستجو کنید.
• فیلتر تاریخ مورد نیاز : شما باید در هر کوئری برای هر دو نما، در عبارت WHERE شرطی را روی date مشخص کنید.

عملکرد UCP در سطح حساب را تجزیه و تحلیل کنید

از ucp_agentic_performance_view برای ردیابی قیف تبدیل کلی UCP خود، از کلیک‌های دکمه خرید و لینک حساب گرفته تا خریدهای تکمیل‌شده و انتقال سبد خرید، استفاده کنید.

معیارهای ارز و قیمت

ucp_agentic_performance_view معیارهای ارز و Price را به همان روشی که گزارش‌های عملکرد را مدیریت می‌کند، مدیریت می‌کند:

• معیارهای Price : معیارهای زیر یک شیء Price را برمی‌گردانند که شامل مقدار amount_micros و currency_code است:
  • purchase_value
  • average_order_value
  • average_purchase_product_value
  • average_cart_value
  • average_cart_product_value
• معیارهای غیرقیمتی : معیارهای زیر ارز مرتبطی ندارند:
  • buy_button_clicks
  • accounts_linked
  • account_linking_rate
  • purchase_count
  • cancellations
  • average_purchase_product_count
  • cart_transfers
  • average_cart_product_count

مهم: گنجاندن معیارهای قیف یا شمارش (مانند buy_button_clicks ) در همان پرس‌وجو به عنوان معیارهای ارزش Price ، ردیف‌های برگردانده شده را بر اساس واحد پول جدا می‌کند. از آنجا که معیارهایی مانند buy_button_clicks به خودی خود واحد پول مرتبطی ندارند، ترکیب آنها با معیارهای Price می‌تواند ردیف‌های بدون مقادیر خرید را تقسیم یا حذف کند. برای جلوگیری از این امر و به دست آوردن مجموع دقیق، دو پرس‌وجوی جداگانه اجرا کنید:

1. معیارهای کلی قیف و تعداد (مستقل از ارز) : فقط معیارهای غیر قیمتی را انتخاب کنید تا تعداد کل مستقل از ارز به دست آید.
2. معیارهای ارزش خرید و سبد خرید (بر اساس واحد پول) : معیارهای Price را به همراه تعداد سفارش و سبد خرید مربوطه انتخاب کنید تا درآمد و ارزش هر واحد پول را تجزیه و تحلیل کنید.

سوال ۱: بازیابی معیارهای کلی قیف فروش (مستقل از ارز)

از کوئری زیر برای بازیابی معیارهای کلی قیف تبدیل، تعداد سفارش و انتقال سبد خرید، مستقل از واحد پول (بدون در نظر گرفتن معیارهای ارزش 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'

توجه: از آنجا که average_cart_value یک معیار Price با یک currency_code مرتبط است، آن را از کوئری کلی قیف فروش خود حذف کنید و در عوض آن را در کوئری خرید و ارزش سبد خرید خود بگنجانید.

این پاسخ، معیارهای قیف فروش تجمیعی را برای هر کشور مشتری برمی‌گرداند:

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

سوال ۲: بازیابی معیارهای ارزش خرید و سبد خرید (بر اساس واحد پول)

از کوئری زیر برای بازیابی مقادیر خرید، مقادیر میانگین سفارش و مقادیر انتقال سبد خرید، به تفکیک واحد پول، استفاده کنید:

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

پاسخ، برای هر واحد پولی موجود در معیارهای ارزش خرید یا سبد خرید، یک ردیف جداگانه برمی‌گرداند:

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

عملکرد UCP در سطح محصول را تجزیه و تحلیل کنید

از ucp_agentic_product_performance_view استفاده کنید تا ببینید کدام محصولات به طور مستقیم از طریق سطوح گوگل، کلیک دکمه خرید دریافت می‌کنند.

بازیابی کلیک‌های دکمه خرید بر اساس محصول

از کوئری زیر برای بازیابی کلیک‌های دکمه خرید در سطح محصول برای یک تاریخ خاص استفاده کنید:

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

همچنین می‌توانید date از دستور SELECT حذف کنید تا کلیک‌ها در یک محدوده تاریخی با استفاده از 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

پاسخ، تعداد کلیک‌های دکمه خرید را برای هر پیشنهاد منطبق، به صورت تجمیعی برمی‌گرداند:

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