Як знаходити відео 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: date_posted допускає значення this-month, sort_by — date-posted, а region приймає код країни. Значення count задає розмір запитуваної видачі, а не гарантує повний перелік публікацій. Під час подальшої пагінації зберігайте повернений курсор як непрозоре значення й передавайте його в параметр cursor.

Перевірка людиною й автоматизація запуску

Передайте CSV відповідальному перевіряльнику разом із короткою інструкцією: відкрити посилання, переглянути відео й контекст підпису, зафіксувати висновок і додати коментар, якщо маркер знайдено в іншому значенні. Наприклад, автоматична фільтрація не розрізняє рекламне розкриття й обговорення того, як влаштована реклама. Людська перевірка усуває цю смислову прогалину.

Для регулярного збору запускайте скрипт за розкладом через cron, планувальник CI або оркестратор завдань. Зберігайте CSV із датою запуску або завантажуйте рядки в таблицю з унікальним ключем, що складається з ідентифікатора відео й дати спостереження. Якщо потрібен журнал аудиту, зберігайте й початкову JSON-відповідь із контролем доступу: це дає змогу повторно перевірити перетворення й пояснити, звідки взявся кожен рядок.

У робочій версії варто додати обробку мережевих і HTTP-помилок, обмеження повторних спроб і сповіщення про збій. Не виводьте повну URL-адресу запиту: вона містить ключ доступу. Команді з кількома користувачами доцільно зберігати секрет у менеджері секретів середовища виконання й обмежити доступ до підсумкових файлів відповідно до внутрішніх правил.

Що саме дасть такий список

Після запуску команда матиме відтворювану вибірку відео, знайдених за ключовою фразою, і чітку підставу потрапляння кожного кандидата до черги. Із таблиці можна вручну вилучити нерелевантні збіги, призначити перевіряльника й згрупувати результати за маркером або автором. Якщо збирати дані регулярно, додасться історія спостережень про те, які відео були в поверненій видачі на конкретну дату.

Цей підхід підходить для первинного виявлення й маршрутизації матеріалів, а не для автоматичного висновку щодо дотримання правил. Він обмежений пошуковою видачею, вибраним ключовим словом, налаштуваннями запиту й текстовими маркерами. Щоб перевірити конкретну співпрацю, зіставте ролик із брифом і відомостями, доступними вашій команді, а потім оцініть саме повідомлення відповідно до застосовних правил.

Щоб почати, перевірте актуальні умови доступу й параметри на сторінці продукту TikTok Scraper API, а формат відповіді й варіанти інтеграції звіряйте з офіційною документацією API.