كيفية إعداد تقرير أسبوعي عن تفاعل الجمهور مع إطلاق منتج على TikTok

بعد إطلاق تطبيق أو ميزة جديدة، يتوزع التعليق بسرعة على مقاطع الفيديو القصيرة. يعثر المسوّق يدويًا على بضعة مقاطع ويرسل روابطها إلى المحادثة، ثم يعجز المحلل لاحقًا عن معرفة المنشورات التي أُدرجت بالفعل وكيف تغيرت المشاهدات. والحل العملي هو جمع نتائج البحث بانتظام باستخدام عدة استعلامات ثابتة، وحفظ الاستجابات الأصلية، وإعداد تقرير يستند إلى الحقول المؤكدة.

سنضبط في هذا الدليل عملية جمع لحالة محددة: أطلق فريق ميزة جديدة ويريد تتبّع مقاطع TikTok العامة أسبوعيًا، التي يرد في أوصافها اسم المنتج أو الميزة الأساسية أو مشكلة شائعة لدى المستخدم. وهذه مراقبة لعينة البحث التي تم العثور عليها: إذ تعيد واجهة API النتائج وفقًا للاستعلام والمعلمات، ولا تضمن قائمة شاملة بكل المنشورات المتعلقة بالإطلاق.

حدّد أولًا الإشارة التي يحتاج إليها الفريق

لا يوضح العدد الكبير من المشاهدات، بمفرده، ما ينبغي فعله لاحقًا. والأجدى أن يعرف الفريق الأسئلة المتكررة والسيناريوهات التي يعرضها الناس والمقاطع التي تحظى بتفاعلات عامة ملحوظة. لذلك، صغ أولًا بضعة عبارات بحث وحدد الحقول التي ستظهر في التقرير.

على سبيل المثال، عند إطلاق أداة لجدولة المنشورات، يمكن تجربة استعلامات مثل «اسم المنتج» و«مجدول المحتوى» و«كيفية جدولة TikTok». ينبغي أن تعكس العبارات طرقًا مختلفة قد يستخدمها الناس لوصف الموضوع نفسه. دوّنها مع تاريخ بدء المراقبة والمنطقة، كي يمكن مقارنة عمليات التصدير اللاحقة بالإعدادات ذاتها.

يمكن أن يتضمن الجدول الأساسي وقت الجمع، وعبارة البحث، ومعرّف الفيديو، والرابط، والوصف، واسم المؤلف، ومعرّف المؤلف، وقيم المشاهدات والإعجابات والتعليقات المتاحة. وتوثّق TikTok Scraper API حقولًا لنتائج البحث مثل aweme_id وdesc وshare_url ومعلومات المؤلف وبعض الإحصاءات. ينبغي التحقق من الحقل في كل كائن، إذ قد تغيب بعض المقاييس.

استخدم نقطة البحث الموثّقة

للبحث عن مقاطع الفيديو، استخدم مسار GET /searchVideo على العنوان الأساسي https://tiktok.evelode.com. وتذكر الوثائق المعامل الإلزامي keyword والمعاملات الإضافية count وcursor وdate_posted وsort_by وregion وcache_timeout. وتشمل القيم المسموح بها لمرشح التاريخ this-week، وللترتيب relevance وmost-liked وdate-posted. راجع أسماءها واستخداماتها في مرجع نقاط TikTok API.

يُمرّر مفتاح الترخيص بوصفه معامل استعلام باسم license_key. في البرنامج النصي التشغيلي، اقرأه من متغير البيئة JSONSCRAPER_TIKTOK_LICENSE_KEY، ولا تكتبه في الشيفرة المصدرية أو تطبعه في السجلات. هذا المثال مخصص لـ Python 3.8+ ويستخدم حزمة requests:

import os
import requests

BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]


