Merchant Reports API מאפשר לכם לאחזר באופן פרוגרמטי מדדי ביצועים של המרות ותשלומים ב-Universal Commerce Protocol (UCP) בפלטפורמות השונות של Google, כולל מצב AI בחיפוש Google וב-Gemini. הדוחות האלה מספקים את אותן תובנות לגבי הביצועים שזמינות במרכז הבקרה לניתוח נתונים של פלטפורמת הלקוחות המאוחדת ב-Merchant Center, ועוזרים לכם לעקוב אחרי משפכי המרות, הזמנות שהושלמו, העברות של עגלות קניות ואינטראקציות ברמת המוצר.
ממשק ה-API המשני Reporting API מספק שתי תצוגות לניתוח הביצועים של UCP:
-
UcpAgenticPerformanceView(ucp_agentic_performance_view): מספק מדדים ברמת החשבון לגבי משפך ההמרות, ההזמנות, הביטולים והעברת עגלות הקניות, בפילוח לפי תאריך ומדינת הלקוח. -
UcpAgenticProductPerformanceView(ucp_agentic_product_performance_view): מספק מדדים ברמת המוצר (offer_id) של קליקים על לחצן הקנייה, בפילוח לפי תאריך ומדינת הלקוח.
לפני שמתחילים
לפני ששולחים שאילתות לתצוגות הביצועים של UCP, חשוב לוודא שהמקרה שלכם עונה על הקריטריונים הבאים:
- שימוש בנקודת הקצה (endpoint) של
v1alpha: שולחים את השאילתות של MCQL למתודהv1alphaaccounts.reports.search. פרטים על ביצוע בקשות דוחות זמינים במאמר תחילת העבודה עם Merchant Reports API. - סוגי חשבונות נתמכים: גם
ucp_agentic_performance_viewוגםucp_agentic_product_performance_viewתומכים בחשבונות עלה (חשבונות עצמאיים וחשבונות משנה נפרדים) וגם בחשבונות מתקדמים (חשבונות מרובי-לקוחות או חשבונות צבירה). לפרטים נוספים ולעיון בדוגמאות, ראו שאילתה ברמת החשבון המתקדם. - מסנן תאריכים נדרש: צריך לציין תנאי ב-
dateבסעיףWHEREשל כל שאילתה בשתי התצוגות.
ניתוח הביצועים של UCP ברמת החשבון
אפשר להשתמש ב-ucp_agentic_performance_view כדי לעקוב אחרי משפך ההמרות הכולל של UCP, החל מקליקים על לחצן הקנייה וקישור החשבון ועד לרכישות שהושלמו והעברות של עגלות קניות.
מדדי מטבע ומחיר
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יחד עם מספר ההזמנות ומספר עגלות הקניות המתאימים כדי לנתח את ההכנסה והערך לכל מטבע.
שאילתה 1: אחזור מדדי משפך כוללים (ללא תלות במטבע)
כדי לאחזר את המדדים הכוללים של משפך ההמרות, מספר ההזמנות והעברת העגלות, בלי קשר למטבע (בלי לכלול מדדי ערך של 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
}
}
]
}
שאילתה 2: אחזור מדדים של ערך הרכישה וערך עגלת הקניות (לפי מטבע)
כדי לאחזר ערכי רכישה, ערכי הזמנה ממוצעים וערכי העברה לעגלת הקניות בפילוח לפי מטבע, משתמשים בשאילתה הבאה:
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 כדי לראות אילו מוצרים ספציפיים מקבלים קליקים על לחצן הקנייה ישירות מפלטפורמות של 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"
}
}
]
}
שאילתה ברמת החשבון המתקדם
אפשר לשלוח שאילתות גם ל-ucp_agentic_performance_view וגם ל-ucp_agentic_product_performance_view על ידי ציון חשבון מתקדם (חשבון מרובה-לקוחות או חשבון אגרגטור) בפרמטר parent של הבקשה accounts.reports.search, למשל accounts/{advanced_account_id}.
בשתי התצוגות, העמודה account_id תמיד מכילה את מספר החשבון המשני ב-Merchant Center (מספר החשבון המשני הספציפי כששולחים שאילתה בחשבון מתקדם, או מספר החשבון העצמאי כששולחים שאילתה בחשבון עצמאי). כשמבצעים שאילתה ברמת החשבון המתקדם, הכללת account_id בסעיף SELECT קובעת איך המדדים מקובצים:
- השמטת
account_id(צבירה ברמת החשבון המתקדם): כשלא בוחרים אתaccount_id, התגובה צוברת מדדים בכל חשבונות המשנה ששייכים לחשבון המתקדם. - בחירה באפשרות
account_id(פירוט לפי חשבון משנה): כשבוחרים באפשרותaccount_id, התגובה מחלקת את הנתונים הסטטיסטיים לפי חשבון משנהaccount_id, ומחזירה שורות נפרדות לכל חשבון משנה בחשבון המתקדם.
אחזור מדדים מצטברים בחשבון מתקדם
כדי לאחזר את המדדים הכוללים של משפך ה-UCP ברמת החשבון המתקדם, שולחים את הבקשה עם מזהה החשבון המתקדם בתור המשאב 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"
}
}
]
}