مقاييس أداء YouTube

ملاحظة مُهمّة: لا تتوفّر هذه الميزة إلا للحسابات المُدرَجة في قائمة السماح. يُرجى التواصل مع ممثّل Google الذي تتعامل معه إذا كنت بحاجة إلى الوصول إلى هذه الميزة.

تتيح BenchmarksService للمعلنين ووكالات الإعلان مقارنة أداء إعلاناتهم على YouTube بمقاييس الأداء في المجال. باستخدام هذه الخدمة، يمكنك تقييم مستوى أداء حملاتك مقارنةً بالقطاعات الصناعية أو بجميع المعلِنين في فئات معيّنة من المنتجات والخدمات.

الإمكانات الأساسية

باستخدام BenchmarksService، يمكنك إجراء ما يلي:

• مقارنة الأداء: يمكنك تقييم مقاييس متوسط معدل عميل (مثل التكلفة لكل ألف ظهور وتكلفة المشاهدة ونسبة النقر إلى الظهور وإمكانية العرض) مقارنةً بمتوسطات الأداء المجمّعة في المجال.
• تحليل حصة السوق: يمكنك فهم مدى حضور أحد العملاء في السوق مقارنةً بغيره من خلال نسبة المساحة المتوفّرة للمعلِن (مرات الظهور النسبية) ونسبة الإنفاق.
• تقييم الوضع التنافسي: يمكنك قياس الوضع التنافسي لأحد العملاء باستخدام مقاييس النسبة المئوية التي تصنّف الأداء على مستوى السمات الرئيسية إلى فئات تنافسية (مثل الشركة الرائدة في السوق أو المنافس).
• التقسيم حسب الوقت: يمكنك تجميع مقاييس الأداء حسب مستويات الدقة الزمنية الأسبوعية أو الشهرية أو الربع سنوية.
• التعرّف على سمات قياس الأداء المتاحة: يمكنك طلب نطاقات التواريخ المتاحة والمواقع الجغرافية والمنتجات الإعلانية ومصادر قياس الأداء (القطاعات الصناعية أو فئات المنتجات والخدمات).

ملاحظة: يجب تقديم رقم تعريف عميل في طلباتك. لن يعرض رقم تعريف عميل الحساب الإداري مقاييس العملاء لأنّ الحسابات الإدارية لا تُطلق حملات إعلانية مباشرةً.

طُرق الرصد

قبل إنشاء مقاييس قياس الأداء، استخدِم طرق البحث لاسترداد المَعلمات ومعايير تحديد النطاق الصالحة لطلباتك.

عرض التواريخ المتاحة

تعرض طريقة ListBenchmarksAvailableDates نطاقات التواريخ السابقة التي تتوافق مع بيانات قياس الأداء في ListBenchmarksAvailableDatesResponse.

يقدّم الردّ نطاقَين زمنيَين مختلفَين:

• ‫supported_dates: النطاق الزمني الإجمالي الذي تتوفّر فيه مقاييس الأداء (شامل). يمكن أن تستعلم طلبات قياس الأداء عن تواريخ ضمن هذا النطاق.
• supported_dates_for_all_metrics: مجموعة فرعية من supported_dates تتوافق مع المجموعة الكاملة من مقاييس الأداء. لا تتوفّر مقاييس معيّنة، وتحديدًا مقاييس حصة العملاء (share_of_voice وshare_of_spend) ومقاييس متوسط التقييم من مصدر قياس الأداء، إلا ضمن هذا النطاق الزمني بسبب محدودية توفّر البيانات. يتم حذف هذه المقاييس من الردّ إذا لم تندرج date_range المطلوبة بالكامل ضمن supported_dates_for_all_metrics.

سرد مواقع

تعرض الطريقة ListBenchmarksLocations قائمة بالمواقع الجغرافية (مثل البلدان) التي تتوافق مع بيانات قياس الأداء.

يتضمّن كل BenchmarksLocation في الردّ ما يلي:

• location_name: اسم الموقع الجغرافي الفريد باللغة الإنجليزية (مثلاً، "United States").
• location_type: نوع الموقع الجغرافي الذي يتوافق مع target_type في Google Ads API (على سبيل المثال، "Country").
• ‫location_info: عنصر LocationInfo يحتوي على الثابت الخاص بالاستهداف الجغرافي (مثل geo_target_constant: "geoTargetConstants/2840").

عرض المنتجات

