تحليل أداء "الذكاء الوكيل" في "منصة الحملات الموحّدة" (الإصدار الأولي)

تجريبية: هذه الميزة في مرحلة الإصدار الأوّلي (تجريبية) وهي قابلة للتغيير.

تتيح لك واجهة برمجة التطبيقات Merchant Reports API استرداد مقاييس أداء الدفع وأداء الإحالات الناجحة في بروتوكول Universal Commerce Protocol (UCP) بشكل آلي على جميع مساحات عرض Google، بما في ذلك "وضع AI" في "بحث Google" وGemini. تقدّم هذه التقارير إحصاءات الأداء نفسها المتوفّرة في لوحة بيانات إحصاءات "بروتوكول UCP" في Merchant Center، ما يساعدك في تتبُّع مسارات الإحالات الناجحة والطلبات المكتملة وعمليات نقل سلّة التسوّق ومعدّل الاهتمام بالتطبيق على مستوى المنتج.

توفّر واجهة برمجة التطبيقات الفرعية Reporting طريقتَين لعرض التقارير من أجل تحليل أداء "الحملات الشاملة على جميع المنصات":

• ‫UcpAgenticPerformanceView (ucp_agentic_performance_view): يقدّم هذا التقرير مقاييس مسار الإحالة الناجحة والطلبات والإلغاء ونقل سلة التسوّق على مستوى الحساب، ويتم تقسيمها حسب التاريخ وبلد العميل.
• ‫UcpAgenticProductPerformanceView (ucp_agentic_product_performance_view): يقدّم مقاييس النقرات على زر الشراء على مستوى المنتج (offer_id) مقسّمة حسب التاريخ والبلد الذي يقيم فيه العميل.

قبل البدء

قبل طلب البحث في طرق عرض أداء "منصة المستخدمين الموحّدة"، تأكَّد من استيفاء المتطلبات التالية:

• استخدام نقطة النهاية 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"
      }
    }
  ]
}