Come creare un report settimanale su TikTok delle reazioni al lancio di un prodotto

Dopo il lancio di un’app o di una nuova funzionalità, il feedback si disperde rapidamente tra i video brevi. Un addetto al marketing trova manualmente alcuni video e ne condivide i link in chat; più tardi, l’analista non riesce a capire quali pubblicazioni siano già state conteggiate né come siano cambiate le visualizzazioni. Una soluzione pratica consiste nel raccogliere regolarmente i risultati di ricerca con alcune query stabili, salvare le risposte originali e creare report usando solo i campi verificati.

In questa guida configureremo la raccolta per un caso specifico: un team ha lanciato una nuova funzionalità e vuole monitorare ogni settimana i video pubblici di TikTok le cui descrizioni menzionano il nome del prodotto, una funzione chiave o un problema tipico degli utenti. Si tratta di monitorare un campione di risultati di ricerca: l’API restituisce risultati in base alla query e ai parametri, non un elenco garantito di tutte le pubblicazioni sul lancio.

Per prima cosa, stabilite quale segnale serve al team

Un numero elevato di visualizzazioni, da solo, spiega poco su cosa fare dopo. È più utile sapere quali domande si ripetono, quali casi d’uso vengono mostrati e quali video ottengono reazioni pubbliche significative. Perciò, iniziate formulando alcune query e decidendo quali campi includere nel report.

Per esempio, per il lancio di uno strumento di pianificazione delle pubblicazioni, potete provare le query «nome del prodotto», «pianificatore di contenuti» e «come programmare un TikTok». Le frasi dovrebbero riflettere i diversi modi in cui le persone potrebbero descrivere lo stesso argomento. Annotatele insieme alla data di avvio del monitoraggio e alla regione, così da poter confrontare le raccolte successive mantenendo le stesse impostazioni.

Una tabella minima può contenere l’ora della raccolta, la query, l’identificatore e il link del video, la descrizione, il nome e l’identificatore dell’autore, oltre ai valori disponibili per visualizzazioni, Mi piace e commenti. La documentazione di TikTok Scraper API indica per i risultati di ricerca campi quali aweme_id, desc, share_url, informazioni sull’autore e alcune statistiche. Verificate ogni campo nel singolo oggetto: alcune metriche potrebbero mancare.

Collegatevi alla ricerca documentata

Per cercare video, usate la route GET /searchVideo sull’indirizzo di base https://tiktok.evelode.com. La documentazione elenca il parametro obbligatorio keyword e quelli facoltativi count, cursor, date_posted, sort_by, region e cache_timeout. Tra i valori ammessi per il filtro della data c’è this-week; per l’ordinamento sono disponibili relevance, most-liked e date-posted. Consultate il riferimento delle route di TikTok API per verificarne nomi e funzioni.

La chiave di licenza viene passata come parametro di query license_key. In uno script di produzione, leggetela dalla variabile d’ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY, non inseritela nel codice sorgente e non scrivetela nei log. Questo esempio è pensato per Python 3.8+ e usa il pacchetto requests:

import os
import requests

BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]


