ניתוח הביצועים של סוכנים ב-UCP (אלפא)

ניסיוני: התכונה הזו נמצאת בשלב אלפא (ניסיוני) ועשויה להשתנות.

‫Merchant Reports API מאפשר לכם לאחזר באופן פרוגרמטי מדדי ביצועים של תהליך התשלום ומספר ההמרות ב-Universal Commerce Protocol‏ (UCP) בכל ממשקי Google, כולל מצב AI בחיפוש Google וב-Gemini. הדוחות האלה מספקים את אותן תובנות לגבי הביצועים שזמינות במרכז הבקרה של ניתוח הנתונים ב-UCP ב-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 זמינות רק לסוגי חשבונות עלים (חשבונות עצמאיים וחשבונות משנה פרטיים). שירות הדיווח לא תומך בחשבונות מתקדמים (חשבונות מרובי-לקוחות). כדי לאחזר את הביצועים של UCP בחשבון מתקדם, צריך לשלוח שאילתה לכל חשבון משנה בנפרד.
• מסנן תאריכים נדרש: צריך לציין תנאי ב-date בסעיף WHERE של כל שאילתה בשני התצוגות.

ניתוח הביצועים של 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 מדדים יחד עם מספר ההזמנות ומספר העגלות התואמים כדי לנתח את ההכנסה והערך לפי מטבע.

שאילתה 1: אחזור מדדים כלליים של משפך (ללא תלות במטבע)

אפשר להשתמש בשאילתה הבאה כדי לאחזר את המשפך הכולל של ההמרות, את מספר ההזמנות ואת מדדי העברת עגלות הקניות ללא תלות במטבע (ללא מדדי ערך 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
      }
    }
  ]
}

שאילתה 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"
      }
    }
  ]
}