ملاحظة مهمة: سيتم إيقاف Content API for Shopping نهائيًا في 18 أغسطس 2026.

إذا كنت بحاجة إلى وقت إضافي للانتقال إلى Merchant API، يمكنك طلب الوصول لفترة أطول إلى Content API for Shopping.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

تتيح لك 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) على مستوى المنتج، مقسّمة حسب التاريخ وبلد العميل.

قبل البدء

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

استخدام نقطة النهاية v1alpha: أرسِل طلبات MCQL إلى طريقة v1alpha accounts.reports.search. لمعرفة التفاصيل حول تنفيذ طلبات التقارير، يُرجى الاطّلاع على الخطوات الأولى لاستخدام Merchant Reports API.
أنواع الحسابات المتوافقة: يتيح كلّ من ucp_agentic_performance_view وucp_agentic_product_performance_view استخدام الحسابات الفرعية (الحسابات المستقلة والحسابات الفرعية الفردية) بالإضافة إلى الحسابات بامتيازات متقدّمة (الحسابات المتعدّدة العملاء أو حسابات المجمّعين). للاطّلاع على التفاصيل والأمثلة، يُرجى مراجعة الاستعلام على مستوى الحساب بامتيازات متقدّمة.
فلتر التاريخ المطلوب: يجب تحديد شرط على date في عبارة WHERE لكل طلب بحث في كلا العرضَين.

تحليل أداء "حملات التطبيقات الموحّدة" على مستوى الحساب

يمكنك استخدام 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

مقاييس مسار الإحالة الناجحة والعدد الإجمالية (غير مرتبطة بالعملة): اختَر فقط المقاييس غير المرتبطة بالسعر للحصول على أعداد مجمّعة غير مرتبطة بالعملة.
مقاييس قيمة الشراء وسلّة التسوّق (حسب العملة): اختَر مقاييس 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 طريقة تجميع المقاييس:

Omit account_id (aggregated at the advanced account level): عند عدم اختيار 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"
      }
    }
  ]
}

Analyze YouTube Affiliate Performance (Alpha)

Use Merchant Center Query Language