כיצד לאתר סרטוני TikTok עם גילויי פרסום ולהעבירם לבדיקה

אם צוות צריך לבדוק כיצד יוצרים חושפים קשר למותג בסרטוני TikTok ציבוריים, תוצאה ראשונית מועילה אינה הכרעה אוטומטית, אלא תור מסודר של סרטונים הכולל כיתוב, קישור ומילות הסמן שנמצאו. להלן תהליך עבודה: שולחים שאילתת חיפוש דרך TikTok Scraper API של jsonscraper, מאחדים שתי תבניות אפשריות של מבנה התשובה לפורמט אחד ושומרים קובץ CSV לבדיקה מקצועית.

המטרה: למצוא סרטונים שכדאי לבדוק

קשה לחזור על חיפוש ידני לפי שם חברה באותה דרך: צריך לאסוף את התוצאות אחת-אחת, והנימוקים לבחירה נשארים בדפדפן. איסוף אוטומטי מאפשר לשמור בטבלה את השאילתה, את מועד ההרצה ואת הפריטים שנמצאו, כך שהצוות יוכל לבדוק את הסרטונים לפי רשימה אחידה.

בתרחיש הזה, „מועמד לבדיקה” פירושו רק סרטון שמופיע בתוצאות החיפוש שהוחזרו, ובתיאור שלו נמצאה מראש מילה או צירוף מילים שהוגדרו. למשל, אלה יכולים להיות „פרסומת”, „שותפות” או „ממומן”. מסנן הטקסט הזה מסייע למקד את תשומת הלב של אדם, אך אינו מעריך את הסרטון עצמו ואינו קובע אם הדרישות הרלוונטיות מולאו.

ההבחנה הזאת חשובה לצוות השיווק. הנחיות ועדת הסחר הפדרלית של ארצות הברית מתארות גילוי של קשר מהותי עם מותג כחובה שתלויה בהקשר של המסר; לגבי סרטונים, ה-FTC ממליצה להביא בחשבון גילוי חזותי ושמיעתי. חיפוש בכיתוב עשוי לזהות סימנים טקסטואליים מסוימים, אך ההחלטה מחייבת צפייה בפרסום והערכת ההקשר שלו. מדריך ה-FTC ליוצרים מסביר את התנאים האלה באמצעות דוגמאות.

התוצאה: קובץ CSV עם נימוק לבחירה

צינור העיבוד ייצור שורה אחת לכל מזהה סרטון ייחודי ויכלול את טקסט התיאור, הקישור, שם היוצר, מוני פעילות ציבוריים זמינים ואת סמני הטקסט שהתאימו. בנפרד נוסיף את שאילתת החיפוש המקורית ואת מועד האיסוף. כך ניתן להעביר את הטבלה לתור עבודה, וגם להבין בהמשך מדוע סרטון מסוים נכלל בו.

עורך או מומחה ציות יגדירו את מילון הסמנים. התחילו בשפה ובמונחים שמשמשים בפועל בקמפיין שלכם, אחר כך בחנו את התוצאות והרחיבו את הרשימה במידת הצורך. הערכים בקוד שלהלן פשוטים בכוונה: יש להתאים אותם למותג, לשוק ולשפת התוכן המסוימים.

התחברות ל-TikTok Scraper API

בתיעוד של jsonscraper מצוין שנתיב חיפוש הסרטונים הוא GET /searchVideo, בכתובת הבסיס https://tiktok.evelode.com. הפרמטר הנדרש הוא keyword; בין הפרמטרים הנוספים נמצאים count, date_posted, sort_by ו-region. המפתח נשלח כ-license_key, לכן יש לשמור אותו במשתנה סביבה ולא בקוד או בקובץ CSV. השמות המדויקים של הפרמטרים והנתיב מופיעים במדריך נקודות הקצה של TikTok; מידע על המוצר והגישה זמין גם בעמוד TikTok Scraper API.

יש מאפיין חשוב בתשובה שמשפיע על שלמות המנתח המקומי: הנתונים עשויים להימצא ב-tiktok.aweme_list או ב-tiktok.search_item_list[].aweme_info. לכן הסקריפט בודק את שתי הרשימות. אם החיפוש החזיר רשימה ריקה, ייווצר קובץ CSV ריק, ולא יתווספו לו שורות פיקטיביות במקום התוצאות החסרות.

דוגמה ב-Python: חיפוש, סינון ו-CSV

הדוגמה משתמשת רק בספרייה הסטנדרטית של Python 3.8 ומעלה. לפני ההרצה, הגדירו בסביבה את JSONSCRAPER_TIKTOK_LICENSE_KEY. הבקשה משתמשת ב-keyword, והמפתח מועבר בפרמטר השאילתה license_key, בהתאם למפרט.

import csv
import json
import os
import sys
from datetime import datetime, timezone
from urllib.parse import urlencode
from urllib.request import Request, urlopen

API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
KEYWORD = "Acme"
MARKERS = ["реклама", "партнерство", "партнёрство", "спонсор", "ad", "sponsored"]

params = {
    "license_key": API_KEY,
    "keyword": KEYWORD,
    "count": 30,
    "sort_by": "date-posted",
    "date_posted": "this-month",
    "region": "US",
}
url = "https://tiktok.evelode.com/searchVideo?" + urlencode(params)
request = Request(url, headers={"Accept": "application/json"})

with urlopen(request, timeout=30) as response:
    payload = json.load(response)

