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، Claude، ChatGPT یا اپنے کوڈ سے get_social_insights کے ذریعے TikTok ویڈیو کے میٹرکس پڑھتا ہے: وہ فیلڈز نام لیں جو چاہیں، جیسے video_views، reach یا full_video_watched_rate، اور ویڈیو کا item_id دیں۔
واچ ٹائم، تکمیل، ریٹینشن، ٹریفک کے ذرائع اور ناظرین کی تفصیلات کے لیے درکار اسکوپ؛ بنیادی گنتیوں کے لیے video.list درکار ہے۔
وہ غیرفعالیت کا دورانیہ جس کے بعد کسی ویڈیو کے ریچ، واچ ٹائم، ٹریفک کے ذرائع اور audience_countries غائب ہو سکتے ہیں۔
کسی ویڈیو کی audience_countries اور audience_cities فہرستوں کے زیادہ تر اندراجات۔
video_views، likes، ریچ، واچ ٹائم اور ٹریفک کے ذرائع کی عام تاخیر، UTC میں۔
کسی ویڈیو کے کون سے میٹرکس ہوتے ہیں؟
GET /business/video/list/ کے ذریعے fields میں نام دی گئی ہر پوسٹ کے یہ میٹرکس ملتے ہیں، جو پوسٹ کی پوری عمر پر مجموعی ہوتے ہیں، اکاؤنٹ میٹرکس کی 60 دن والی ونڈو پر نہیں۔ ویوز اور لائکس جیسی گنتیوں کے لیے ٹوکن پر video.list اسکوپ درکار ہے، جبکہ واچ، تکمیل اور ریٹینشن کے اعداد و شمار کے لیے video.insights:
ان کی درخواست کیسے کریں؟
fields میں JSON array کی صورت میں نام دیں۔ ایک سے زیادہ فیلڈ مانگیں تو 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 array ملتا ہے جس میں ہر پوسٹ کا ایک آبجیکٹ ہوتا ہے اور مانگے گئے فیلڈز ہوتے ہیں، ساتھ ہی صفحہ بندی کے لیے 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: 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۔
کون سے میٹرکس اکاؤنٹ کی قسم پر منحصر ہیں؟
کچھ کلکس اور پروفائل وزٹس TikTok کے Business Analytics سے آتے ہیں، اس لیے عام پرسنل اکاؤنٹ کافی نہیں۔ 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، کیپشن اور لنک حقیقی وقت میں آتے ہیں۔ ریچ، واچ ٹائم، ٹریفک کے ذرائع اور audience_countries اُس ویڈیو کے لیے غائب ہو سکتے ہیں جسے 7 دن تک کسی نے نہ دیکھا، نہ لائک کیا، نہ کمنٹ کیا، نہ شیئر کیا۔ TikTok کا مشورہ ہے کہ اس سے انٹرایکٹ کریں اور 24 سے 48 گھنٹے بعد دوبارہ کوشش کریں۔ اشاعت کے 365 دن بعد ڈیٹا اپڈیٹ ہونا بند ہو جاتا ہے۔ خلاف ورزی، جیسے میوزک کاپی رائٹ، کی وجہ سے فلٹر ہونے والی پوسٹس واپس نہیں آتیں۔
easyCoexistence کسی ویڈیو کے میٹرکس کیسے پڑھتا ہے؟
get_social_insights کے ذریعے: ویڈیو کا item_id object_id کے طور پر دیں اور فیلڈ نام metrics میں، تو یہ اکاؤنٹ کی 20 تازہ ترین پوسٹس میں تلاش کر کے اس پوسٹ کے فیلڈز واپس کرتا ہے۔ پرانی پوسٹ کے لیے آپ کا اپنا کوڈ پیرامیٹرز کے طور پر fields اور filters.video_ids کے ساتھ business/video/list/ کو کال کرتا ہے، 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 کا ریفرنس خبردار کرتا ہے کہ ایسی درخواست ناکام ہو سکتی ہے۔
- کسی پرانی، خاموش ویڈیو سے ریچ کی توقع رکھنا۔ TikTok 7 دن تک ویوز، لائکس، کمنٹس یا شیئرز نہ ہونے پر ریچ، واچ ٹائم اور ٹریفک کے ذرائع خالی چھوڑ سکتا ہے۔
- پوسٹ کے میٹرکس کا روزانہ اکاؤنٹ میٹرکس سے موازنہ کرنا۔ پوسٹ کے اعداد اس کی پوری عمر کا احاطہ کرتے ہیں، جبکہ اکاؤنٹ میٹرکس 60 دن تک روزانہ ملتے ہیں۔
پرانی پوسٹس کے لیے get_social_credentials آپ کے اپنے کوڈ کو اکاؤنٹ کا ٹوکن دیتا ہے۔ US$ 9 سے US$ 0.75 فی کنکشن فی مہینہ، کنکشن بڑھنے کے ساتھ کم ہوتی ہوئی، پہلے 3 دن فری ٹرائل ہے۔
اکثر پوچھے جانے والے سوالات
کیا TikTok API ہر ویڈیو کا واچ ٹائم دیتا ہے؟
ہاں۔ total_time_watched اور average_time_watched /business/video/list/ سے سیکنڈ میں آتے ہیں، video.insights اسکوپ والے ٹوکنز کے لیے۔
API کے ذریعے TikTok ویڈیو کا تکمیل کا تناسب کیسے حاصل کروں؟
/business/video/list/ کے fields میں full_video_watched_rate مانگیں۔ TikTok اسے ان ناظرین کا فیصد بتاتا ہے جو ویڈیو مکمل دیکھتے ہیں۔
میری TikTok ویڈیو کے ریچ اور واچ ٹائم خالی کیوں ہیں؟
TikTok انہیں ایسی ویڈیو کے لیے چھوڑ سکتا ہے جس پر پچھلے 7 دن میں کوئی ویوز، لائکس، کمنٹس یا شیئرز نہ ہوں، اور تازہ ڈیٹا 24 سے 48 گھنٹے پیچھے ہوتا ہے۔
کیا API ایک مخصوص TikTok ویڈیو کے میٹرکس واپس کر سکتا ہے؟
ہاں۔ اس کا ID filters.video_ids میں دیں، اور item_id کے ساتھ مطلوبہ میٹرکس fields میں۔
مزید پڑھیں
دو منٹ میں اپنا پہلا چینل کنیکٹ کریں۔
کسی پلیٹ فارم کے ریویو کا انتظار نہیں۔ WhatsApp، Instagram، TikTok یا کوئی اور چینل کنیکٹ کریں، پھر اپنے AI سے پوسٹ کرنے، جواب دینے یا رپورٹ بنانے کو کہیں اور اسے کام کرتے دیکھیں۔
- 3 دن مفت
- کسی بھی وقت منسوخ کریں
- صرف آفیشل API
- 24/7 نگرانی
تصدیق شدہ تاریخ