تسجيل الدخولابدأ الفترة التجريبية المجانية
easyCoexistence واجهات API الرسمية

مقاييس فيديو TikTok عبر واجهة برمجة التطبيقات (API): المشاهدات ووقت المشاهدة والإكمال

تعيد API TikTok للأعمال مقاييس كل منشور منذ نشره من 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.

7 days

فترة عدم النشاط التي قد تختفي بعدها الوصول ووقت المشاهدة ومصادر الظهور وaudience_countries لفيديو ما.

10

معظم العناصر في قائمتي audience_countries وaudience_cities لفيديو ما.

24 to 48 h

التأخير المعتاد لـ video_views وlikes وreach ووقت المشاهدة ومصادر الظهور، بالتوقيت العالمي UTC.

ما المقاييس التي يملكها الفيديو؟

تعيد GET /business/video/list/ هذه المقاييس لكل منشور مذكور في fields، مجمّعةً على عمر المنشور كاملًا لا على نافذة الستين يومًا لمقاييس الحساب. تحتاج الأرقام مثل المشاهدات والإعجابات إلى النطاق video.list في رمز الوصول (token)، بينما تحتاج أرقام المشاهدة والإكمال والاحتفاظ إلى النطاق video.insights:

video_viewsViews, counted on the first playback in an impression session
reachPeople who watched the post at least once
likes, comments, sharesLifetime totals; shares include sends to friends inside TikTok
favoritesTimes the post was added to favorites
total_time_watchedSeconds viewers spent watching, in total
average_time_watchedAverage seconds viewers spent watching
full_video_watched_rateShare of viewers who finished the video
video_view_retentionShare of viewers still watching at each second
impression_sourcesWhere viewers found the post, by share
new_followersViewers who started following the account
engagement_likesShare of viewers who liked at each second
video_durationLength of the video in seconds

كيف تطلبها؟

سمِّها في fields، وهي مصفوفة JSON يجب أن تتضمن item_id متى ضمّت أكثر من حقل، واختر المنشورات بـ filters.video_ids. وبدون هذا الفلتر، تتصفح نقطة النهاية (endpoint) منشورات الحساب، بحد أقصى 20 في المرة الواحدة:

Metrics for one video
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:

