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

‫Merchant Reports API מאפשר לכם לאחזר באופן פרוגרמטי מדדי ביצועים של המרות ותשלומים ב-Universal Commerce Protocol ‏ (UCP) בפלטפורמות השונות של Google, כולל מצב AI בחיפוש Google וב-Gemini. הדוחות האלה מספקים את אותן תובנות לגבי הביצועים שזמינות במרכז הבקרה לניתוח נתונים של פלטפורמת הלקוחות המאוחדת ב-Merchant Center, ועוזרים לכם לעקוב אחרי משפכי ההמרות, ההזמנות שהושלמו, ההעברות של עגלות הקניות וההתעניינות ברמת המוצר.

‫Reporting sub-API מספק שתי תצוגות לניתוח הביצועים של UCP:

• ‫UcpAgenticPerformanceView (ucp_agentic_performance_view): מספק מדדים ברמת החשבון לגבי משפך ההמרות, ההזמנות, הביטולים והעברות עגלות הקניות, בפילוח לפי תאריך ומדינת הלקוח.
• ‫UcpAgenticProductPerformanceView (ucp_agentic_product_performance_view): מספק מדדים ברמת המוצר (offer_id) של קליקים על לחצן הקנייה, בפילוח לפי תאריך ומדינת הלקוח.

לפני שמתחילים

לפני ששולחים שאילתות לתצוגות הביצועים של UCP, חשוב לוודא שהמקרה שלכם עונה על הקריטריונים הבאים:

• שימוש בנקודת הקצה (endpoint) של v1alpha: שולחים את השאילתות של MCQL למתודה v1alpha accounts.reports.search. פרטים על ביצוע בקשות דוחות זמינים במאמר תחילת העבודה עם Merchant Reports API.
• סוגי חשבונות נתמכים: גם ucp_agentic_performance_view וגם ucp_agentic_product_performance_view תומכים בחשבונות עלה (חשבונות עצמאיים וחשבונות משנה נפרדים) וגם בחשבונות מתקדמים (חשבונות מרובי-לקוחות או חשבונות אגרגטור). לפרטים נוספים ולעיון בדוגמאות, ראו שאילתה ברמת החשבון המתקדם.
• מסנן תאריכים נדרש: צריך לציין תנאי ב-date בסעיף WHERE של כל שאילתה בשתי התצוגות.

ניתוח הביצועים של UCP ברמת החשבון

אתם יכולים להשתמש ב-ucp_agentic_performance_view כדי לעקוב אחרי משפך ההמרות הכולל של UCP, החל מקליקים על לחצן הקנייה וקישור החשבון ועד לרכישות שהושלמו והעברות של עגלות קניות.

מדדי מטבע ומחיר

Price מטפל במטבע ובמדדי ucp_agentic_performance_view באותו אופן שבו הם מטופלים בדוחות הביצועים:

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

שאילתה 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'

התגובה מחזירה מדדי משפך מצטברים לכל מדינה של לקוח:

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

שאילתה ברמת החשבון המתקדם

אפשר לשלוח שאילתות גם ל-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_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"
      }
    }
  ]
}