מדדי סרטוני TikTok דרך ה-API: צפיות, זמן צפייה והשלמה
ה-TikTok API for Business מחזיר את המדדים המצטברים של כל פוסט דרך נקודת הקצה GET /business/video/list/. מבקשים כל מדד בשמו בשדה fields: video_views, reach, likes, comments, shares, favorites, total_time_watched, average_time_watched (בשניות), full_video_watched_rate, video_view_retention, impression_sources ופילוחי צופים כמו audience_countries. רוב הספירות מגיעות באיחור של 24 עד 48 שעות ומפסיקות להתעדכן 365 ימים אחרי הפרסום.
easyCoexistence קורא את מדדי סרטון TikTok עם get_social_insights מתוך Claude, ChatGPT או הקוד שלכם: מציינים את השדות שרוצים, כמו video_views, reach או full_video_watched_rate, ונותנים את item_id של הסרטון.
היקף video.insights נדרש לזמן צפייה, להשלמה, לשימור, למקורות תנועה ולפילוחי הצופים, ואילו הספירות הבסיסיות דורשות היקף video.list בלבד.
חוסר פעילות שאחריו עלולים להיעדר מדדים כמו reach, זמן צפייה, מקורות תנועה או audience_countries של סרטון.
רוב הערכים ברשימות audience_countries וברשימות audience_cities של סרטון.
זמן העיכוב הטיפוסי של video_views, likes, reach, זמן צפייה ומקורות תנועה, בשעון UTC, שהוא השעון העולמי המתואם.
אילו מדדים יש לסרטון?
GET /business/video/list/ מחזיר אותם לכל פוסט שנבחר בשדה fields, מצטברים לאורך כל חייו של הפוסט ולא בחלון של 60 ימים שממנו נמשכים מדדי החשבון. הרשאת video.insights נדרשת לנתוני הצפייה, ההשלמה והשימור, וספירות כמו צפיות ולייקים דורשות את video.list על האסימון.
איך מבקשים אותם?
מציינים אותם בשדה fields, כמערך JSON שחייב לכלול את item_id בכל פעם שמופיעים בו יותר משדה אחד, ובוחרים פוסטים בעזרת filters.video_ids; בלי הסינון נקודת הקצה עוברת על פוסטי החשבון, עד 20 בכל פעם:
curl -G 'https://business-api.tiktok.com/open_api/v1.3/business/video/list/' \
-H 'Access-Token: <ACCESS_TOKEN>' \
--data-urlencode 'business_id=<OPEN_ID>' \
--data-urlencode 'fields=["item_id","video_views","reach","video_duration","total_time_watched","average_time_watched","full_video_watched_rate","impression_sources","audience_countries"]' \
--data-urlencode 'filters={"video_ids":["<ITEM_ID>"]}'איך נראית התשובה?
מערך videos עם אובייקט אחד לכל פוסט ובו השדות שביקשתם, ובנוסף cursor וגם has_more לדפדוף. הדוגמה המקוצרת של TikTok מראה את היחידות: זמני צפייה בשניות עד שלוש ספרות אחרי הנקודה, ואת full_video_watched_rate, שערכו כאן 0.0237, כשבר עשרוני:
{
"code": 0,
"message": "OK",
"request_id": "2021080307532501024502410704A7306F",
"data": {
"videos": [
{
"item_id": "6990565363377392901",
"video_views": 1231,
"reach": 154,
"likes": 10,
"comments": 2,
"shares": 0,
"video_duration": 20.0,
"total_time_watched": 695.942,
"average_time_watched": 4.118,
"full_video_watched_rate": 0.0237,
"impression_sources": [
{ "impression_source": "For You", "percentage": 0.8983 },
{ "impression_source": "Personal Profile", "percentage": 0.0904 },
{ "impression_source": "Follow", "percentage": 0.0113 }
],
"audience_countries": [
{ "country": "US", "percentage": 0.7574 },
{ "country": "GB", "percentage": 0.1775 }
]
}
],
"cursor": 0,
"has_more": false
}
}מה משמעות מקורות התנועה?
impression_sources מדרג מאיפה הצופים גילו את הפוסט, מהנתח הגדול ביותר אל הקטן ביותר, וכל ערך הוא impression_source עם האחוז שלו. TikTok מתעד את הערכים הבאים:
- For You: פיד ה-For You, פיד ההמלצות.
- Follow: פיד העוקבים.
- Sound: דפי צליל.
- Personal Profile: דפי פרופיל אישי.
- Search: דפי חיפוש.
- Direct Message: הודעות ישירות, כאשר TikTok Studio מציג את הנתונים האלה לחשבון.
- Others: כל השאר.
אילו פילוחי צופים יש?
ארבעה פילוחים, כולם דורשים את הרשאת video.insights, והם מתארים את האנשים שצפו באותו פוסט ולא את עוקבי החשבון:
audience_genders: חלקי הצופים לפי מין, כשהערכים Female, Male או Other מופיעים בתשובה.audience_countries: עד 10 מדינות או אזורים, כשכל אחד מסומן בקוד ISO 3166-1 בן שתי אותיות.audience_cities: עד 10 ערים, בשמות כמו הדוגמה US Cincinnati, שהיא קוד מדינה ואחריו עיר.audience_types: סוגי הצופים, בערכיםNEW_VIEWER,RETURN_VIEWER,FOLLOWER_PERCENTולעומתםNON_FOLLOWER_PERCENT, כפי שמוגדר אצלם.
אילו מדדים תלויים בסוג החשבון?
כמה קליקים וביקורים בפרופיל מגיעים מ-Business Analytics של TikTok, ודורשים יותר מחשבון אישי. profile_views, ביקורי הפרופיל שפוסט הניע, דורש חשבון עם Advanced Access או חשבון עסקי מאומת. website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks ואת address_clicks דורשים חשבון עסקי מאומת.
למה מדד יכול להיעדר או להתעכב?
כי TikTok מחשב את רוב המדדים במצב לא מקוון ומתוך TikTok Analytics בלבד. הספירות ומדדי הצפייה בדרך כלל מתעכבים 24 עד 48 שעות, בעוד שהשדות item_id, caption וגם links מופיעים בזמן אמת. הגעה, זמן צפייה, מקורות תנועה ואת audience_countries עלולים להיעדר לסרטון שלא נצפה, לא קיבל לייקים, תגובות או שיתופים במשך 7 ימים; לפי TikTok, מומלץ ליצור איתו אינטראקציה ולנסות שוב אחרי 24 עד 48 שעות. הנתונים מפסיקים להתעדכן 365 ימים אחרי הפרסום, ופוסטים שסוננו בשל הפרות, כמו זכויות יוצרים במוזיקה, אינם מוחזרים.
איך easyCoexistence קורא את מדדי הסרטון?
הכלי get_social_insights מקבל את item_id של הסרטון בתור object_id ואת שמות השדות בתור metrics, ומחזיר את השדות של אותו פוסט, בחיפוש בין 20 הפוסטים האחרונים של החשבון. לפוסט ישן יותר, הקוד שלכם פונה אל business/video/list/ ומעביר את fields וגם את filters.video_ids כפרמטרים, עם האסימון מ-get_social_credentials.
get_social_insights {
"account_id": "<ACCOUNT_ID>",
"object_id": "<ITEM_ID>",
"metrics": ["video_views", "reach", "average_time_watched", "full_video_watched_rate", "impression_sources"]
}טעויות נפוצות
- להניח שיש סקאלה אחת לכל האחוזים. הדוגמאות של TikTok מציגות את impression_sources כשברים שסכומם 1, ואילו הדוגמה של audience_cities מציגה ערכים כמו 17.4921, בסקאלה אחרת.
- לבקש כמה שדות בלי item_id. ההפניה של TikTok מזהירה שבקשה כזו עלולה להיכשל.
- לצפות לקבל reach לסרטון ישן ושקט. TikTok יכול להשאיר ריקים את reach, זמן הצפייה ומקורות התנועה אחרי 7 ימים בלי צפיות, לייקים, תגובות או שיתופים.
- השוואת מדדי פוסט למדדי חשבון יומיים. המדדים של פוסט מכסים את כל חייו, ואילו מדדי החשבון מגיעים לפי יום עד 60 ימים.
לפוסטים ישנים, get_social_credentials נותן לקוד שלכם את האסימון של החשבון. US$ 9 עד US$ 0.75 לחיבור לחודש, יורד ככל שמוסיפים חיבורים, עם 3 הימים הראשונים בחינם.
שאלות נפוצות
האם ה-TikTok API מחזיר זמן צפייה לכל סרטון?
כן. לאסימון עם הרשאת video.insights, נקודת הקצה /business/video/list/ מחזירה את total_time_watched וגם את average_time_watched בשניות.
איך מקבלים את שיעור ההשלמה של סרטון TikTok דרך ה-API?
כדי לקבל אותו, מבקשים את full_video_watched_rate בשדה fields, דרך נקודת הקצה /business/video/list/, ו-TikTok מגדיר אותו כאחוז הצופים שמסיימים את הסרטון.
למה reach וזמן הצפייה ריקים לסרטון ה-TikTok שלי?
TikTok יכול להשמיט אותם לסרטון בלי צפיות, לייקים, תגובות או שיתופים ב-7 הימים האחרונים, ונתונים עדכניים מתעכבים 24 עד 48 שעות.
האם ה-API יכול להחזיר מדדים לסרטון TikTok אחד מסוים?
כן. מעבירים את המזהה שלו דרך filters.video_ids, ובשדה fields נותנים את item_id ואת המדדים הרצויים.
המשיכו לקרוא
מחברים את הערוץ הראשון שלכם תוך שתי דקות.
בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.
- 3 ימי ניסיון חינם
- ביטול בכל עת
- רק ממשקי API רשמיים
- ניטור 24/7
נבדק ב-