A video's metrics, from TikTok's example
{
  "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: خلاصة Follow.
  • Sound: صفحات الصوت.
  • Personal Profile: صفحات الملف الشخصي.
  • Search: صفحات البحث.
  • Direct Message: الرسائل المباشرة، عندما يعرض TikTok Studio هذه البيانات للحساب.
  • Others: كل ما عدا ذلك.

ما تفصيلات المشاهدين المتاحة؟

أربع تفصيلات، كلها تصف الأشخاص الذين شاهدوا ذلك المنشور لا متابعي الحساب، وكلها تحتاج إلى النطاق video.insights:

  • audience_genders: حصص المشاهدين بحسب الجنس، Female أو Male أو Other.
  • audience_countries: حتى 10 دول أو مناطق، برموز ISO 3166-1 alpha-2.
  • audience_cities: حتى 10 مدن، بصيغة مثل US Cincinnati.
  • audience_types: NEW_VIEWER وRETURN_VIEWER، وFOLLOWER_PERCENT مقابل NON_FOLLOWER_PERCENT.

أي المقاييس يتوقف على نوع الحساب؟

بعض النقرات وزيارات الملف الشخصي تأتي من Business Analytics لدى TikTok، وتتطلب حسابًا تجاريًا لا حسابًا شخصيًا. يحتاج profile_views، وهي زيارات الملف الشخصي التي قادها المنشور، إلى حساب بـ Advanced Access أو حساب Verified Business Account. وتحتاج website_clicks وphone_number_clicks وlead_submissions وapp_download_clicks وemail_clicks وaddress_clicks إلى حساب Verified Business Account.

لماذا قد يغيب مقياس أو يتأخر؟

لأن TikTok تحسب معظمها دون اتصال ومن TikTok Analytics وحدها. تتأخر الأعداد ومقاييس المشاهدة عادةً من 24 إلى 48 ساعة، بينما تُحدَّث item_id والعنوان (caption) والروابط فورًا. وقد تغيب الوصول ووقت المشاهدة ومصادر الظهور و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.

One video's metrics through MCP
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 من أن مثل هذا الطلب قد يفشل.
  • توقّع مقياس الوصول لفيديو قديم هادئ. قد تترك TikTok الوصول ووقت المشاهدة ومصادر الظهور فارغة بعد 7 أيام دون مشاهدات أو إعجابات أو تعليقات أو مشاركات.
  • مقارنة مقاييس المنشور بمقاييس الحساب اليومية. تغطي أرقام المنشور عمره كاملًا، بينما تأتي مقاييس الحساب يومًا بيوم لمدة تصل إلى 60 يومًا.
إنجاز ذلك باستخدام EasyCoexistence

وللمنشورات الأقدم، يمنح get_social_credentials الكود الخاص بك token الحساب. من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، وينخفض كلما أضفت اتصالات، مع فترة تجريبية مجانية لمدة 3 أيام.

الأسئلة الشائعة

هل تعطي واجهة TikTok وقت المشاهدة لكل فيديو؟

نعم. تأتي total_time_watched وaverage_time_watched بالثواني من /business/video/list/، للرموز التي تملك النطاق video.insights.

كيف أحصل على نسبة إكمال فيديو TikTok عبر API؟

اطلب full_video_watched_rate في fields على /business/video/list/. وتعرّفها TikTok بأنها نسبة المشاهدين الذين أتموا مشاهدة الفيديو.

لماذا يكون الوصول ووقت المشاهدة فارغين لفيديو TikTok الخاص بي؟

قد تحذفهما TikTok لفيديو بلا مشاهدات أو إعجابات أو تعليقات أو مشاركات خلال آخر 7 أيام، والبيانات الحديثة تتأخر من 24 إلى 48 ساعة.

هل تعيد API مقاييس فيديو TikTok واحد بعينه؟

نعم. مرّر معرّفه في filters.video_ids، مع item_id والمقاييس التي تريدها في fields.

تابع القراءة

ديموغرافيا الجمهور في TikTok عبر واجهة برمجة التطبيقات (API)ديموغرافيا متابعي الحساب في واجهة TikTok للأعمال: العمر والجنس والدولة والمدينة والنشاط بالساعة، وشرط 100 متابع.عرض فيديوهات حساب TikTok عبر واجهة برمجة التطبيقات (API)كيف تعرض واجهة TikTok للأعمال منشورات الحساب عبر /business/video/list/، مع حقوله والتصفح بالمؤشر و20 منشورا في الصفحة والتصفية بالمعرّف.واجهة TikTok Analytics API: مؤشرات الحساب ومقاييس الفيديومقاييس TikTok التي تعيدها واجهة API الخاصة بالأعمال: المتابعون والمشاهدات والإعجابات يوميًا للحساب، والمشاهدات والإعجابات والتعليقات والمشاركات لكل فيديو.نطاقات TikTok API for Business: ما يفتحه كل إذنالأذونات التي تعمل بها TikTok Accounts API بأسمائها الرسمية: ما تفتحه كل منها، ونطاقات الرمز لكل حقل، وكيفية التحقق من الرمز.كيف تنشر فيديو على TikTok عبر واجهة برمجة التطبيقات (API)انشر فيديو على TikTok عبر واجهة TikTok للأعمال، مع نقطة النشر وجسم JSON وshare_id المُعاد وطلب الحالة، بأمثلة curl وPython.

اربط قناتك الأولى في دقيقتين.

لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.

  • 3 أيام مجانًا
  • إلغاء في أي وقت
  • واجهات API الرسمية فقط
  • مراقبة على مدار الساعة 24/7

تم التحقق في