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