تتيح لك واجهة برمجة تطبيقات YouTube Analytics إنشاء تقارير مخصصة تحتوي على بيانات YouTube Analytics. توفر واجهة برمجة التطبيقات تقارير للقنوات ومالكي المحتوى. تتميز حقول التقرير بالأبعاد أو المقاييس:
-
الأبعاد هي معايير شائعة تُستخدم لجمع البيانات، مثل تاريخ حدوث إجراء أو البلد الذي وقع فيه المستخدمون.
في كل تقرير، يحتوي كل صف من البيانات على مجموعة فريدة من قيم الأبعاد. وبالتالي، تحدد الأبعاد التي تختارها للتقرير كيفية حساب YouTube لقيم المقاييس في هذا التقرير.
- المقاييس عبارة عن مقاييس فردية ذات صلة بنشاط المستخدم أو أداء الإعلان أو الأرباح المقدّرة. تشمل مقاييس نشاط المستخدم عددًا، مثل عدد مشاهدات الفيديو وتقييماته (الإعجابات وإبداءات عدم الإعجاب).
وتوفّر واجهة برمجة تطبيقات "إحصاءات Google" معلّمات للفلترة والترتيب، لذا لا يحتاج تطبيق الاستدعاءات إلى دعم هذه الوظائف في الأصل. تسمح لك أيضًا واجهة برمجة التطبيقات باسترداد البيانات لمجموعات YouTube Analytics، حيث تضم المجموعة ما يصل إلى 500 فيديو أو قائمة تشغيل أو قناة أو مادة عرض مخصصة.
اختيار معلمات التقرير
عند طلب تقرير، باستخدام طريقة واجهة برمجة التطبيقات reports.query، يحتوي طلب البيانات من واجهة برمجة التطبيقات على خمس معلمات تحدد كيفية حساب قيم التقرير:
-
تحدد المعلمتان
startDateوendDateالفترة الزمنية التي سيحتوي التقرير على بيانات فيها. تحتوي استجابة واجهة برمجة التطبيقات على بيانات حتى اليوم الأخير الذي تتوفر له جميع المقاييس في طلب البحث في وقت طلب البحث. -
تحدّد المعلمة
metricsالقياسات التي سيتم تضمينها في التقرير. في تقارير القنوات، تقيس المقاييس نشاط المستخدم وتتضمّن قيمًا مثل المشاهدات وإبداءات الإعجاب. تقيس بعض المقاييس أيضًا أداء الإعلان أو الأرباح المقدّرة. -
تشرح المعلمة
dimensionsكيفية تجميع المقاييس. -
تشرح المعلمة
filtersكيفية فلترة بيانات التقرير. على سبيل المثال، بدلاً من عرض كل البيانات لقناة معيّنة، يمكن فلترة التقرير بحيث يحتوي فقط على مقاييس لبلد معيّن أو فيديو أو مجموعة معيّنة من الفيديوهات.ملاحظة: تسمح لك واجهة برمجة التطبيقات بتحديد قيم متعددة لفلاتر الفيديو وقائمة التشغيل والقناة. وفي هذه الحالة، يمكنك أيضًا تضمين هذا الفلتر في قائمة الأبعاد حتى يتم أيضًا تجميع المقاييس المعروضة بحسب الفيديو أو قائمة التشغيل أو القناة.
نماذج خيارات إعداد التقارير
على سبيل المثال، لنفترض أن مالك القناة يريد استرداد تقرير حول نوع جهاز الفيديو لتحديد عدد مرات مشاهدة مقاطع فيديو القناة على أجهزة الجوّال ووحدات تحكم الألعاب وأجهزة التلفزيون وما إلى ذلك.
-
يعيّن مالك القناة المعلمة
startDateإلى2015-06-01والمعلمةendDateإلى2015-07-31. واستنادًا إلى هذه القيم، سيحتوي التقرير على بيانات لمدة شهرين. -
يدعم تقرير نوع الجهاز مقياسَي المشاهدات وestimatedMinutesWatched، لذلك، ضبط مالك القناة المعلَمة
metricsعلىviews,estimatedMinutesWatched. -
بالنسبة إلى المعلَمة
dimensions، يتوفّر لمالك القناة عدد من الخيارات. ويتم عرض نوعَين منها في القائمة التالية، وستتم مناقشة ثالث في شرح قيمة المعلَمةfiltersلاحقًا في هذا القسم.-
وعند ضبط قيمة المَعلمة على
deviceType، سيتمّ تجميع عدد المُشاهَدات وعدد مُدد المشاهدة حسب نوع الجهاز خلال الفترة الكاملة التي يغطيها التقرير. لذا، باستخدام هذه القيمة، سترد بيانات التقرير على أسئلة مثل:- كم مرة تمت مشاهدة مقاطع فيديو القناة على أجهزة الجوّال بين 1 حزيران (يونيو) 2015 و31 تموز (يوليو) 2015؟
- كم مرة تمت مشاهدة مقاطع فيديو القناة على وحدات تحكم الألعاب في الفترة بين 1 حزيران (يونيو) 2015 و31 تموز (يوليو) 2015؟
وسيحتوي التقرير في الواقع على إجمالي عدد المشاهدات ووقت المشاهدة لكل نوع جهاز.
-
وعند ضبط قيمة المَعلمة على
day,deviceType، سيتمّ احتساب عدد المُشاهَدات وعدد مُشاهَدات وقت المشاهَدة حسب نوع الجهاز لكلّ يوم خلال الفترة المشمولة بالتقارير. لذا، باستخدام هذه القيمة، سترد بيانات التقرير على أسئلة مثل:- كم مرة تمت مشاهدة مقاطع فيديو القناة على أجهزة الجوال في 1 حزيران (يونيو) 2015؟
- كم مرة تمت مشاهدة مقاطع فيديو القناة على أجهزة التلفزيون في 14 تموز (يوليو) 2015؟
-
-
وأخيرًا، تسمح المَعلمة
filtersلمالك القناة بتقييد التقرير بحيث يتضمن فقط البيانات التي تتطابق مع قيم فلاتر معيّنة. يدعم التقرير عددًا كبيرًا جدًا من خيارات التصفية لتوضيحها جميعًا، لذلك تمثل هذه الأمثلة جزءًا صغيرًا فقط من التقارير التي يمكنك إنشاؤها.-
يمكن لمالك القناة فلترة الطلب لعرض القيم لنظام التشغيل Android فقط. (كم عدد مرات المشاهدة التي حدثت على أجهزة الجوال Android خلال الفترة المشمولة بالتقارير؟)
-
يمكن لمالك القناة فلترة طلب عرض القيم الخاصة ببلد معيّن فقط. (كم عدد المرات التي تمّت فيها مشاهدة الفيديوهات في كندا في كل يوم من الفترة المشمولة بالتقارير؟)
-
يمكن لمالك القناة فلترة طلب عرض القيم الخاصة ببعض الفيديوهات فقط. ولكن الفلتر فيديو يتيح قائمة من القيم مفصولة بفواصل، وبالتالي يمكن أن يحتوي التقرير على بيانات للعديد من مقاطع الفيديو.
علاوةً على ذلك، إذا كان الفلتر video يحدّد قيمًا متعدّدة، يمكن تحديد video أيضًا كسمة. وهذا يعني أن المعلَمة
dimensionsتتيح أيضًا القيمتَينdeviceType,videoوday,deviceType,video.- إذا أدرج مالك القناة فيديو في قائمة الأبعاد، فستحدد المقاييس قيمًا فردية لكل فيديو. (كم عدد مرات مشاهدة الفيديو XYZ على وحدة تحكم الألعاب في 1 حزيران (يونيو) 2015؟)
- وإذا لم يُدرج مالك القناة فيديو في قائمة الأبعاد، فستحدد المقاييس إجمالي القيم التي تغطي كل مقاطع الفيديو المحددة. (كم عدد مرات مشاهدة مقاطع الفيديو ABC وDEF وXYZ على وحدة تحكم الألعاب في 1 حزيران (يونيو) 2015؟)
-
جارٍ استرداد التقارير
لاسترداد تقرير، أرسل طلب GET معتمدًا إلى طريقة واجهة برمجة التطبيقات reports.query، مع تحديد المعلمات التي تحدد التقرير الذي تريد استرداده.
اطّلع على وثائق تقارير القنوات وتقارير مالكي المحتوى للحصول على قائمة بالتقارير التي تتيحها واجهة برمجة التطبيقات. يحدّد كل تعريف تقرير القيم التي يسمح بها التقرير للمعلمات metrics وdimensions وfilters.
أفضل الممارسات
يجب أن تلتزم التطبيقات التي تستخدم YouTube Analytics API دائمًا بالممارسات التالية:
- استخدم صف عنوان الرد لتحديد ترتيب أعمدة التقرير. على سبيل المثال، لا تفترض أن المشاهدات ستكون المقياس الأول المعروض في إحدى الردود فقط لأنه المقياس الأول المدرج في وصف التقرير. وبدلاً من ذلك، يمكنك استخدام صف عنوان الاستجابة لتحديد العمود الذي يحتوي على هذه البيانات.
- استخدم YouTube Data API لاسترداد بيانات وصفية إضافية للموارد المحدّدة في ردود واجهة برمجة تطبيقات YouTube Analytics. كما هو مذكور في سياسات مطوّري خدمات واجهة برمجة تطبيقات YouTube (الأقسام من 3.E.4.b إلى III.E.4.d)، يجب على عملاء واجهة برمجة التطبيقات حذف البيانات الوصفية للموارد المخزنة أو تحديثها من واجهة برمجة التطبيقات بعد 30 يومًا.
المقاييس المجمّعة والعناصر المحذوفة
لا تحتوي ردود واجهة برمجة تطبيقات YouTube Analytics على تفاصيل المقاييس للعناصر المحذوفة. على سبيل المثال، إذا حذف مالك قناة فيديو معيّنًا، لن يظهر بعد ذلك الفيديو في استجابة واجهة برمجة التطبيقات التي تعرض مقاييس على أساس كل فيديو على حدة. ومع ذلك، فإن التقارير التي تجمّع مقاييس لمجموعة من الموارد لا تزال تتضمن مقاييس مرتبطة بالعناصر المحذوفة.
على سبيل المثال، لنفترض أن مالك القناة يسترد تقريرين. يسرد التقرير الأول إجمالي عدد المشاهدات اليومية لكل الفيديوهات في القناة خلال فترة زمنية معيّنة. يعرض التقرير الثاني إجمالي المشاهدات اليومية على أساس كل فيديو على حدة خلال الفترة الزمنية نفسها.
في هذه الحالة، ستتضمن الأرقام الواردة في التقرير الأول مرات مشاهدة مقاطع الفيديو التي تم حذفها لاحقًا نظرًا لأن التقرير الأول يحتوي على بيانات يومية مجمّعة. ولكن، لن يشتمل التقرير الثاني على المشاهدات المرتبطة بالعناصر المحذوفة لأن التقرير الثاني يسرد عدد المشاهدات على أساس كل مقطع فيديو على حدة. ونتيجة لذلك، إذا حذفت القناة مقاطع الفيديو خلال الفترة الزمنية التي يغطيها التقرير، فقد يكون إجمالي عدد مرات المشاهدة اليومي المسجل في التقرير الأول أعلى من إجمالي عدد مرات المشاهدة اليومية الخاصة بالفيديو في التقرير الثاني.
إخفاء هوية البيانات
تكون بعض بيانات YouTube Analytics محدودة عندما لا تستوفي المقاييس حدًا معينًا. ويمكن أن يحدث ذلك في مجموعة متنوعة من التقارير. من الناحية العملية، يعني ذلك أن التقرير قد لا يحتوي على كل (أو أي) بياناتك، إذا:
-
أنّ عددًا محدودًا من الزيارات إلى فيديو أو قناة خلال فترة زمنية محدّدة
أو
-
لقد حددت فلترًا أو بُعدًا، مثل مصدر عدد الزيارات أو البلد، والذي لا تستوفي القيم له حدًا معينًا.
في الحالات التي تكون فيها البيانات محدودة، قد يكون هناك فرق بين الإجماليات المبلّغ عنها في تقارير مختلفة استنادًا إلى كيفية تجميع تلك التقارير للبيانات.
على سبيل المثال، لنفترض أن مالك القناة يسترد تقريرين. يسرد التقرير الأول إجمالي عدد المشاهدات لفيديو معيّن، ويدرج التقرير الثاني إجمالي المشاهدات لهذا الفيديو على أساس كل بلد على حدة. افترض أنّه تمّت مشاهدة الفيديو 1000 مرة خلال الفترة الزمنية المحدّدة، أي 500 مشاهدة في الولايات المتحدة و498 مشاهدة في كندا ومرّتين في فرنسا.
في هذا المثال، يشير التقرير الأول إلى مشاهدة الفيديو 1000 مرة. أما التقرير الثاني فيشير إلى أنه تمت مشاهدة الفيديو 500 مرة في الولايات المتحدة و498 مشاهدة في كندا فقط. وبالتالي، سيكون هناك فرق بين إجمالي عدد المشاهدات في التقريرين. تجدر الإشارة إلى أن التقرير الثاني لن يحتوي على أي إشارات تدل على حدوث مشاهدتين أخريين (أو حدوث أي مشاهدتين في فرنسا).
لا يتمّ نشر الحدود الفعلية التي تتوفّر فيها بيانات محدودة وتخضع للتغيير وفقًا لتقدير YouTube.
أنواع البيانات المحدودة
قد تكون البيانات التالية محدودة في تقارير YouTube Analytics:
- بيانات الديموغرافيات، مثل العمر والجنس
- البيانات الجغرافية، بما في ذلك المقاييس أو السمات المتعلّقة بالبلدان أو المناطق التي تواجد فيها المشاهدون، مثل بلدانهم أو مناطقهم ومع ذلك، تجدر الإشارة إلى أن التقارير لا تنطبق على حدود الموقع الجغرافي على مقاييس الأرباح.
- المقاييس المرتبطة بمصادر زيارات معيّنة، مثل عبارات البحث أو عناوين URL الخارجية التي أدّت إلى مشاهدة فيديوهاتك على سبيل المثال، لن تظهر عبارات البحث وعناوين URL التي تؤدي إلى أعداد صغيرة جدًا من المشاهدات في التقارير، ولكن ستستمر في مشاهدة العبارات وعناوين URL التي تجذب الكثير من المشاهدين إلى المحتوى التابع لك.
راجع مركز مساعدة YouTube للاطلاع على مزيد من المعلومات حول البيانات المحدودة في تقارير YouTube Analytics.
استخدام الحصة
يتم احتساب كل طلب تجريه لواجهة برمجة التطبيقات كوحدة واحدة من حصة استخدام واجهة برمجة التطبيقات. تظهر حدود الحصص في لوحة الحصص في وحدة تحكم واجهة برمجة تطبيقات Google.