Jak znajdować filmy na TikToku z informacją o reklamie i przekazywać je do weryfikacji

Jeśli zespół chce sprawdzić, jak twórcy ujawniają związki z marką w publicznych filmach na TikToku, przydatnym pierwszym rezultatem nie jest automatyczny werdykt, lecz krótka kolejka filmów z opisem, linkiem i znalezionymi słowami-kluczami. Poniżej przedstawiamy praktyczny schemat: wysłanie zapytania przez TikTok Scraper API jsonscraper, ujednolicenie dwóch wariantów struktury odpowiedzi i zapisanie pliku CSV do weryfikacji przez specjalistę.

Cel: znaleźć filmy warte sprawdzenia

Ręczne wyszukiwanie według nazwy firmy trudno powtarzać w ten sam sposób: wyniki trzeba zbierać pojedynczo, a uzasadnienie wyboru pozostaje w przeglądarce. Zautomatyzowane wyszukiwanie pozwala zapisać zapytanie, datę uruchomienia i znalezione materiały w tabeli, dzięki czemu zespół może sprawdzić filmy według jednej listy.

W tym scenariuszu „kandydat do weryfikacji” oznacza wyłącznie film z wyników wyszukiwania, którego opis zawiera wcześniej ustalone słowo lub frazę. Może to być na przykład „reklama”, „partnerstwo” albo „sponsor”. Taki filtr tekstowy pomaga skierować uwagę człowieka, ale nie ocenia samego filmu ani nie rozstrzyga, czy spełniono obowiązujące wymagania.

To rozróżnienie jest ważne dla zespołu marketingowego. Zalecenia amerykańskiej Federalnej Komisji Handlu opisują ujawnienie istotnego związku z marką jako obowiązek zależny od kontekstu przekazu; w przypadku filmów FTC zaleca uwzględnienie widocznej i słyszalnej formy ujawnienia. Wyszukiwanie po opisie może wykryć określone sygnały tekstowe, ale decyzja wymaga obejrzenia publikacji i oceny jej kontekstu. Przewodnik FTC dla twórców wyjaśnia te warunki na przykładach.

Wynik: plik CSV z uzasadnieniem wyboru

Potok zapisze jeden wiersz dla każdego unikatowego identyfikatora filmu, uwzględniając tekst opisu, link, nazwę autora, dostępne publiczne liczniki i dopasowane oznaczenia. Dodamy również oryginalne zapytanie oraz czas zebrania danych. Dzięki temu tabelę można przekazać do kolejki roboczej, a później ustalić, dlaczego konkretny film się w niej znalazł.

Słownik oznaczeń ustala redaktor lub specjalista ds. zgodności. Zacznij od języka i terminów rzeczywiście używanych w kampanii, następnie przejrzyj wyniki i w razie potrzeby rozszerz listę. W poniższym kodzie wartości są celowo proste: należy je dostosować do konkretnej marki, rynku i języka treści.

Łączenie z TikTok Scraper API

Dokumentacja jsonscraper wskazuje trasę GET /searchVideo pod adresem bazowym https://tiktok.evelode.com do wyszukiwania filmów. Wymaganym parametrem jest keyword; wśród parametrów opcjonalnych znajdują się count, date_posted, sort_by i region. Klucz przekazuje się jako license_key, dlatego należy przechowywać go w zmiennej środowiskowej, a nie w kodzie ani pliku CSV. Dokładne nazwy parametrów i trasę podano w dokumentacji endpointów TikToka; informacje o produkcie i dostępie znajdują się na stronie TikTok Scraper API.

Istotna cecha odpowiedzi, która wpływa na kompletność lokalnego parsera: dane mogą znajdować się w tiktok.aweme_list albo w tiktok.search_item_list[].aweme_info. Dlatego skrypt sprawdza obie tablice. Jeśli wyszukiwanie zwróci pustą listę, utworzy pusty plik CSV, zamiast podstawiać fikcyjne wiersze.

Przykład w Pythonie: wyszukiwanie, filtr i plik CSV