if payload.get("status") != "ok":
    raise RuntimeError("API returned a non-ok outer status")

tiktok = payload.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
    info = entry.get("aweme_info") or {}
    if info:
        items.append(info)

seen = set()
rows = []
collected_at = datetime.now(timezone.utc).isoformat()

for item in items:
    video_id = item.get("aweme_id")
    if not video_id or video_id in seen:
        continue
    seen.add(video_id)

    description = item.get("desc") or ""
    lowered = description.casefold()
    matched = [word for word in MARKERS if word.casefold() in lowered]
    if not matched:
        continue

    author = item.get("author") or {}
    stats = item.get("statistics") or {}
    rows.append({
        "collected_at_utc": collected_at,
        "search_keyword": KEYWORD,
        "video_id": video_id,
        "share_url": item.get("share_url") or "",
        "description": description,
        "matched_markers": "; ".join(matched),
        "author_name": author.get("nickname") or "",
        "author_id": author.get("unique_id") or "",
        "play_count": stats.get("play_count", ""),
        "digg_count": stats.get("digg_count", ""),
        "comment_count": stats.get("comment_count", ""),
        "share_count": stats.get("share_count", ""),
    })

fields = [
    "collected_at_utc", "search_keyword", "video_id", "share_url",
    "description", "matched_markers", "author_name", "author_id",
    "play_count", "digg_count", "comment_count", "share_count",
]
with open("tiktok_review_queue.csv", "w", newline="", encoding="utf-8-sig") as output:
    writer = csv.DictWriter(output, fieldnames=fields)
    writer.writeheader()
    writer.writerows(rows)

print(f"Saved {len(rows)} review candidates to tiktok_review_queue.csv")

תחילה הסקריפט בודק את סטטוס התשובה החיצוני, אחר כך קורא את אובייקט tiktok ומאחד את חלופות הרשימה הזמינות. מניעת כפילויות לפי aweme_id מונעת שורות חוזרות אם אותו סרטון הופיע בשני נתיבי התשובה. המדדים נכתבים כפי שהתקבלו; ערך חסר נשאר ריק ואינו הופך לאפס.

הדוגמה משתמשת בפרמטרים המתועדים עבור /searchVideo: הערך this-month מותר עבור date_posted, הערך date-posted עבור sort_by, ו-region מקבל קוד מדינה. הערך count קובע את גודל התוצאות המבוקש, ואינו מבטיח רשימה מלאה של פרסומים. אם מוסיפים עימוד, שמרו את הסמן שהוחזר כערך אטום והעבירו אותו בפרמטר cursor.

בדיקה אנושית ואוטומציה של ההרצה

העבירו את קובץ ה-CSV לבודק האחראי עם הוראות קצרות: לפתוח את הקישור, לצפות בסרטון ולבחון את ההקשר של הכיתוב, לתעד את המסקנה ולהוסיף הערה אם הסמן נמצא במשמעות אחרת. לדוגמה, סינון אוטומטי אינו מבחין בין גילוי פרסומי לבין דיון באופן שבו פרסום פועל. בדיקה אנושית מגשרת על הפער הסמנטי הזה.

כדי לאסוף נתונים באופן עקבי, הריצו את הסקריפט לפי לוח זמנים באמצעות cron, מתזמן של CI או מתזמר משימות. שמרו את קובץ ה-CSV עם תאריך ההרצה, או טענו את השורות לטבלה עם מפתח ייחודי המורכב ממזהה הסרטון ומתאריך התצפית. אם נדרש יומן ביקורת, שמרו גם את תשובת ה-JSON המקורית עם בקרת גישה: כך ניתן לבדוק מחדש את ההמרה ולהסביר מה מקור כל שורה.

בגרסת ייצור כדאי להוסיף טיפול בשגיאות רשת ו-HTTP, הגבלת ניסיונות חוזרים והתראה במקרה של כשל. אל תדפיסו את כתובת הבקשה המלאה: מפתח הגישה כלול בה. לצוותים עם כמה משתמשים, מומלץ לאחסן את הסוד במנהל סודות של סביבת ההרצה ולהגביל את הגישה לקובצי הפלט בהתאם לכללים הפנימיים.

מה הרשימה הזאת תספק בפועל

לאחר ההרצה יהיה לצוות אוסף שניתן לשחזר של סרטונים שנמצאו באמצעות ביטוי מפתח, וכן נימוק ברור לכך שכל מועמד נכלל בתור. אפשר להסיר מהטבלה ידנית התאמות לא רלוונטיות, לשבץ בודק ולקבץ את התוצאות לפי סמן או יוצר. איסוף קבוע יוסיף היסטוריה של הסרטונים שהופיעו בתוצאות שהוחזרו בתאריך מסוים.

הגישה הזאת מתאימה לגילוי ראשוני ולניתוב חומרים, ולא לקביעה אוטומטית של עמידה בכללים. היא מוגבלת לתוצאות החיפוש, למילת המפתח שנבחרה, להגדרות הבקשה ולסמני הטקסט. כדי לבדוק שיתוף פעולה מסוים, השוו את הסרטון למסמך ההנחיות ולמידע הזמין לצוות שלכם, ואז העריכו את המסר עצמו לפי הכללים הרלוונטיים.

כדי להתחיל, בדקו את זמינות הגישה ואת הפרמטרים המעודכנים בעמוד המוצר TikTok Scraper API, והשוו את מבנה התשובה ואת אפשרויות האינטגרציה לתיעוד הרשמי של ה-API.