API یوتیوب آنالیتیکس شما را قادر میسازد گزارشهای سفارشی حاوی دادههای یوتیوب آنالیتیکس ایجاد کنید. این API از گزارشها برای کانالها و صاحبان محتوا پشتیبانی میکند. فیلدهای گزارش به صورت ابعاد یا معیارها مشخص میشوند:
ابعاد، معیارهای رایجی هستند که برای جمعآوری دادهها استفاده میشوند، مانند تاریخی که یک اقدام رخ داده یا کشوری که کاربران در آن قرار دارند.
در یک گزارش، هر ردیف از دادهها ترکیبی منحصر به فرد از مقادیر ابعاد دارد. به این ترتیب، ابعادی که برای یک گزارش انتخاب میکنید، نحوه محاسبه مقادیر معیارهای موجود در آن گزارش توسط یوتیوب را تعیین میکند.
- معیارها، اندازهگیریهای فردی مربوط به فعالیت کاربر، عملکرد تبلیغات یا درآمد تخمینی هستند. معیارهای فعالیت کاربر شامل مواردی مانند تعداد بازدید ویدیو و رتبهبندی (لایک و دیسلایک) میشود.
API تجزیه و تحلیل، پارامترهای فیلتر کردن و مرتبسازی را فراهم میکند، بنابراین برنامه فراخوانی نیازی به پشتیبانی بومی از این توابع ندارد. این API همچنین به شما امکان میدهد دادهها را برای گروههای YouTube Analytics بازیابی کنید، که در آن یک گروه مجموعهای سفارشی از حداکثر ۵۰۰ ویدیو، لیست پخش، کانال یا دارایی است.
انتخاب پارامترهای گزارش
وقتی با استفاده از متد reports.query در API، گزارشی را درخواست میکنید، درخواست API شامل پنج پارامتر است که نحوه محاسبه مقادیر گزارش را تعیین میکنند:
پارامترهای
startDateوendDateدوره زمانی را مشخص میکنند که گزارش شامل دادهها خواهد بود. پاسخ API در واقع شامل دادهها تا آخرین روزی است که تمام معیارهای موجود در پرسوجو در زمان پرسوجو در دسترس هستند.پارامتر
metrics، معیارهایی را که در گزارش لحاظ میشوند، مشخص میکند. در گزارشهای کانال، معیارها فعالیت کاربر را اندازهگیری میکنند و شامل مقادیری مانند بازدیدها و لایکها میشوند. برخی از معیارها همچنین عملکرد تبلیغات یا درآمد تخمینی را اندازهگیری میکنند.پارامتر
dimensionsتوضیح میدهد که چگونه معیارها گروهبندی خواهند شد.پارامتر
filtersتوضیح میدهد که چگونه دادههای گزارش فیلتر میشوند. بنابراین، برای مثال، به جای بازگرداندن تمام دادههای یک کانال، میتوان یک گزارش را طوری فیلتر کرد که فقط شامل معیارهای یک کشور، ویدیو یا گروه خاصی از ویدیوها باشد.نکته: این API به شما امکان میدهد چندین مقدار برای فیلترهای ویدیو ، لیست پخش و کانال تعیین کنید. اگر این کار را انجام دهید، میتوانید آن فیلتر را در لیست ابعاد نیز قرار دهید تا معیارهای بازگشتی نیز بر اساس ویدیو، لیست پخش یا کانال گروهبندی شوند.
گزینههای گزارش نمونه
به عنوان مثال، فرض کنید صاحب یک کانال میخواهد گزارشی از نوع دستگاه پخش ویدیو دریافت کند تا مشخص شود که ویدیوهای کانال چند بار در دستگاههای تلفن همراه، کنسولهای بازی، تلویزیونها و غیره مشاهده شدهاند.
مالک کانال پارامتر
startDateرا روی2015-06-01و پارامترendDateرا روی2015-07-31تنظیم میکند. بر اساس این مقادیر، گزارش شامل دادههایی برای یک دوره دو ماهه خواهد بود.گزارش نوع دستگاه از معیارهای views و estimationMinutesWatched پشتیبانی میکند، بنابراین صاحب کانال پارامتر
metricsرا رویviews,estimatedMinutesWatchedتنظیم میکند.برای پارامتر
dimensions، صاحب کانال گزینههای مختلفی دارد. دو مورد از آنها در لیست زیر نشان داده شده است و مورد سوم در توضیح مقدار پارامترfiltersبعداً در این بخش مورد بحث قرار خواهد گرفت.تنظیم مقدار پارامتر روی
deviceTypeبه این معنی است که تعداد بازدیدها و تعداد زمانهای مشاهده، برای کل دورهای که گزارش پوشش میدهد، بر اساس نوع دستگاه گروهبندی میشوند. بنابراین، با این مقدار، دادههای گزارش به سؤالاتی مانند موارد زیر پاسخ خواهند داد:- ویدیوهای کانال بین ۱ ژوئن ۲۰۱۵ و ۳۱ جولای ۲۰۱۵ چند بار در دستگاههای تلفن همراه مشاهده شدهاند؟
- ویدیوهای کانال بین ۱ ژوئن ۲۰۱۵ و ۳۱ جولای ۲۰۱۵ چند بار در کنسولهای بازی دیده شدهاند؟
این گزارش در واقع شامل تعداد کل زمان مشاهده و تماشا برای هر نوع دستگاه خواهد بود.
تنظیم مقدار پارامتر به
day,deviceTypeبه این معنی است که تعداد بازدیدها و تعداد زمانهای تماشا بر اساس نوع دستگاه برای هر روز در طول دوره گزارش محاسبه میشوند. بنابراین، با این مقدار، دادههای گزارش به سؤالاتی مانند موارد زیر پاسخ خواهند داد:- ویدیوهای کانال در تاریخ ۱ ژوئن ۲۰۱۵ چند بار در دستگاههای تلفن همراه مشاهده شدهاند؟
- ویدیوهای این کانال در تاریخ ۱۴ جولای ۲۰۱۵ چند بار از تلویزیونها دیده شدهاند؟
در نهایت، پارامتر
filtersبه صاحب کانال اجازه میدهد گزارش را محدود کند تا فقط دادههایی را که با مقادیر فیلتر خاص مطابقت دارند، شامل شود. این گزارش از گزینههای فیلترینگ بسیار زیادی پشتیبانی میکند که توضیح همه آنها غیرممکن است، بنابراین این مثالها تنها بخشی از گزارشهایی را که میتوانید ایجاد کنید، نشان میدهند.صاحب کانال میتواند درخواست را طوری فیلتر کند که فقط مقادیر مربوط به سیستم عامل اندروید را برگرداند. (در طول دوره گزارش، چند بازدید در دستگاههای تلفن همراه اندروید رخ داده است؟)
صاحب کانال میتواند درخواست را طوری فیلتر کند که فقط مقادیر مربوط به یک کشور خاص را برگرداند. (در هر روز از دوره گزارش، ویدیوها در کانادا چند بار دیده شدهاند؟)
صاحب کانال میتواند درخواست را طوری فیلتر کند که فقط مقادیر مربوط به ویدیوهای خاص را برگرداند. با این حال، فیلتر ویدیو از فهرستی از مقادیر که با کاما از هم جدا شدهاند پشتیبانی میکند، بنابراین گزارش میتواند در واقع شامل دادههای مربوط به ویدیوهای زیادی باشد.
علاوه بر این، اگر فیلتر video چندین مقدار را مشخص کند، video نیز میتواند به عنوان یک بُعد مشخص شود. این بدان معناست که پارامتر
dimensionsاز مقادیرdeviceType,videoوday,deviceType,videoنیز پشتیبانی میکند.- اگر صاحب کانال ، ویدیو را در فهرست ابعاد قرار دهد، آنگاه معیارها مقادیر جداگانهای را برای هر ویدیو مشخص میکنند. (در تاریخ ۱ ژوئن ۲۰۱۵، ویدیوی XYZ چند بار در کنسول بازی مشاهده شده است؟)
- اگر صاحب کانال ، ویدیو را در فهرست ابعاد قرار ندهد، معیارها کل مقادیری را که تمام ویدیوهای مشخص شده را پوشش میدهند، مشخص میکنند. (در تاریخ ۱ ژوئن ۲۰۱۵، ویدیوهای ABC، DEF و XYZ چند بار در کنسول بازی مشاهده شدهاند؟)
تازگی و تأخیر دادهها
اگرچه API یوتیوب آنالیتیکس از کوئریهای هدفمند پشتیبانی میکند، اما دادههای تحلیلی زیربنایی آن به صورت بلادرنگ (real-time) نیستند. پردازش دادهها معمولاً تأخیری بین ۴۸ تا ۷۲ ساعت ایجاد میکند. بنابراین، پاسخهای API حاوی دادههای مربوط به آخرین روزها نیستند و endDate گزارش شما فقط شامل دادههایی تا آخرین روزی است که تمام معیارهای درخواستی به طور کامل پردازش شدهاند.
با توجه به تأخیر دادهها، ممکن است متوجه اختلاف بین دادههای برگردانده شده توسط API و معیارهای بلادرنگ قابل مشاهده در YouTube Studio شوید. اگر برنامه شما به آمار بلادرنگ برای ویدیوهای منفرد، مانند تعداد بازدید فعلی، لایکها یا نظرات نیاز دارد، به جای API YouTube Analytics از متد videos.list در YouTube Data API استفاده کنید.
بازیابی گزارشها
برای بازیابی یک گزارش، یک درخواست GET مجاز به متد reports.query از API ارسال کنید و پارامترهایی را که گزارش مورد نظر برای بازیابی را تعریف میکنند، مشخص کنید.
برای مشاهدهی فهرست گزارشهایی که این API پشتیبانی میکند، به مستندات گزارشهای کانال و گزارشهای مالک محتوا مراجعه کنید. تعریف هر گزارش، مقادیری را که گزارش برای پارامترهای metrics ، dimensions و filters مجاز میداند، مشخص میکند.
بهترین شیوهها
برنامههایی که از API یوتیوب آنالیتیکس استفاده میکنند، باید همیشه از این شیوهها پیروی کنند:
- از ردیف سربرگ پاسخ برای تعیین ترتیب ستونهای گزارش استفاده کنید. برای مثال، فرض نکنید که نماها (views) اولین معیاری هستند که در پاسخ برگردانده میشوند، صرفاً به این دلیل که اولین معیار ذکر شده در توضیحات گزارش هستند. در عوض، از ردیف سربرگ پاسخ برای تعیین اینکه کدام ستون حاوی آن دادهها است، استفاده کنید.
- از API داده یوتیوب برای بازیابی فرادادههای اضافی برای منابع شناساییشده در پاسخهای API تجزیه و تحلیل یوتیوب استفاده کنید. همانطور که در سیاستهای توسعهدهندگان خدمات API یوتیوب (بخشهای III.E.4.b تا III.E.4.d) ذکر شده است، کلاینتهای API باید پس از 30 روز، فرادادههای ذخیرهشده منابع را از آن API حذف یا بهروزرسانی کنند.
معیارهای تجمیعشده و موارد حذفشده
پاسخهای API یوتیوب آنالیتیکس شامل تفکیک معیارها برای موارد حذفشده نیستند. برای مثال، اگر صاحب کانالی ویدیویی را حذف کند، آن ویدیو دیگر در پاسخ API که معیارها را به صورت ویدیو به ویدیو برمیگرداند، فهرست نمیشود. با این حال، گزارشهایی مبنی بر اینکه معیارهای کلی برای مجموعهای از منابع هنوز شامل معیارهای مرتبط با موارد حذفشده هستند، وجود دارد.
برای مثال، فرض کنید صاحب کانال دو گزارش دریافت میکند. گزارش اول، کل بازدیدهای روزانه برای تمام ویدیوهای کانال را در یک دوره زمانی خاص فهرست میکند. گزارش دوم، کل بازدیدهای روزانه را به صورت ویدیو به ویدیو در همان دوره زمانی فهرست میکند.
در این حالت، اعداد موجود در گزارش اول شامل بازدیدهای ویدیوهایی خواهد بود که بعداً حذف شدهاند زیرا گزارش اول شامل مجموع روزانه است. با این حال، گزارش دوم شامل بازدیدهای مرتبط با موارد حذف شده نخواهد بود زیرا گزارش دوم بازدیدها را به صورت ویدیو به ویدیو فهرست میکند. در نتیجه، اگر کانال در دوره زمانی که گزارش پوشش میدهد، ویدیوها را حذف کرده باشد، ممکن است کل تعداد بازدیدهای روزانه گزارش شده در گزارش اول بیشتر از مجموع تعداد بازدیدهای روزانه مختص ویدیو در گزارش دوم باشد.
ناشناسسازی دادهها
برخی از دادههای YouTube Analytics زمانی محدود میشوند که معیارها به آستانه خاصی نرسند. این میتواند در گزارشهای مختلفی اتفاق بیفتد. در عمل، به این معنی است که یک گزارش ممکن است شامل تمام (یا هیچ) دادههای شما نباشد اگر:
یک ویدیو یا کانال در یک بازه زمانی مشخص، ترافیک محدودی دارد،
یا
شما یک فیلتر یا بُعد، مانند منبع ترافیک یا کشور، را انتخاب کردهاید که مقادیر آن با آستانهی خاصی مطابقت ندارند.
در مواردی که دادهها محدود هستند، بسته به نحوه تجمیع دادهها در گزارشهای مختلف، ممکن است بین مجموعهای گزارششده در آنها تفاوت وجود داشته باشد.
برای مثال، فرض کنید صاحب کانال دو گزارش دریافت میکند. گزارش اول کل بازدیدهای یک ویدیوی خاص را فهرست میکند و گزارش دوم کل بازدیدهای آن ویدیو را به تفکیک کشور فهرست میکند. در طول دوره زمانی مشخص شده، فرض کنید که ویدیو ۱۰۰۰ بار مشاهده شده است، که ۵۰۰ بازدید در ایالات متحده، ۴۹۸ بازدید در کانادا و دو بازدید در فرانسه رخ داده است.
در این مثال، گزارش اول نشان میدهد که ویدیو ۱۰۰۰ بار مشاهده شده است. گزارش دوم فقط نشان میدهد که ویدیو ۵۰۰ بار در ایالات متحده و ۴۹۸ بار در کانادا مشاهده شده است. به این ترتیب، بین تعداد کل بازدیدها در دو گزارش تفاوت وجود خواهد داشت. توجه داشته باشید که گزارش دوم هیچ نشانهای مبنی بر اینکه دو بازدید دیگر نیز رخ داده است (یا اینکه بازدیدی در فرانسه رخ داده است) ندارد.
آستانههای واقعی که دادهها در آنها محدود میشوند منتشر نشدهاند و ممکن است به صلاحدید یوتیوب تغییر کنند.
انواع داده محدود
دادههای زیر ممکن است در گزارشهای YouTube Analytics محدود باشند:
- دادههای جمعیتشناختی، مانند سن و جنسیت.
- دادههای جغرافیایی، شامل معیارها یا ابعاد مربوط به کشورها یا مناطقی که بینندگان در آن قرار داشتهاند، مانند کشورها یا مناطق آنها. با این حال، توجه داشته باشید که گزارشها آستانههای جغرافیایی را برای معیارهای درآمد اعمال نمیکنند.
- معیارهای مربوط به منابع ترافیکی خاص، مانند عبارات جستجو یا URL های خارجی که منجر به بازدید از ویدیوهای شما شدهاند. به عنوان مثال، عبارات جستجو و URL هایی که تعداد بازدید بسیار کمی دارند، در گزارشها ظاهر نمیشوند، اگرچه همچنان عبارات و URL هایی را مشاهده خواهید کرد که بینندگان زیادی را به محتوای شما هدایت میکنند.
برای اطلاعات بیشتر در مورد دادههای محدود در گزارشهای YouTube Analytics، به مرکز راهنمایی YouTube مراجعه کنید.
استفاده از سهمیه
هر درخواست API که شما ارسال میکنید، به عنوان یک واحد از سهمیه استفاده API شما محاسبه میشود. محدودیتهای سهمیه در پنل سهمیهها در کنسول API گوگل قابل مشاهده است.