تعرض الطريقة ListBenchmarksProducts قائمة بالمنتجات وأهداف التسويق المتاحة لقياس الأداء.

يتضمّن كل إدخال BenchmarksProductMetadata ما يلي:

• ‫product_name: اسم المنتج السهل الاستخدام
• product_code: سلسلة المعرّف الفريد للمنتج، ويتم استخدامها عند إنشاء ProductFilter.
• ‫marketing_objective: الهدف التسويقي المرتبط (BenchmarksMarketingObjective):
  • ‫AWARENESS: حملات مصمّمة لزيادة الوعي بالعلامة التجارية أو المنتج
  • ‫CONSIDERATION: حملات مصمَّمة لتشجيع العملاء المحتملين على التفكير في العلامة التجارية أو المنتجات.
  • ACTION: حملات مصمَّمة لزيادة إجراء إحالة ناجحة معيّن.

سرد مصادر مقاييس الأداء

يستردّ الإجراء ListBenchmarksSources مصادر قياس الأداء المتاحة. حدِّد أنواع المصادر التي تريد استردادها باستخدام BenchmarksSourceType:

• ‫INDUSTRY_VERTICAL: تصنيفات لقطاعات الصناعة (على سبيل المثال، "التكنولوجيا" أو "الشؤون المالية")
• ‫CATEGORY: فئات المنتجات والخدمات (على سبيل المثال، "/Apparel/Clothing"). يمكن استخدام الفئات كفلاتر لتحديد نطاق قياس الأداء عند المقارنة مع جميع المعلِنين.

يعرض الردّ قائمة بعناصر BenchmarksSourceMetadata تحتوي على أحد الخيارَين التاليَين:

• ‫IndustryVerticalInfo: يحتوي على industry_vertical_name وindustry_vertical_id وparent_industry_vertical_id (إذا كان ذلك منطبقًا).
• CategoryInfo: يحتوي على category_name وcategory_id وcategory_path (التسلسل الهرمي الكامل للفئات).

إنشاء مقاييس الأداء

اتّصِل برقم GenerateBenchmarksMetrics لمقارنة مقاييس إعلانات أحد العملاء على YouTube بمقاييس الأداء العامة في المجال.

مَعلمات الطلب

تحدّد GenerateBenchmarksMetricsRequest نطاق التحليل. يجب تحديد customer_id للعميل وlocation جغرافي وbenchmarks_source (مثل مجال صناعي محدّد أو جميع المعلِنين الذين يندرجون ضمن category_filter) وproduct_filter كحدّ أدنى. يمكنك اختياريًا تقديم date_range أو تجميع المقاييس باستخدام breakdown_definition أو تحديد currency_code أو طلب ميزات إضافية، مثل PERCENTILE_DATA من خلال supplemental_data.

للاطّلاع على تعريفات المَعلمات ومتطلباتها الكاملة، يُرجى الرجوع إلى GenerateBenchmarksMetricsRequest.

تقسيمات حسب التاريخ

يمكنك تجميع المقاييس من خلال ضبط breakdown_definition.date_breakdown باستخدام BenchmarksTimeGranularity:

• ‫WEEK: يجمع المقاييس حسب الأسبوع. يجب أن تبدأ date_range في يوم الأحد وتنتهي في يوم السبت (يُرجى العِلم أنّ هذا يختلف عن معيار ISO 8601).
• ‫MONTH: يجمع المقاييس حسب الشهر. يجب أن تبدأ فترة date_range في اليوم الأول من الشهر وتنتهي في اليوم الأخير منه.
• QUARTER: يجمع المقاييس حسب الربع السنوي. يجب أن تبدأ date_range في اليوم الأول من الربع وتنتهي في اليوم الأخير منه.

مقاييس الاستجابة

تعرض GenerateBenchmarksMetricsResponse ما يلي:

• customer_metrics: مقاييس تمثّل أداء إعلانات أحد العملاء على YouTube، بما في ذلك average_rate_metrics وshare_metrics وaggregate_metrics وpercentile_metrics.
• average_benchmarks_metrics: مقاييس المعدّل المجمّع (RateMetrics) على مستوى مصدر قياس الأداء المحدّد
• breakdown_metrics: قائمة بالمقاييس مقسّمة حسب التصنيفات المحدّدة في breakdown_definition.

للاطّلاع على مواصفات الحقول الكاملة، يُرجى الرجوع إلى GenerateBenchmarksMetricsResponse المستندات المرجعية.