def search_videos(keyword, cursor=None):
    params = {
        "license_key": API_KEY,
        "keyword": keyword,
        "count": 20,
        "date_posted": "this-week",
        "sort_by": "date-posted",
        "region": "US",
    }
    if cursor is not None:
        params["cursor"] = cursor

    response = requests.get(
        f"{BASE_URL}/searchVideo",
        params=params,
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("أعادت TikTok API حالة غير ok")

    return payload["tiktok"]


result = search_videos("content planning app")
print("الكائنات التي عُثر عليها:", len(result.get("aweme_list", [])))

يتحقق البرنامج النصي من أخطاء HTTP ومن الحالة الخارجية للاستجابة. لكن نجاح استجابة HTTP لا يضمن وجود مقاطع فيديو في نتائج البحث؛ فقد تكون القائمة فارغة عند خلو العينة. ومن المفيد في التشغيل الأول حفظ الاستجابة كاملة في مخزن آمن، لمقارنة الكائنات الفعلية بجدول الحقول الموحّدة.

عالج بنيتي استجابة البحث

تتسم نتائج البحث بخاصية مهمة في بنيتها. فقد تظهر مقاطع الفيديو مباشرةً في tiktok.aweme_list، أو قد ترد ضمن tiktok.search_item_list[].aweme_info. وإذا قرأ المعالج القائمة الأولى وحدها، فقد يفوته ما يوجد في البنية الثانية.

أضف مُطبِّعًا صغيرًا يدعم البنيتين ويتجاوز بأمان العناصر التي لا تتضمن كائن فيديو متداخلًا:

def extract_awemes(tiktok):
    items = list(tiktok.get("aweme_list") or [])

    for item in tiktok.get("search_item_list") or []:
        aweme = item.get("aweme_info")
        if aweme:
            items.append(aweme)

    return items


def normalize(aweme, keyword, collected_at):
    author = aweme.get("author") or {}
    stats = aweme.get("statistics") or {}

    return {
        "collected_at": collected_at,
        "keyword": keyword,
        "video_id": aweme.get("aweme_id"),
        "posted_at": aweme.get("create_time"),
        "description": aweme.get("desc"),
        "share_url": aweme.get("share_url"),
        "author_id": author.get("uid"),
        "author_name": author.get("nickname"),
        "views": stats.get("play_count"),
        "likes": stats.get("digg_count"),
        "comments": stats.get("comment_count"),
        "shares": stats.get("share_count"),
    }

تظل القيمة المفقودة None. لا تستبدلها بصفر: فالصفر يعني قيمة مقيسة، في حين تحفظ None حقيقة أن الحقل لم يرد. ويؤثر هذا الفرق في المتوسطات والنسب وأي استنتاجات للفريق.

احفظ السجل التاريخي، لا اللقطة الحالية فقط

لمتابعة التغيّر، احفظ سجلات رصد منفصلة. يصلح معرّف الفيديو لإزالة المنشورات المكررة، لا لحذف سجلها التاريخي؛ فظهور المقطع نفسه مجددًا في عملية الجمع التالية يوفر نقطة رصد جديدة. مثلًا، يمكن إنشاء مفتاح فريد لجدول الرصد من video_id وcollected_at، مع حفظ الرابط والوصف في السجل لتسهيل التحقق.

يفيد هذا المخطط الأساسي في SQLite عند إعداد نموذج أولي:

import sqlite3

conn = sqlite3.connect("tiktok_observations.sqlite3")
conn.execute("""
CREATE TABLE IF NOT EXISTS observations (
    video_id TEXT NOT NULL,
    collected_at TEXT NOT NULL,
    keyword TEXT NOT NULL,
    posted_at INTEGER,
    description TEXT,
    share_url TEXT,
    author_id TEXT,
    author_name TEXT,
    views INTEGER,
    likes INTEGER,
    comments INTEGER,
    shares INTEGER,
    PRIMARY KEY (video_id, collected_at, keyword)
)
""")
conn.commit()

عمليًا، وحّد وقت الجمع بتوقيت UTC، واحفظ JSON الأصلي على حدة، وأضف عمودًا لإصدار المخطط. تساعد الاستجابة الأصلية على مراجعة التحويل عندما تختلف بنية الكائنات الجديدة عن المعتاد. أما المنشورات التي تظهر ضمن عدة استعلامات، فاحفظ عبارات البحث المطابقة لها في جدول مرتبط منفصل، أو اجمعها عند إعداد التقرير.

التقسيم إلى صفحات: تابع باستخدام المؤشر الوارد في الاستجابة فقط

يُستخدم المعامل cursor لمتابعة البحث. تُؤخذ قيمته من الاستجابة السابقة وتُمرّر مجددًا من دون تحويل، وينتهي العمل عندما لا يعود has_more يشير إلى وجود صفحات إضافية أو عند بلوغ الحد المحدد. ينبغي التعامل مع المؤشر بوصفه قيمة مبهمة: لا تحسبه بنفسك ولا تستبدله بعدّاد للصفحات.

def collect_pages(keyword, max_pages=3):
    cursor = None
    collected = []

    for _ in range(max_pages):
        page = search_videos(keyword, cursor)
        collected.extend(extract_awemes(page))

        if not page.get("has_more"):
            break
        cursor = page.get("cursor")
        if cursor is None:
            break

    return collected

يجعل تقييد عدد الصفحات حجم الطلبات أكثر قابلية للتوقع في المهمة الدورية. سجّل عدد الصفحات وقيمة has_more في سجل التنفيذ، كي يتوفر سياق لتقرير العينة. وحتى مع استخدام تقسيم الصفحات، تظل النتيجة وصفًا لاستجابات API التي تم الحصول عليها وللحد المحدد للجمع؛ ولا تمثل تقديرًا لكل المنشورات على المنصة.

أنشئ تقريرًا قابلًا للتكرار

جدول عملية الجمع أسبوعيًا أو بوتيرة أعلى إذا احتاج الفريق إلى إشارات أكثر تكرارًا. وفي كل عملية، سجّل قائمة الاستعلامات والمعلمات والوقت وعدد الكائنات المستلمة وعدد المعرّفات الفريدة. واحسب منفصلًا المنشورات التي رُصدت للمرة الأولى في هذه العملية والمنشورات التي ظهرت سابقًا.

يمكن أن يتضمن التقرير أربعة عروض بسيطة:

• مقاطع فيديو جديدة: الروابط والأوصاف وتاريخ النشر وعبارة البحث التي عُثر على المقطع بواسطتها.
• موضوعات متكررة: تجميع الأوصاف ضمن فئات يحددها الفريق يدويًا، مثل «خطأ في الإعداد» و«طلب ميزة» و«استعراض سيناريو».
• التفاعلات العامة: المشاهدات والإعجابات والتعليقات وإعادة النشر المتاحة، مع عرضها بجانب وقت الرصد.
• إشارات تستحق التحقق: صياغات جديدة أو أسئلة متكررة أو مقاطع يجدر بأحد الموظفين دراستها.

لا تسمِّ الفرق بين لقطتين «إعجابات جديدة» قبل التحقق من دلالة القيم وحداثتها في الاستجابة. الصياغة الأدق هي «قيمة المقياس في أحدث استجابة مستلمة» و«الفرق بين لقطات الرصد المحفوظة». وهكذا يعرف الفريق ما حُسب بالضبط، ويمكنه فتح المنشور الأصلي قبل اتخاذ القرار.

استخدم الذكاء الاصطناعي للتصنيف، لا بديلًا عن الجمع

بعد توحيد البيانات، يمكن إرسال أوصاف مقاطع الفيديو إلى نموذج لتصنيفها ضمن فئات محددة مسبقًا. أرسل الحقول النصية الضرورية فقط، واطلب نتيجة منظّمة تشمل الفئة ومبررًا موجزًا ومستوى الثقة ومقتطفًا من الوصف تستند إليه العلامة. واحفظ المنشور الأصلي إلى جانب العلامة كي يتمكن المحلل من مراجعة الحالات الملتبسة.

يبقى سير العمل بسيطًا: يشغّل المجدول عملية الجمع؛ ويتحقق Python من الاستجابة ويحفظ JSON؛ ثم توحّد مهمة منفصلة السجلات الجديدة؛ ويعالج المصنّف الأوصاف الجديدة فقط؛ ويُنشأ التقرير من قاعدة البيانات ويُرسل إلى القناة التي يختارها الفريق. توفر TikTok Scraper API بيانات البحث، أما التصنيف وإيصال التقرير فهما منطق التكامل الخاص بك، ويمكن تنفيذهما باستخدام Python أو n8n أو Make.

للحد من الضجيج، حدّد قاموس الفئات قبل إرسال البيانات إلى النموذج، وراجع دوريًا عينة موسومة يدويًا. وتفيد حالة «السياق غير كافٍ» للأوصاف القصيرة أو الملتبسة بدلًا من فرض اختيار فئة. تساعد علامات الذكاء الاصطناعي على ترتيب قائمة المقاطع للمراجعة، لكن ينبغي تأكيد الاستنتاجات المتعلقة بمشكلات المستخدمين بقراءة المنشورات ومقارنة عدة مشاهدات.

الأخطاء وإعادة المحاولة والتعامل الآمن مع المفتاح

قد ينتهي طلب الشبكة بانتهاء المهلة أو بخطأ مؤقت، أو قد يتعذر تحليل الاستجابة على هيئة JSON. قسّم المعالجة إلى مراحل: الطلب، والتحقق من رمز HTTP، وتحليل JSON، والتحقق من الحالة الخارجية، وتوحيد البيانات، ثم حفظها. عند وقوع أعطال مؤقتة، استخدم عددًا محدودًا من المحاولات مع زيادة مدة الانتظار تدريجيًا؛ وسجّل الأخطاء الدائمة لمراجعتها لاحقًا، من دون اعتبار العملية ناجحة.

احفظ المفتاح في مدير أسرار بيئة التشغيل أو في متغير بيئة. وبما أن API تقبل license_key ضمن سلسلة الطلب، فتجنب تسجيل URL الكامل ومعلمات الطلب، إذ سيظهر السر فيها. ولأغراض التشخيص، سجّل المسار ورمز الاستجابة والمدة وعبارة البحث ومعرّف المهمة، مع حذف المفتاح من السجلات.

اضبط الجدول الزمني وحجم العينة بما يناسب مهمتك وشروط استخدام المنصة. وينبغي قصر جمع البيانات العامة على ما تحتاج إليه فعليًا للتحليل، مع توضيح قواعد الفريق الداخلية الخاصة بحفظ الأوصاف والروابط ومعرّفات المؤلفين. وقد تكون استجابات API ومقاييسها غير مكتملة أو تتغير بين عمليات الرصد، لذلك ينبغي أن يحفظ التقرير وقت الجمع ومصدر كل سجل.

النتيجة: من الروابط اليدوية إلى سجل قابل للتحقق

بعد الإعداد، يحصل الفريق على قائمة متجددة بانتظام بالمقاطع التي عُثر عليها، واستجابات أصلية للتدقيق، وجدول للمقاييس العامة المتاحة، ونظرة عامة على الموضوعات المتكررة. ويساعد ذلك على رصد الأسئلة المتعلقة بالميزة الجديدة بسرعة أكبر، والعثور على أمثلة لسيناريوهات استخدام المنتج، واختيار منشورات للتحليل اليدوي. وتوضح مقارنة اللقطات كيف تغيرت القيم المحفوظة للمقاطع التي عُثر عليها سابقًا، فيما يبين سجل الاستعلامات طريقة تكوين العينة.

ابدأ باستعلام واحد وحدّ صغير للصفحات، وتحقق من البنية الفعلية للاستجابة، ثم أضف صيغًا أخرى وجدولًا زمنيًا. وقبل نقل النموذج الأولي إلى بيئة الإنتاج، ضع قواعد لإزالة التكرار والتخزين ومعالجة الأخطاء. تتوفر المسارات والمعلمات الحالية في الوثائق الرسمية لـ API؛ أما وصف الإمكانات والانتقال إلى الاختبار فيتوفر على صفحة TikTok Scraper API.