הערה:Content owner reports are only accessible to YouTube content partners who participate in the YouTube Partner Program.
בדף הזה מפורטים דוחות שבעלי תוכן יכולים לאחזר באמצעות ה-API של YouTube Analytics. דוחות של בעלי תוכן מכילים מדדים של ערוצים שמקושרים לבעלי תוכן מסוים ב-YouTube. מדדים הם מדידות ספציפיות של פעילות המשתמשים, ביצועי המודעות או ההכנסה המשוערת.
דוחות וידאו מכילים מדדים של פעילות המשתמשים, ביצועי המודעות והכנסות משוערות מסרטונים בערוצים של בעלי התוכן.
דוחות פלייליסטים מספקים נתונים סטטיסטיים שקשורים באופן ספציפי לצפיות בסרטונים שמתרחשות בהקשר של פלייליסט. בדוחות של פלייליסטים נעשה שימוש ברבים מהמאפיינים והמסננים של דוחות הסרטונים.
דוחות ביצועי מודעות מכילים מדדים שקשורים להכנסות ולביצועי המודעות. הם משתמשים במאפיין adType כדי לקבץ מדדים על סמך סוגי המודעות שהוצגו במהלך ההפעלה של הסרטונים. בקטע דוחות ביצועי מודעות מוסבר על שני סוגי מדדי ביצועי המודעות ש-API תומך בהם.
אחזור דוח
כדי לאחזר דוח של בעלי תוכן, צריך לקרוא ל-method reports.query של ה-API ולהגדיר את ערך הפרמטר ids בבקשת ה-API כ-contentOwner==OWNER_NAME, כאשר OWNER_NAME מציין את המזהה של בעלי התוכן. אם אתם לא בטוחים לגבי הערך, תוכלו לפנות למנהל השותפים.
אישור
כל הבקשות ל-YouTube Analytics API חייבות לקבל הרשאה. במאמר מדריך ההרשאות מוסבר איך משתמשים בפרוטוקול OAuth 2.0 כדי לאחזר אסימוני הרשאה.
הבקשות של YouTube Analytics API משתמשות בהיקפי ההרשאה הבאים:
הצגת דוחות כספיים של YouTube Analytics לתוכן שלכם ב-YouTube. ההיקף הזה מספק גישה למדדי פעילות המשתמשים ולמדדים של ההכנסות המשוערות וביצועי המודעות.
https://www.googleapis.com/auth/youtube
ניהול חשבון YouTube. ב-YouTube Analytics API, בעלי ערוצים משתמשים בהיקף הזה כדי לנהל קבוצות ופריטים מקובצים ב-YouTube Analytics.
https://www.googleapis.com/auth/youtubepartner
הצגה וניהול של נכסי YouTube והתכנים המשויכים ב-YouTube. ב-YouTube Analytics API, בעלי תוכן משתמשים בהיקף הזה כדי לנהל קבוצות ופריטים מקובצים ב-YouTube Analytics.
הערה: כדי לגשת למדדים שמסומנים בכוכבית (*), נדרש אסימון הרשאה שמעניק גישה להיקף https://www.googleapis.com/auth/yt-analytics-monetary.readonly.
בטבלאות שמפורטות בהן הדוחות הנתמכים מפורטים המסננים שאפשר להשתמש בהם בכל דוח נתון. בתיאורים, המסננים שמופיעים בסוגריים הם אופציונליים. לדוגמה, אם בדוח מופיעה האפשרות video(,country) כאפשרות סינון, אפשר לסנן את הדוח כך שיכלול רק נתונים לגבי סרטון ספציפי, או רק נתונים לגבי סרטון ספציפי במדינה ספציפית.
ה-API תומך גם באפשרות לציין כמה ערכים למסננים video, playlist ו-channel. אם מציינים כמה ערכים לאחד מהמסננים האלה, אפשר גם להוסיף את המסנן הזה לרשימת המאפיינים שציינתם בבקשה. זה נכון גם אם המסנן לא מופיע כמאפיין נתמך בדוח מסוים.
בהגדרת הפרמטר filters מוסבר באופן מלא איך לסנן תוצאות API לפי ערך ספציפי או קבוצת ערכים ספציפית.
הסבר על טבלאות דוחות
בקטע הזה מוסבר הפורמט והטרמינולוגיה שבהם נעשה שימוש בטבלאות שמגדירות את הדוחות שתומכים ב-API. בטבלה הבאה מפורטים המאפיינים, המדדים והמסננים הנתמכים בדוח הווידאו 'פרטי ההפעלה' באמצעות מאפיין הזמן והמדד averageViewPercentage.
הטבלה מכילה שתי שורות למאפיינים, שורה אחת למדדים ושלוש שורות למסננים. לגבי מאפיינים ומסננים, אפשר לשלב ערכים מכל שורה בבקשת API כל עוד השילוב עומד בכללי השימוש בטבלה. לדוגמה, הערכים החוקיים של הפרמטר dimensions בדוח הזה הם:
dimensions=day
dimensions=day,subscribedStatus
dimensions=month,subscribedStatus,youtubeProduct
dimensions=month,youtubeProduct
עם זאת, ערך הפרמטר day,month לא חוקי כי הוא כולל שני מאפיינים מבוססי-זמן, ובבקשה צריך להשתמש ב-0 או ב-1.
מונחים של טבלת דוחות
בטבלאות נעשה שימוש במונחים הבאים כדי לציין אם המאפיינים נדרשים או אופציונליים:
המונחים הבאים מציינים שצריך להזין ערך:
חובה: חובה לכלול את הערך.
שימוש ב-1 בדיוק: חובה לכלול ערך אחד מהקבוצה.
שימוש באחד או יותר: אפשר לכלול כל ערך מהקבוצה או את כולם, אבל חובה לכלול לפחות ערך אחד.
המונחים הבאים מציינים שהערך הוא אופציונלי:
אופציונלי: יש לכם אפשרות לכלול את הערך.
שימוש ב-0 או ב-1: יש לכם אפשרות לכלול ערך אחד מהקבוצה.
שימוש ב-0 או יותר: יש לכם אפשרות לכלול כל ערך מהקבוצה או את כולם.
חשוב: כל בקשות ה-API לאחזור דוחות של סרטונים של בעלי תוכן חייבות לסנן את הנתונים באמצעות המאפיין video, המאפיין channel, המאפיין group או שילוב נתמך של המאפיינים claimedStatus ו-uploaderType. (בחלק מהדוחות לא תהיה תמיכה בכל האפשרויות האלה). השילובים הנתמכים, שמופיעים גם בהגדרה של המאפיין uploaderType, הם:
uploaderType==self
claimedStatus==claimed
claimedStatus==claimed;uploaderType==self
claimedStatus==claimed;uploaderType==thirdParty
דוחות סרטונים
נתונים סטטיסטיים בסיסיים
נתונים סטטיסטיים בסיסיים (כולל מספר המנויים)
הדוח הזה מספק נתונים סטטיסטיים לגבי פעולות של משתמשים בכל הערוצים של בעלי התוכן. אפשר לסנן את הדוח כך שיציג רק נתונים לגבי סרטון או מדינה ספציפיים. אפשר גם להשתמש בו כדי לאחזר נתונים סטטיסטיים רק לגבי תוכן שהוגשה לגביו תלונה על הפרת זכויות יוצרים, כולל תוכן שהוגשה לגביו תלונה על הפרת זכויות יוצרים והועלה על ידי בעלי התוכן, צדדים שלישיים או שניהם.
הדוח הזה מספק נתונים סטטיסטיים לגבי מדינה מסוימת בארה"ב או לגבי מחוז קולומביה. שימו לב שהדוח הזה תומך רק בקבוצת משנה של המדדים שזמינים בדוח הספציפי למדינה שמתואר למעלה.
הדוח הזה מספק נתונים סטטיסטיים לגבי פעולות של משתמשים בכל הערוצים של בעלי התוכן, במרווחי זמן ספציפיים. אפשר לסנן את הדוח כך שיציג רק נתונים לגבי סרטון או מדינה ספציפיים.
הדוח הזה מספק נתונים סטטיסטיים לגבי מדינה מסוימת בארה"ב או לגבי מחוז קולומביה. שימו לב שהדוח הזה תומך רק בקבוצת משנה של המדדים שזמינים בדוח הספציפי למדינה שמתואר למעלה.
הדוח הזה מספק נתונים סטטיסטיים לגבי פעילות המשתמשים לפי מדינה, לכל הערוצים של בעלי התוכן. אפשר לסנן את הדוח כך שיציג רק נתונים לגבי סרטון או ערוץ ספציפיים.
הערה: כדי להציג את הדוח הזה, צריך להגדיר את הפרמטר maxResults לערך שלם של 250 או פחות. בניגוד לרוב הדוחות האחרים, בדוח הזה צריך לציין גם ערך לפרמטר הבקשה sort.
הדוח הזה מספק נתונים סטטיסטיים על פעילות המשתמשים לפי עיר.
בדוח הזה מוצגים מדדי פעילות המשתמשים לגבי צופים מנויים וצופים שלא מנויים. אפשר לקבץ את הנתונים הסטטיסטיים לפי תקופת זמן (יום או חודש), ואפשר גם לסנן את הדוח לפי מדינה, יבשת או subContinent.
מאפיין הזמן – day או month – הוא אופציונלי בדוחות האלה, כי בכל מקרה צריך להשתמש בפרמטרים של הבקשה startDate ו-endDate כדי לציין את טווח התאריכים שבו יתבצע הדוח. המאפיין, אם הוא קיים, מציין שרוצים שהנתונים בדוח יקובצו לפי יום, חודש וכו'.
פרטי ההפעלה עם מאפיין זמן אופציונלי ונתונים סטטיסטיים של liveOrOnDemand
הדוח הזה מספק נתונים סטטיסטיים מפורטים על ההפעלה של מודעות במרווחי זמן ספציפיים. הוא תומך במימד (ובמסנן) liveOrOnDemand.
הערה: כדי להציג את הדוח הזה, צריך להגדיר את הפרמטר maxResults לערך שלם של 25 או פחות. בניגוד לרוב הדוחות האחרים, בדוח הזה צריך לציין גם ערך לפרמטר הבקשה sort.
בדוח הזה מוצגים נגני הווידאו המוטמעים שהניבו את מספר הצפיות או את משך הצפייה הגבוהים ביותר בתוכן של בעלי תוכן. כשמאחזרים את הדוח הזה, צריך להגדיר את המסנן insightPlaybackLocationType לערך EMBEDDED.
הדוח הזה מציג נתונים מצטברים של נתוני צפייה על סמך האופן שבו הצופים הגיעו לתוכן הסרטונים שלכם. לדוגמה, הוא מזהה את מספר הצפיות שנובעות מחיפוש ב-Google או מקישור לסרטון קשור.
הערה: הדוח הזה מחזיר הודעת שגיאה אם המכפלה של מספר הסרטונים שבוצעה להם שאילתה x מספר הימים בטווח התאריכים חורגת מ-50,000. לדוגמה, שאילתה שמאחזרת נתונים של 500 מזהי וידאו יכולה לבקש נתונים של עד 100 ימים. כדי להפחית את מספר השורות שחוזרות בתגובה לבקשה, אפשר לפצל את השאילתה לכמה שאילתות שמציינות פחות סרטונים או להגדיר טווחי תאריכים קצרים יותר.
הערה: כדי להציג את הדוח הזה, צריך להגדיר את הפרמטר maxResults לערך שלם של 25 או פחות. בניגוד לרוב הדוחות האחרים, בדוח הזה צריך לציין גם ערך לפרמטר הבקשה sort.
הדוח הזה מציג סיכום של נתוני הצפייה על סמך מקורות ההפניה שהניבו את מספר הצפיות הגבוה ביותר בתוכן של בעלי התוכן. ההפניות מסווגות לפי סוג מקור התנועה, וההגדרה של המאפיין insightTrafficSourceDetail מאפשרת לזהות את מקורות התנועה שעבורם הדוח זמין. לדוגמה, אם מגדירים את המסנן insightTrafficSourceType לערך ADVERTISING, בדוח יופיעו סוגי המודעות שהניבו הכי הרבה צפיות או זמן צפייה בתוכן של בעלי התוכן.
הערה: יש תמיכה בדוח הזה רק לגבי מקורות תנועה ספציפיים. מקורות התנועה VIDEO_REMIXES, NOTIFICATION, END_SCREEN, CAMPAIGN_CARD, VIDEO_REMIXES ו-NO_LINK_EMBEDDED הם חלק מהמקורות שלא נתמכים.
סוג המכשיר ומערכת ההפעלה
סוג מכשיר
הדוח הזה מציג נתונים מצטברים של נתוני צפייה על סמך סוג המכשיר שבו הצופים השתמשו כשצפו בתוכן שלכם. לדוגמה, הוא מזהה את מספר הצפיות שהתרחשו בטאבלטים או במסופי משחקים.
הדוח הזה מציג נתונים סטטיסטיים מצטברים של צפייה על סמך מערכות ההפעלה וסוגים של המכשירים של הצופים. לדוגמה, הוא מזהה את מספר הצפיות שהתרחשו בטאבלטים עם Android או במחשבים עם Windows.
לדוגמה, אם בדוח נעשה שימוש במאפיין subscribedStatus, המערכת מחזירה נתונים של viewerPercentage שסך כל הערכים שלהם הוא 100% לצפיות של מנויים וגם נתונים של viewerPercentage שסך כל הערכים שלהם הוא 100% לצפיות של משתמשים שלא רשומים כמנויים. (הערך הכולל של כל השדות viewerPercentage בדוח הוא 200 אחוזים).
הדוח הזה מודד את היכולת של סרטון לשמר את הקהל שלו. המאפיין elapsedVideoTimeRatio מודד את משך הזמן שחלף בסרטון עבור ערכי המדדים התואמים. המדדים audienceWatchRatio ו-relativeRetentionPerformance מספקים שני מדדים שמראים באיזו מידה הסרטון מצליח לשמר את רמת העניין של הצופים. הערך הראשון הוא ערך מוחלט, והערך השני מראה את הביצועים של הסרטון ביחס לביצועים של סרטונים אחרים ב-YouTube באורך דומה.
הערה: בדוחות שימור הקהל אין אפשרות לציין רשימה של ערכים מופרדים בפסיקים עבור המסנן video. הערך חייב לציין מזהה סרטון יחיד.
הערה: בדוחות האלה צריך להגדיר את הפרמטר maxResults לערך שלם של 200 או פחות. לפני 1 בינואר 2013, הנתונים זמינים רק לגבי 10 הסרטונים המובילים. בניגוד לרוב הדוחות האחרים, בדוחות האלה צריך לציין גם ערך לפרמטר הבקשה sort.
הסרטונים המובילים באופן כללי, לפי מדינה, לפי יבשת או לפי תת-יבשת (200 תוצאות לכל היותר)
בדוח הזה מפורטים הסרטונים המובילים של בעלי התוכן, על סמך קריטריונים ספציפיים לסינון ולמיון.
הסרטונים המובילים באופן כללי לפי מדינה בארה"ב (200 תוצאות לכל היותר)
בדוח הזה מפורטים הסרטונים המובילים של בעלי התוכן במדינה מסוימת בארה"ב או במחוז קולומביה. שימו לב שהדוח הזה תומך רק בקבוצת משנה של המדדים שזמינים בדוח הספציפי למדינה שמתואר למעלה.
הסרטונים המובילים לצופים רשומים או לצופים שלא רשומים(<= 200 תוצאות)
בדוח הזה מפורטים הסרטונים המובילים בקרב צופים שהם מנויים או צופים שלא רשומים כמנויים. אפשר לסנן את הדוח כדי להציג את הסרטונים המובילים לפי מדינה, יבשת או subContinent. הדוח הקודם מאפשר לאחזר את הסרטונים המובילים במדינה מסוימת בארה"ב לצופים שנרשמו כמנויים או לצופים שלא נרשמו כמנויים, אבל הוא תומך בפחות מדדים בהשוואה לדוח הזה.
הסרטונים המובילים לפי מוצר של YouTube (200 תוצאות לכל היותר)
בדוח הזה מפורטים הסרטונים המובילים, והוא תומך בפרטים על ההפעלה ובמסננים גיאוגרפיים. הדוח הזה דומה לדוח הקודם, אבל הוא תומך בפחות מדדים ומוסיף תמיכה במסנן youtubeProduct.
הסרטונים המובילים עם מסננים של פרטי ההפעלה (200 תוצאות לכל היותר)
בדוח הזה מפורטים הסרטונים המובילים של בעלי התוכן, וסינון מתבצע לפי מאפיין אחד או יותר של פרטי ההפעלה: liveOrOnDemand, subscribedStatus ו-youtubeProduct. הדוח תומך גם בסינון לפי אזור.
דוחות הפלייליסטים מכילים מדדים שקשורים לפעילות המשתמשים בסרטונים בפלייליסטים של בעלי הערוץ. יש שתי גרסאות של הדוחות האלה, וכל דוח זמין מתואר בקטעים הבאים:
בכרטיסייה מומלץ בכל קטע מתואר פורמט הבקשה המועדף ל-API לאחזור הדוח המתאים. הדוחות המומלצים תומכים בקבוצה מורחבת של מדדים, שכוללת גם מדדים נצברים של סרטונים וגם מדדים בפלייליסט. בפורמט הבקשה הזה לא נעשה שימוש במאפיין isCurated.
בכרטיסייה Using isCurated בכל קטע מתוארים פורמטים ישנים יותר של בקשות API שבהם המאפיין isCurated נדרש. הדוחות האלה תומכים רק במדדים בפלייליסט. חשוב לזכור שהמאפיין isCurated הוצא משימוש בכל הדוחות. בהערת האזהרה שבהמשך מוסבר לוח הזמנים להוצאה משימוש.
בהודעת האזהרה הבאה מוסבר בפירוט רב יותר על השינויים בין שתי הגרסאות של הדוח.
מדדים מצטברים של סרטונים
המדדים האלה מספקים מדדים של פעילות משתמשים וחשיפות שמצטברים לכל הסרטונים בפלייליסט ששייכים גם לערוץ שהפלייליסט בבעלותו. המדדים של סרטונים בבעלות של ערוצים אחרים לא נכללים בצבירה. כתוצאה מכך, אם ערוץ יוצר פלייליסט שמכיל רק סרטונים בבעלות של ערוצים אחרים, בדוחות של הפלייליסטים האלה לא יופיעו ערכים של המדדים האלה.
המדדים האלה משקפים את הפעילות וההתעניינות של המשתמשים בהקשר של דף הפלייליסט. המדדים האלה כוללים צפיות בכל הסרטונים בפלייליסט, ללא קשר לערוץ שבבעלותו הם נמצאים, אבל נספרות רק צפיות שהתרחשו בהקשר של הפלייליסט.
הדוח הזה מספק נתונים סטטיסטיים לגבי האינטראקציות של המשתמשים עם הסרטונים בפלייליסטים של הערוצים של בעלי התוכן, במרווחי זמן ספציפיים. אפשר לסנן את הדוח כך שיציג רק נתונים לגבי פלייליסט או ערוץ ספציפיים.
הערה: כדי להציג את הדוח הזה, צריך להגדיר את הפרמטר maxResults לערך שלם של 25 או פחות. בניגוד לרוב הדוחות האחרים, בדוח הזה צריך לציין גם ערך לפרמטר הבקשה sort.
הדוח הזה מאפשר לזהות את נגני הווידאו המוטמעים שהניבו את מספר הצפיות או את זמן הצפייה הגבוהים ביותר בפלייליסטים של בעלי תוכן.
הדוח הזה מציג סיכום של נתוני הצפייה על סמך האופן שבו הצופים הגיעו לתוכן של הפלייליסט. לדוגמה, הוא מזהה את מספר הצפיות שנבעו מחיפוש ב-Google או מדף ערוץ.
הערה: כדי להציג את הדוח הזה, צריך להגדיר את הפרמטר maxResults לערך שלם של 25 או פחות. בניגוד לרוב הדוחות האחרים, בדוח הזה צריך לציין גם ערך לפרמטר הבקשה sort.
בדוח הזה מוצגים נתונים סטטיסטיים מצטברים של צפיות על סמך מקורות ההפניה שהניבו את מספר הצפיות הגבוה ביותר בפלייליסטים של בעלי התוכן. ההפניות מסווגות לפי סוג מקור התנועה, וההגדרה של המאפיין insightTrafficSourceDetail מאפשרת לזהות את מקורות התנועה שעבורם הדוח זמין. לדוגמה, אם מגדירים את המסנן insightTrafficSourceType לערך ADVERTISING, בדוח יופיעו סוגי המודעות שהניבו את מספר הצפיות או זמן הצפייה הגבוה ביותר בפלייליסטים של בעלי התוכן.
הערה: יש תמיכה בדוח הזה רק לגבי מקורות תנועה ספציפיים. מקורות התנועה VIDEO_REMIXES, NOTIFICATION, END_SCREEN, CAMPAIGN_CARD, VIDEO_REMIXES ו-NO_LINK_EMBEDDED הם חלק מהמקורות שלא נתמכים.
סוג המכשיר ומערכת ההפעלה
סוג המכשיר לפלייליסטים
הדוח הזה מציג נתונים סטטיסטיים נצברים של צפייה על סמך סוג המכשיר שבו הצופים השתמשו כדי לצפות בתוכן של הפלייליסט. לדוגמה, הוא מזהה את מספר הצפיות שהתרחשו במכשירים ניידים או בקונסולות משחקים.
הדוח הזה מצטבר נתונים סטטיסטיים של צפייה על סמך מערכות ההפעלה של הצופים. לדוגמה, הוא מזהה את מספר הצפיות בפלייליסטים שהתרחשו במכשירי Android או ב-PlayStation.
הדוח הזה מציג נתונים סטטיסטיים מצטברים של צפייה על סמך מערכות ההפעלה וסוגים של המכשירים של הצופים. לדוגמה, הוא מזהה את מספר הצפיות בפלייליסטים שהתרחשו בטאבלטים עם Android או במחשבים עם Windows.
לדוגמה, דוח שמשתמש במאפיין subscribedStatus מחזיר נתוני viewerPercentage שסך הכול שלהם הוא 100% עבור צפיות של מנויים וגם נתוני viewerPercentage שסך הכול שלהם הוא 100% עבור צפיות של משתמשים שלא רשומים כמנויים. (הערך הכולל של כל השדות viewerPercentage בדוח הוא 200 אחוזים).
אפשר להשתמש במסננים כדי לוודא שהדוח מכיל רק נתונים של viewerPercentage לערך אחד (או לשילוב של ערכים) של מאפייני פרטי ההפעלה.
פלייליסטים מובילים
הערה: בדוחות האלה צריך להגדיר את הפרמטר maxResults לערך שלם של 200 או פחות. לפני 1 בינואר 2013, הנתונים זמינים רק לגבי 10 הפלייליסטים המובילים. בניגוד לרוב הדוחות האחרים, בדוחות האלה צריך לציין גם ערך לפרמטר הבקשה sort.
בדוח הזה מוצגים הפלייליסטים המובילים של בעלי התוכן, על סמך קריטריונים ספציפיים לסינון ולמיון.
הערה: כדי להציג דוחות ביצועים של מודעות, נדרש אסימון הרשאה שמעניק גישה להיקף https://www.googleapis.com/auth/yt-analytics-monetary.readonly.
דוחות ביצועי המודעות מספקים מדדים שמבוססים על חשיפות של מודעות שהופעלו במהלך הפעלות של סרטונים. המדדים האלה מתייחסים לכל חשיפה של מודעה, וכל הפעלה של סרטון יכולה להניב כמה חשיפות.
