Jak najít videa TikTok s reklamním označením a předat je ke kontrole

Pokud tým potřebuje zkontrolovat, jak autoři označují vztah ke značce ve veřejných videích TikTok, užitečným prvním výsledkem není automatický verdikt, ale stručná fronta videí s popiskem, odkazem a nalezenými klíčovými slovy. Níže je pracovní postup: odeslat vyhledávací dotaz přes TikTok Scraper API jsonscraper, sjednotit dvě varianty struktury odpovědi a uložit CSV ke kontrole specialistou.

Úkol: najít videa, která stojí za kontrolu

Ruční vyhledávání podle názvu společnosti se obtížně opakuje stejným způsobem: výsledky je třeba shromažďovat jednotlivě a důvody výběru zůstávají v prohlížeči. Automatizovaný výběr umožňuje uložit dotaz, datum spuštění a nalezené materiály do tabulky, aby tým mohl videa kontrolovat podle jednotného seznamu.

V tomto scénáři „kandidát ke kontrole“ označuje pouze video z vrácených výsledků vyhledávání, v jehož popisku se našlo předem určené slovo nebo fráze. Může jít například o „reklama“, „partnerství“ nebo „sponzor“. Takový textový filtr pomáhá nasměrovat pozornost člověka, ale video nehodnotí ani neurčuje, zda jsou splněny příslušné požadavky.

Toto rozlišení je pro marketingový tým důležité. Doporučení Federální obchodní komise USA popisují zveřejnění podstatného vztahu ke značce jako povinnost závislou na kontextu sdělení; u videí FTC doporučuje zohlednit viditelnou i slyšitelnou podobu zveřejnění. Vyhledávání v popisku dokáže odhalit jednotlivé textové signály, ale rozhodnutí vyžaduje zhlédnutí příspěvku a posouzení jeho kontextu. Pokyny FTC pro tvůrce tyto podmínky vysvětlují na příkladech.

Výsledek: CSV s důvodem výběru

Pipeline zapíše jeden řádek pro každý jedinečný identifikátor videa a zahrne text popisu, odkaz, jméno autora, dostupné veřejné čítače a nalezené signály. Zvlášť přidáme původní vyhledávací dotaz a čas sběru. Tabulka tak bude vhodná k předání do pracovní fronty a později pomůže pochopit, proč se do ní konkrétní video dostalo.

Slovník signálů stanoví editor nebo specialista na compliance. Začněte jazykem a výrazy, které se ve vaší kampani skutečně používají, potom zkontrolujte výsledky a podle potřeby seznam rozšiřte. Hodnoty v následujícím kódu jsou záměrně jednoduché: je třeba je upravit podle konkrétní značky, trhu a jazyka obsahu.

Připojení k TikTok Scraper API

Dokumentace jsonscraper uvádí pro vyhledávání videí endpoint GET /searchVideo na základní adrese https://tiktok.evelode.com. Povinným parametrem je keyword; mezi další parametry patří count, date_posted, sort_by a region. Klíč se předává jako license_key, proto jej ukládejte do proměnné prostředí, nikoli do kódu nebo CSV. Přesné názvy parametrů a endpoint najdete v referenční příručce endpointů TikTok; informace o produktu a přístupu jsou na stránce TikTok Scraper API.

Jedna důležitá vlastnost odpovědi ovlivňuje úplnost lokálního parseru: data se mohou nacházet v tiktok.aweme_list nebo v tiktok.search_item_list[].aweme_info. Skript proto kontroluje obě pole. Pokud vyhledávání vrátí prázdný seznam, vytvoří prázdné CSV namísto toho, aby chybějící výsledky nahradil smyšlenými řádky.

Příklad v Pythonu: vyhledávání, filtr a CSV

Příklad používá pouze standardní knihovnu Pythonu 3.8+. Před spuštěním nastavte v prostředí proměnnou JSONSCRAPER_TIKTOK_LICENSE_KEY. V požadavku se používá keyword a klíč se předává v parametru dotazu license_key, jak uvádí specifikace.

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")

Skript nejprve kontroluje vnější stav, poté načte objekt tiktok a spojí dostupné varianty pole. Deduplikace podle aweme_id zabraňuje duplicitním řádkům, pokud se jedno video objeví v obou cestách odpovědi. Metriky se zapisují tak, jak byly vráceny; chybějící hodnota zůstane prázdná a nezmění se na nulu.

Příklad používá parametry dokumentované pro /searchVideo: date_posted může mít hodnotu this-month, sort_by hodnotu date-posted a region přijímá kód země. Hodnota count určuje velikost požadovaných výsledků, nikoli záruku úplného seznamu příspěvků. Při následné stránkování ukládejte vrácený kurzor jako neprůhlednou hodnotu a předávejte jej v parametru cursor.

Lidská kontrola a automatizace spouštění

Předejte CSV odpovědnému kontrolujícímu spolu se stručnými pokyny: otevřít odkaz, zhlédnout video i kontext popisku, zaznamenat závěr a přidat komentář, pokud je signál použit v jiném smyslu. Automatický filtr například nerozliší reklamní označení od diskuse o tom, jak reklama funguje. Lidská kontrola tuto významovou mezeru překlene.

Pro opakovatelný sběr spouštějte skript podle plánu pomocí cronu, plánovače CI nebo nástroje pro orchestraci úloh. Ukládejte CSV s datem spuštění nebo načítejte řádky do tabulky s jedinečným klíčem tvořeným identifikátorem videa a datem pozorování. Pokud potřebujete auditní záznam, uchovávejte také původní odpověď JSON s řízeným přístupem: umožní znovu zkontrolovat převod a vysvětlit původ každého řádku.

V produkční verzi je vhodné doplnit zpracování síťových chyb a chyb HTTP, omezení počtu opakovaných pokusů a upozornění na selhání. Nevypisujte celý URL požadavku: obsahuje přístupový klíč. Pro tým s více uživateli je rozumné ukládat tajný klíč ve správci tajných údajů běhového prostředí a omezit přístup k výsledným souborům podle interních pravidel.

Co tento seznam skutečně poskytne

Po spuštění bude mít tým reprodukovatelný výběr videí nalezených podle klíčové fráze a jasný důvod, proč se každý kandidát dostal do fronty. Z tabulky lze ručně vyloučit nerelevantní shody, přiřadit kontrolujícího a seskupit výsledky podle signálu nebo autora. Při pravidelném sběru navíc vznikne historie toho, která videa se v konkrétní den nacházela ve vrácených výsledcích.

Tento přístup se hodí k prvotnímu vyhledávání a směrování materiálů, nikoli k automatickému závěru o dodržování pravidel. Je omezen výsledky vyhledávání, zvoleným klíčovým slovem, nastavením dotazu a textovými signály. Při kontrole konkrétní spolupráce porovnejte video s briefem a informacemi, které má váš tým k dispozici, a poté posuďte samotné sdělení podle příslušných pravidel.

Než začnete, ověřte aktuální přístup a parametry na stránce produktu TikTok Scraper API; formát odpovědi a možnosti integrace porovnejte s oficiální dokumentací API.