با 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 خود را به روشv1alphaaccounts.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را برمیگردانند که حاوی مقدارamount_microsوcurrency_codeاست:purchase_valueaverage_order_valueaverage_purchase_product_valueaverage_cart_valueaverage_cart_product_value
سنجههای غیرقیمتی: سنجههای زیر واحد پول مرتبط ندارند:
buy_button_clicksaccounts_linkedaccount_linking_attemptsaccount_linking_ratepurchase_countcancellationsaverage_purchase_product_countcart_transfersaverage_cart_product_count
- سنجههای کلی قیف و شمارش (مستقل از ارز): فقط سنجههای غیرقیمتی را انتخاب کنید تا شمارشهای مجموع مستقل از ارز را دریافت کنید.
- سنجههای مقدار خرید و سبد خرید (براساس واحد پول):
Priceسنجه را همراه با تعداد سفارش و سبد خرید مربوطه انتخاب کنید تا درآمد و مقدار را براساس واحد پول تحلیل کنید.
پُرسمان ۱: بازیابی سنجههای کلی قیف (مستقل از واحد پول)
از پُرسمان زیر برای بازیابی قیف تبدیل کلی، تعداد سفارش، و
سنجههای انتقال سبد خرید مستقل از ارز (بدون گنجاندن سنجههای مقدار Price)
استفاده کنید:
SELECT
date,
account_id,
customer_country_code,
buy_button_clicks,
accounts_linked,
account_linking_attempts,
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",
"accountLinkingAttempts": "125",
"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_attempts,
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",
"accountLinkingAttempts": "200",
"accountLinkingRate": 0.7,
"purchaseCount": "110",
"cancellations": "5"
}
}
]
}
بازیابی سنجهها بهتفکیک حساب فرعی
برای تفکیک نتایج براساس حساب فرعی هنگام پرسمان حساب پیشرفته،
account_id را در بند SELECT اضافه کنید:
SELECT
date,
account_id,
customer_country_code,
buy_button_clicks,
accounts_linked,
account_linking_attempts,
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",
"accountLinkingAttempts": "125",
"accountLinkingRate": 0.68,
"purchaseCount": "64",
"cancellations": "3"
}
},
{
"ucpAgenticPerformanceView": {
"date": {
"year": 2026,
"month": 9,
"day": 20
},
"accountId": "987654321",
"customerCountryCode": "US",
"buyButtonClicks": "310",
"accountsLinked": "55",
"accountLinkingAttempts": "100",
"accountLinkingRate": 0.55,
"purchaseCount": "46",
"cancellations": "2"
}
}
]
}