مقاييس النسبة المئوية

تمثّل مقاييس النسبة المئوية ترتيب العميل التنافسي على شكل فئات نسبة مئوية بين المعلِنين الآخرين ضمن التحليل المحدّد النطاق.

المتطلبات الأساسية

لاسترداد مقاييس النسبة المئوية، يجب أن يستوفي طلبك المتطلبات التالية:

1. مصدر مقاييس الأداء: يجب اختيار benchmarks_source all_advertisers = true.
2. فلتر الفئات: يجب توفير category_filter الذي يحتوي على category_ids واحد أو أكثر صالح يتم استرجاعه من ListBenchmarksSources.
3. البيانات التكميلية: يجب إضافة PERCENTILE_DATA إلى الحقل supplemental_data في GenerateBenchmarksMetricsRequest.

الشرائح المئوية

يتم تصنيف أداء العميل ضمن إحدى قيم التعداد BenchmarksCustomerPercentileTier (التي تتراوح من DEVELOPING للمستويات الأدنى إلى MARKET_LEADER للمعلنين الأفضل أداءً). للحصول على وصف لكل فئة وحدودها المئوية، يُرجى الرجوع إلى مستند BenchmarksCustomerPercentileTier المرجعي.

مثال على الطلب

يوضّح المثال التالي حمولة طلب JSON لخدمة REST من أجل إنشاء مقاييس الأداء المرجعي مع فئات النسبة المئوية لمستخدم يقارن أداء إعلانات عميله على YouTube بأداء المعلِنين الآخرين الذين يعرضون إعلانات في فئة /Apparel/Clothing:

{
  "customer_id": "1234567890",
  "location": {
    "geo_target_constant": "geoTargetConstants/2840"
  },
  "benchmarks_source": {
    "all_advertisers": true
  },
  "category_filter": {
    "category_ids": ["10176"]
  },
  "product_filter": {
    "marketing_objective_list": {
      "marketing_objectives": ["AWARENESS", "CONSIDERATION"]
    }
  },
  "supplemental_data": [
    "PERCENTILE_DATA"
  ]
}

الردّ الذي يتضمّن بيانات النسبة المئوية الإضافية المطلوبة:

{
  "customer_metrics": {
    "average_rate_metrics": {
      "average_cpm": 5.42,
      "click_through_rate": 0.0185
    },
    "share_metrics": {
      "share_of_voice": 0.0345,
      "share_of_spend": 0.0410
    },
    "aggregate_metrics": {
      "cost": 15200.0,
      "impressions": 2800000.0,
      "clicks": 51800.0
    },
    "percentile_metrics": {
      "cost_percentile_tier": "STRONG_COMPETITOR",
      "impressions_percentile_tier": "STRONG_COMPETITOR",
      "clicks_percentile_tier": "MARKET_LEADER",
      "video_trueview_views_percentile_tier": "COMPETITOR",
      "viewable_impressions_percentile_tier": "STRONG_COMPETITOR",
      "interactions_percentile_tier": "MARKET_LEADER",
      "engagements_percentile_tier": "COMPETITOR"
    }
  },
  "average_benchmarks_metrics": {
    "average_rate_metrics": {
      "average_cpm": 6.15,
      "click_through_rate": 0.0142
    }
  }
}

معالجة الأخطاء

عند طلب BenchmarksService، قد تواجه أخطاء خاصة بطلبات البحث عن مقاييس الأداء في BenchmarksError:

• MAX_QUERY_COMPLEXITY_EXCEEDED: إنّ مجموعة المدخلات المطلوبة معقّدة جدًا بحيث لا يمكن معالجتها. لتقليل تعقيد طلب البحث:
  • اختَر مصدرًا أو فلتر فئة أكثر تحديدًا أو دقةً لمقياس الأداء.
  • تقصير مدة date_range المطلوبة
  • تقليل عدد المنتجات في product_filter
• NO_METRICS_FOUND: لم يتم العثور على أي مقاييس لمجموعة المدخلات المطلوبة (على سبيل المثال، فئة متخصّصة في موقع جغرافي ونطاق زمني محدّدين لم يعرض فيها أي معلنين حملات). حاوِل تعديل الفئة أو الموقع الجغرافي أو النطاق الزمني أو المنتجات.

للحصول على معلومات عامة حول معالجة الأخطاء في واجهة برمجة التطبيقات وأفضل الممارسات، يُرجى الاطّلاع على دليل معالجة الأخطاء.