تحلیل عملکرد عامل‌گرای پروتکل تجارت جهانی (آلفا)

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

‫Reporting sub-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 مراجعه کنید.
  • انواع حساب‌های پشتیبانی‌شده: هم ucp_agentic_performance_view و هم ucp_agentic_product_performance_view از حساب‌های برگ (حساب‌های مستقل و حساب‌های فرعی فردی) و همچنین حساب‌های پیشرفته (حساب‌های چندمشتری یا حساب‌های تجمیع‌کننده) پشتیبانی می‌کنند. برای جزئیات و نمونه‌ها، پرس‌وجو در سطح حساب پیشرفته را ببینید.
  • فیلتر تاریخ الزامی: باید شرطی را برای date در عبارت WHERE هر پُرسمان برای هر دو نما مشخص کنید.

تجزیه‌وتحلیل عملکرد «تبلیغ برنامه جهانی» در سطح حساب

از ucp_agentic_performance_view برای ردیابی قیف تبدیل کلی «پلاتفرم تجارت یکپارچه» استفاده کنید، از کلیک‌های دکمه خرید و پیوند دادن حساب تا خریدهای تکمیل‌شده و انتقال‌های سبد خرید.

سنجه‌های واحد پول و قیمت

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
  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'

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

{
  "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_agentic_product_performance_view استفاده کنید تا ببینید کدام محصولات به‌طور جداگانه کلیک‌های دکمه خرید را مستقیماً از سطوح Google دریافت می‌کنند.

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

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

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

پرس‌وجو در سطح حساب پیشرفته

می‌توانید با مشخص کردن یک حساب پیشرفته (حساب چندمشتری یا حساب تجمیع‌کننده) در پارامتر parent درخواست accounts.reports.search ، مانند accounts/{advanced_account_id}، هم ucp_agentic_performance_view و هم ucp_agentic_product_performance_view را پرسمان کنید.

در هر دو نما، ستون account_id همیشه شناسه حساب Merchant Center برگ را نگه می‌دارد (شناسه حساب فرعی تکی هنگام پرسمان تحت حساب پیشرفته، یا شناسه حساب مستقل هنگام پرسمان حساب مستقل). هنگام پرسمان در سطح حساب پیشرفته، اینکه آیا account_id را در عبارت SELECT اضافه می‌کنید یا نه، تعیین می‌کند که سنجه‌ها چگونه گروه‌بندی شوند:

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

بازیابی سنجه‌های تجمیعی در حساب پیشرفته

برای بازیابی کل سنجه‌های قیف «نمایه مشتریان واحد» که در سطح حساب پیشرفته جمع‌آوری شده‌اند، درخواست را بااستفاده از شناسه حساب پیشرفته‌تان به‌عنوان منبع parent ارسال کنید و account_id را از بند 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'

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

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

بازیابی سنجه‌ها به‌تفکیک حساب فرعی

برای تفکیک نتایج براساس حساب فرعی هنگام پرسمان حساب پیشرفته، account_id را در بند 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'

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

{
  "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"
      }
    }
  ]
}
قبلی
Analyze YouTube Affiliate Performance (Alpha)
بعدی
Use Merchant Center Query Language