Przykład korzysta wyłącznie ze standardowej biblioteki Pythona 3.8 lub nowszego. Przed uruchomieniem ustaw w środowisku zmienną JSONSCRAPER_TIKTOK_LICENSE_KEY. Zapytanie używa parametru keyword, a klucz jest przekazywany w parametrze zapytania license_key, zgodnie ze specyfikacją.

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 = ["reklama", "partnerstwo", "partnerstwo", "sponsor", "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 zwróciło zewnętrzny status inny niż ok")

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"Zapisano {len(rows)} kandydatów do weryfikacji w tiktok_review_queue.csv")

Skrypt najpierw sprawdza status zewnętrzny, a następnie odczytuje obiekt tiktok i łączy dostępne warianty tablicy. Usuwanie duplikatów na podstawie aweme_id zapobiega powielaniu wierszy, jeśli ten sam film pojawił się w obu ścieżkach odpowiedzi. Statystyki są zapisywane w otrzymanej postaci; brakująca wartość pozostaje pusty, a nie zamienia się w zero.

Przykład wykorzystuje parametry udokumentowane dla /searchVideo: date_posted dopuszcza wartość this-month, sort_by — date-posted, a region przyjmuje kod kraju. Wartość count określa rozmiar żądanych wyników, ale nie gwarantuje kompletnej listy publikacji. Przy dalszej paginacji zachowuj zwrócony kursor jako nieprzezroczystą wartość i przekazuj go w parametrze cursor.

Weryfikacja przez człowieka i automatyzacja uruchamiania

Przekaż plik CSV osobie odpowiedzialnej za weryfikację wraz z krótką instrukcją: otworzyć link, obejrzeć film i kontekst opisu, zapisać wniosek oraz dodać komentarz, jeśli oznaczenie zostało użyte w innym znaczeniu. Na przykład automatyczny filtr nie odróżnia ujawnienia reklamowego od dyskusji o tym, jak działa reklama. Weryfikacja przez człowieka pozwala uwzględnić to znaczenie.

Aby zbieranie danych było powtarzalne, uruchamiaj skrypt zgodnie z harmonogramem za pomocą crona, harmonogramu CI lub orkiestratora zadań. Zapisuj pliki CSV z datą uruchomienia albo przesyłaj wiersze do tabeli z unikatowym kluczem składającym się z identyfikatora filmu i daty obserwacji. Jeśli potrzebny jest dziennik audytu, przechowuj także oryginalną odpowiedź JSON z kontrolą dostępu: umożliwia ona ponowne sprawdzenie przetwarzania i wyjaśnienie, skąd pochodzi każdy wiersz.

W wersji produkcyjnej warto dodać obsługę błędów sieciowych i HTTP, ograniczenie liczby ponowień oraz powiadomienia o awarii. Nie drukuj pełnego adresu URL zapytania, ponieważ zawiera klucz dostępu. W zespołach wieloosobowych rozsądne jest przechowywanie sekretu w menedżerze sekretów środowiska wykonawczego oraz ograniczenie dostępu do wynikowych plików zgodnie z wewnętrznymi zasadami.

Co dokładnie zapewni taka lista

Po uruchomieniu zespół otrzyma powtarzalną próbkę filmów znalezionych za pomocą słowa kluczowego oraz jasne uzasadnienie umieszczenia każdego kandydata w kolejce. Z tabeli można ręcznie usunąć nieistotne dopasowania, przydzielić osobę weryfikującą i pogrupować wyniki według oznaczenia lub autora. Regularne zbieranie danych pozwoli dodatkowo śledzić, które filmy znajdowały się w zwracanych wynikach w konkretnym dniu.

To podejście nadaje się do wstępnego wykrywania i kierowania materiałów do weryfikacji, a nie do automatycznego orzekania o zgodności z zasadami. Jest ograniczone wynikami wyszukiwania, wybranym słowem kluczowym, ustawieniami zapytania i oznaczeniami tekstowymi. Aby sprawdzić konkretne współprace, porównaj film z briefem i informacjami dostępnymi zespołowi, a następnie oceń sam przekaz zgodnie z obowiązującymi zasadami.

Aby rozpocząć, sprawdź aktualny dostęp i parametry na stronie produktu TikTok Scraper API, a format odpowiedzi i dostępne warianty integracji zweryfikuj w oficjalnej dokumentacji API.