Hitta TikTok-videor med reklammarkeringar för granskning

När ett team behöver kontrollera hur kreatörer redovisar kopplingar till varumärken i offentliga TikTok-videor är ett användbart första resultat inte ett automatiserat utlåtande, utan en kompakt kö med videor, bildtexter, länkar och identifierade markörord. Här följer ett arbetsflöde: skicka en sökfråga via TikTok Scraper API från jsonscraper, normalisera de två möjliga svarsstrukturerna till ett gemensamt format och spara en CSV-fil för expertgranskning.

Uppgiften: hitta videor som bör granskas

Det är svårt att upprepa en manuell sökning efter ett företagsnamn på samma sätt varje gång: resultaten måste samlas in ett i taget och urvalskriterierna blir kvar i webbläsaren. Med automatiserad insamling kan frågan, kördatumet och det hittade materialet sparas i en tabell, så att teamet kan granska videorna utifrån en gemensam lista.

I det här arbetsflödet betyder ”kandidat för granskning” endast en video i den returnerade sökresultatlistan vars beskrivning innehåller ett förutbestämt ord eller uttryck. Det kan till exempel vara ”reklam”, ”partnerskap” eller ”sponsor”. Ett sådant textfilter hjälper till att rikta en människas uppmärksamhet, men bedömer inte själva videon och fastställer inte om tillämpliga krav har uppfyllts.

Den skillnaden är viktig för marknadsföringsteam. USA:s federala handelskommission beskriver redovisning av en väsentlig koppling till ett varumärke som en skyldighet vars tillämpning beror på meddelandets sammanhang; för video rekommenderar FTC att redovisningen är både synlig och hörbar. En sökning i bildtexten kan hitta vissa textsignaler, men ett beslut kräver att inlägget ses och bedöms i sitt sammanhang. FTC:s vägledning för kreatörer förklarar villkoren med exempel.

Resultat: en CSV-fil med urvalskriterier

Pipelinen skriver en rad per unikt video-ID och tar med beskrivningstext, länk, kreatörens namn, tillgängliga offentliga räknare och matchande markörer. Sökfrågan och insamlingstidpunkten läggs också till. Det gör tabellen lämplig för överlämning till en granskningskö och hjälper teamet att senare förstå varför en viss video hamnade där.

Redaktören eller en ansvarig för regelefterlevnad bestämmer vilka markörer som ska användas. Börja med språket och de termer som faktiskt förekommer i kampanjen, granska sedan urvalet och utöka listan vid behov. Värdena i koden nedan är avsiktligt enkla: anpassa dem till det aktuella varumärket, marknaden och innehållets språk.

Anslut till TikTok Scraper API

jsonscrapers dokumentation anger sökvägen GET /searchVideo på basadressen https://tiktok.evelode.com för videosökning. Den obligatoriska parametern är keyword; bland tilläggsparametrarna finns count, date_posted, sort_by och region. Nyckeln skickas som license_key, så lagra den i en miljövariabel i stället för i koden eller CSV-filen. Exakta parameternamn och sökvägen finns i TikToks endpoint-referens; produkt- och åtkomstinformation finns på produktsidan för TikTok Scraper API.

Det finns en viktig detalj i svaret som påverkar hur fullständig den lokala parsningen blir: data kan ligga i tiktok.aweme_list eller i tiktok.search_item_list[].aweme_info. Därför kontrollerar skriptet båda arrayerna. Om sökningen returnerar en tom lista skapar det en tom CSV-fil i stället för att fylla den med påhittade rader.

Python-exempel: sökning, filtrering och CSV

Exemplet använder endast standardbiblioteket i Python 3.8+. Ange JSONSCRAPER_TIKTOK_LICENSE_KEY i miljön innan du kör skriptet. Frågan använder keyword, och nyckeln skickas i frågeparametern license_key, enligt specifikationen.

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

Skriptet kontrollerar först den yttre statusen, läser sedan objektet tiktok och slår ihop de tillgängliga arrayvarianterna. Dubbletter tas bort med hjälp av aweme_id, så att samma video inte förekommer flera gånger om den dyker upp i båda svarsvägarna. Mätvärdena skrivs som de kommer; värden som saknas lämnas tomma i stället för att omvandlas till noll.

Exemplet använder parametrar som dokumenterats för /searchVideo: date_posted kan ha värdet this-month, sort_by värdet date-posted och region tar emot en landskod. Värdet för count anger storleken på den begärda resultatlistan, inte en garanti om att alla inlägg tas med. Vid fortsatt sidindelning ska den returnerade markören sparas som ett ogenomskinligt värde och skickas i parametern cursor.

Mänsklig granskning och schemaläggning

Överlämna CSV-filen till den ansvariga granskaren tillsammans med en kort instruktion: öppna länken, titta på videon och läs bildtextens sammanhang, dokumentera slutsatsen och lägg till en kommentar om markören har en annan innebörd. Automatisk filtrering kan till exempel inte skilja en reklammarkering från en diskussion om hur reklam fungerar. Mänsklig granskning överbryggar den tolkningsskillnaden.

För återkommande insamling kan du köra skriptet enligt ett schema via cron, en CI-schemaläggare eller en arbetsflödesorkestrerare. Spara CSV-filen med kördatumet eller lägg in raderna i en tabell med en unik nyckel som kombinerar video-ID och observationsdatum. Om en granskningslogg behövs, lagra även det ursprungliga JSON-svaret med åtkomstkontroll: då går det att granska omvandlingen på nytt och förklara varifrån varje rad kommer.

I en produktionsversion bör du lägga till hantering av nätverks- och HTTP-fel, begränsade omförsök och felaviseringar. Skriv inte ut hela förfrågningsadressen: den innehåller åtkomstnyckeln. För team med flera användare är det klokt att lagra hemligheten i körmiljöns hemlighetshanterare och begränsa åtkomsten till utdatafilerna enligt interna regler.

Vad listan faktiskt ger

Efter körningen har teamet en reproducerbar samling videor som hittats med en nyckelfras och ett tydligt skäl till att varje kandidat hamnat i kön. I tabellen kan ni manuellt ta bort irrelevanta träffar, utse en granskare och gruppera resultaten efter markör eller kreatör. Om insamlingen körs regelbundet får ni också en historik över vilka videor som fanns i den returnerade resultatlistan ett visst datum.

Metoden lämpar sig för inledande upptäckt och vidarebefordran av material, inte för automatiska slutsatser om efterlevnad. Den begränsas av sökresultaten, den valda nyckelfrasen, frågeinställningarna och textmarkörerna. För att granska ett specifikt samarbete bör ni jämföra videon med kampanjunderlaget och den information som teamet har tillgång till och sedan bedöma själva meddelandet enligt gällande regler.

Kontrollera aktuell åtkomst och aktuella parametrar på produktsidan för TikTok Scraper API och jämför svarsformatet och integrationsalternativen med den officiella API-dokumentationen innan du börjar.