def search_videos(keyword, cursor=None):
    params = {
        "license_key": API_KEY,
        "keyword": keyword,
        "count": 20,
        "date_posted": "this-week",
        "sort_by": "date-posted",
        "region": "US",
    }
    if cursor is not None:
        params["cursor"] = cursor

    response = requests.get(
        f"{BASE_URL}/searchVideo",
        params=params,
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("TikTok API ha restituito uno status diverso da ok")

    return payload["tiktok"]


result = search_videos("content planning app")
print("Oggetti trovati:", len(result.get("aweme_list", [])))

Lo script verifica gli errori HTTP e lo status esterno della risposta. Una risposta HTTP riuscita non garantisce, da sola, che la ricerca contenga video: se il campione è vuoto, l’elenco potrebbe non contenere elementi. Alla prima esecuzione è utile salvare la risposta completa in un archivio protetto, così da confrontare gli oggetti reali con la tabella dei campi normalizzati.

Gestite entrambi i formati dei risultati di ricerca

I risultati di ricerca presentano una particolarità strutturale importante. I video possono trovarsi direttamente in tiktok.aweme_list, oppure all’interno di tiktok.search_item_list[].aweme_info. Un gestore che legge soltanto il primo elenco potrebbe quindi ignorare i risultati presenti nel secondo formato.

aggiungete un piccolo normalizzatore che supporti entrambe le strutture e ignori senza errori gli elementi privi dell’oggetto video annidato:

def extract_awemes(tiktok):
    items = list(tiktok.get("aweme_list") or [])

    for item in tiktok.get("search_item_list") or []:
        aweme = item.get("aweme_info")
        if aweme:
            items.append(aweme)

    return items


def normalize(aweme, keyword, collected_at):
    author = aweme.get("author") or {}
    stats = aweme.get("statistics") or {}

    return {
        "collected_at": collected_at,
        "keyword": keyword,
        "video_id": aweme.get("aweme_id"),
        "posted_at": aweme.get("create_time"),
        "description": aweme.get("desc"),
        "share_url": aweme.get("share_url"),
        "author_id": author.get("uid"),
        "author_name": author.get("nickname"),
        "views": stats.get("play_count"),
        "likes": stats.get("digg_count"),
        "comments": stats.get("comment_count"),
        "shares": stats.get("share_count"),
    }

I valori mancanti restano None. Non sostituiteli con zero: zero indica un valore misurato, mentre None conserva l’informazione che il campo non era presente. Questa differenza influisce su medie, percentuali e qualsiasi conclusione del team.

Conservate la cronologia, non soltanto l’istantanea attuale

Per osservare l’andamento, conservate record di osservazione separati. L’identificatore del video è adatto a deduplicare le pubblicazioni, ma non a eliminare la cronologia: se lo stesso video ricompare nella raccolta successiva, si ottiene un nuovo punto di osservazione. Per esempio, la chiave univoca della tabella delle osservazioni può essere composta da video_id e collected_at; per agevolare le verifiche, salvate il link e la descrizione nel record.

Uno schema SQLite minimo è utile per un prototipo:

import sqlite3

conn = sqlite3.connect("tiktok_observations.sqlite3")
conn.execute("""
CREATE TABLE IF NOT EXISTS observations (
    video_id TEXT NOT NULL,
    collected_at TEXT NOT NULL,
    keyword TEXT NOT NULL,
    posted_at INTEGER,
    description TEXT,
    share_url TEXT,
    author_id TEXT,
    author_name TEXT,
    views INTEGER,
    likes INTEGER,
    comments INTEGER,
    shares INTEGER,
    PRIMARY KEY (video_id, collected_at, keyword)
)
""")
conn.commit()

Nella pratica, normalizzate l’ora di raccolta in UTC, conservate il JSON originale separatamente e aggiungete una colonna per la versione dello schema. La risposta originale consente di verificare la trasformazione se la struttura dei nuovi oggetti differisce da quella abituale. Per le pubblicazioni individuate con più query, conservate le parole chiave corrispondenti in una tabella collegata separata oppure aggregatele durante la creazione del report.

Impaginazione: proseguite solo con il cursore della risposta

Il parametro cursor serve a proseguire la ricerca. Il suo valore va preso dalla risposta precedente e reinviato senza modificarlo; il processo termina quando has_more non indica più che ci sono altri risultati o quando viene raggiunto il limite stabilito. Considerate il cursore opaco: non calcolatelo autonomamente e non sostituitelo con un contatore di pagine.

def collect_pages(keyword, max_pages=3):
    cursor = None
    collected = []

    for _ in range(max_pages):
        page = search_videos(keyword, cursor)
        collected.extend(extract_awemes(page))

        if not page.get("has_more"):
            break
        cursor = page.get("cursor")
        if cursor is None:
            break

    return collected

Limitare il numero di pagine rende prevedibile il volume di richieste dell’attività ricorrente. Registrate nei log di esecuzione il numero di pagine e il valore di has_more: forniscono un contesto utile per interpretare il campione del report. Anche con l’impaginazione, il risultato descrive le risposte ottenute dall’API e il limite di raccolta impostato; non è una stima di tutte le pubblicazioni presenti sulla piattaforma.

Create un report ripetibile

Eseguite la raccolta secondo una pianificazione settimanale, o più spesso se al team servono segnali più frequenti. Per ogni esecuzione, registrate l’elenco delle query, i parametri, l’ora, il numero di oggetti ricevuti e il numero di identificatori univoci. Contate separatamente le pubblicazioni individuate per la prima volta durante l’esecuzione e quelle già comparse in precedenza.

Nel report sono utili quattro semplici viste:

• Nuovi video: link, descrizioni, date di pubblicazione e query che ha permesso di trovare ciascun video.
• Temi ricorrenti: raggruppamento delle descrizioni in categorie definite manualmente, per esempio «errore di configurazione», «richiesta di una funzione» e «panoramica di un caso d’uso».
• Reazioni pubbliche: visualizzazioni, Mi piace, commenti e condivisioni disponibili, mostrati insieme all’ora dell’osservazione.
• Segnali da verificare: nuove formulazioni, domande frequenti o video che vale la pena esaminare.

Non definite la differenza tra due istantanee «nuovi Mi piace» senza verificare il significato e l’aggiornamento dei valori nella risposta. Una formulazione corretta è «valore della metrica nell’ultima risposta ricevuta» e «differenza tra le istantanee salvate». Così il team capisce cosa è stato calcolato e può aprire la pubblicazione originale prima di prendere una decisione.

Usate l’IA per classificare, non al posto della raccolta

Dopo la normalizzazione, potete inviare le descrizioni dei video a un modello perché le classifichi secondo categorie predefinite. Inviate solo i campi di testo necessari e chiedete un risultato strutturato: categoria, breve motivazione, livello di confidenza e frammento della descrizione su cui si basa l’etichetta. Conservate la pubblicazione originale accanto all’etichetta, così che l’analista possa verificare i casi controversi.

Il flusso di lavoro resta semplice: un pianificatore avvia la raccolta; Python verifica la risposta e salva il JSON; un’attività separata normalizza i nuovi record; il classificatore elabora soltanto le nuove descrizioni; infine, il report viene generato dal database e inviato al canale scelto dal team. TikTok Scraper API fornisce i dati di ricerca, mentre la classificazione e l’invio del report fanno parte della logica d’integrazione, realizzabile in Python, n8n o Make.

Per ridurre il rumore, definite il vocabolario delle categorie prima di inviare i dati al modello e verificate periodicamente un campione etichettato manualmente. Per le descrizioni brevi o ambigue, è utile uno stato «contesto insufficiente», anziché forzare la scelta di una categoria. Le etichette dell’IA aiutano a ordinare la coda di revisione, ma le conclusioni sui problemi degli utenti vanno confermate leggendo le pubblicazioni e confrontando più osservazioni.

Errori, nuovi tentativi e gestione sicura della chiave

Una richiesta di rete può terminare per timeout, errore temporaneo o risposta non interpretabile come JSON. Suddividete la gestione in fasi: richiesta, verifica del codice HTTP, analisi del JSON, verifica dello status esterno, normalizzazione e scrittura. In caso di problemi temporanei, effettuate un numero limitato di tentativi con pause crescenti; registrate gli errori permanenti per esaminarli in seguito, senza contrassegnare l’esecuzione come riuscita.

Conservate la chiave in un gestore dei segreti dell’ambiente di esecuzione o in una variabile d’ambiente. Poiché l’API accetta license_key nella stringa di query, evitate di registrare l’URL completo e i parametri della richiesta: conterrebbero il segreto. Per la diagnosi, registrate la route, il codice di risposta, la durata, la query e l’identificatore dell’attività, rimuovendo la chiave dai log.

Impostate la pianificazione e le dimensioni del campione in base alle vostre esigenze e alle condizioni d’uso della piattaforma. La raccolta di dati pubblici dovrebbe limitarsi a ciò che serve davvero per l’analisi; le regole interne del team dovrebbero specificare come conservare descrizioni, link e identificatori degli autori. Le risposte dell’API e le metriche possono essere incomplete o cambiare tra un’osservazione e l’altra: perciò, il report dovrebbe conservare l’ora di raccolta e la provenienza di ogni riga.

Risultato: dai link condivisi manualmente a una cronologia verificabile

Una volta configurato, il team ottiene un elenco aggiornato regolarmente dei video individuati, le risposte originali per le verifiche, una tabella delle metriche pubbliche disponibili e una panoramica dei temi ricorrenti. Questo aiuta a individuare più rapidamente le domande sulla nuova funzionalità, trovare esempi di casi d’uso e selezionare le pubblicazioni da analizzare manualmente. Il confronto tra istantanee mostra come cambiano i valori salvati per i video già individuati, mentre il registro delle query spiega come è stato formato il campione.

Iniziate con una query e un limite ridotto di pagine, verificate la struttura reale della risposta, poi aggiungete altre formulazioni e una pianificazione. Prima di trasferire il prototipo in produzione, definite le regole per deduplicazione, conservazione e gestione degli errori. Le route e i parametri aggiornati sono disponibili nella documentazione ufficiale dell’API; la descrizione delle funzionalità e l’accesso alla prova sono disponibili nella pagina di TikTok Scraper API.