Relatório de Campanha TikTok com Métricas de Postagens Públicas

TL;DR:

• A reportagem da campanha TikTok começa com uma lista definida pelo usuário. Liste as contas da campanha e IDs das postagens antes de combinar quaisquer registros coletados.
• Uma postagem da campanha deve existir na amostra coletada. Mantenha as entradas da lista não correspondidas visíveis em vez de converter postagens ausentes em desempenho zero.
• Instantâneas com timestamp transformam contadores cumulativos em deltas. Subtraia o valor observado anteriormente de uma postagem do seu valor observado mais tarde somente quando ambos os registros compartilharem o mesmo ID da postagem e métrica.
• O envolvimento público não é atribuição. Contagens de plays, curtidas, comentários, compartilhamentos, coletas e repostagens não provam alcance único, vendas ou ROI.
• Distribuições mostram a forma da campanha. Relate medianas, intervalos e compartilhamento das principais postagens ao lado dos totais.
• Gratuito para começar. Novas contas Scrapeless incluem crédito gratuito; crie uma conta no Painel Scrapeless.

Introdução: a participação na campanha deve ser explícita

Métricas de postagens públicas respondem a uma pergunta restrita: quais contadores estavam visíveis para uma postagem conhecida em um horário registrado? Elas não identificam quem viu a postagem, quem comprou um produto ou qual interação causou uma conversão.

Este guia constrói a reportagem de campanhas TikTok em torno desse limite. Um usuário fornece as contas participantes e IDs das postagens, o pipeline combina esses IDs com amostras de postagens públicas coletadas, e instantâneas repetidas produzem deltas métricos. O relatório final separa postagens correspondidas, entradas de lista não correspondidas, valores cumulativos e mudanças de intervalo.

Para a etapa de resolução de conta que precede a coleta de postagens, veja o guias do scraper de perfil TikTok.

Pipeline em um Relance

Um relatório de campanha de postagens públicas tem seis estágios:

1. Defina a lista da campanha e os limites de reportagem.
2. Resolva cada conta pública listada para sec_uid.
3. Colete uma amostra de postagens limitada para cada conta.
4. Combine os itens coletados com os IDs de postagens da campanha fornecidos.
5. Salve instantâneas métricas com timestamp e calcule deltas comparáveis.
6. Resuma a cobertura correspondente, distribuições e postagens notáveis.

A lista define a atribuição de pertencimento para este relatório. O scraper não descobre quais postagens pertencem à campanha, e uma menção ou hashtag sozinha não deve adicionar uma postagem, a menos que as regras de reportagem digam o contrário.

Pré-requisitos

• Uma conta Scrapeless e token da API do Painel Scrapeless
• Uma lista de campanhas contendo nomes de usuário de conta e IDs exatos de postagens
• Uma política de coleta fixa e pelo menos duas observações com timestamp para deltas
• Um token ativo exportado como SCRAPELESS_API_KEY para o código abaixo

O exemplo tem uma lacuna de pré-requisito porque depende da credencial da API do leitor, lista da campanha e postagens públicas ativas. Nenhuma saída de exemplo é apresentada como um resultado de campanha real.

Estágio 1: Criar a Lista da Campanha

A lista é a tabela de controle para o relatório. Cada linha deve conter um ID da campanha, nome de usuário público, ID da postagem, URL da postagem esperada quando conhecida, data de publicação planejada, se fornecida pela equipe da campanha, e um rótulo legível por humanos.

Mantenha os IDs das postagens como strings. Identificadores grandes podem perder precisão quando ferramentas de planilha ou análise os forçam a números.

A lista também deve distinguir postagens obrigatórias e opcionais. Uma postagem obrigatória que não aparece na amostra coletada precisa de um status unmatched e uma nota de revisão; suas métricas são desconhecidas, não zero.

Estágio 2: Coletar Postagens Públicas para Contas Listadas

O caminho de coleta usa scraper.tiktok.user.detail para resolver unique_id em sec_uid, seguido de scraper.tiktok.user.work para solicitar postagens públicas. A solicitação de postagens suporta cursor e count, e sua resposta contém um array items.

Use a mesma contagem solicitada para contas comparáveis, mas relate a contagem retornada para cada uma. A documentação disponível confirma a entrada do cursor sem estabelecer um loop de histórico completo universal. Se uma postagem da campanha estiver fora da amostra coletada, marque-a como não correspondida e expanda a coleta apenas através de uma regra de continuação verificada na resposta atual e na documentação.

Cada execução de coleta precisa do seu próprio timestamp UTC. Armazene a resposta bruta do ator sob essa execução para que as métricas de nível de postagem possam ser reconstruídas se a lógica do relatório mudar.

Comece a Coletar com Scrapeless

Potencialize seu fluxo de trabalho de web scraping e automação com Scrapeless!
Inscreva-se hoje e ganhe $5 em crédito gratuito — sem necessidade de cartão de crédito.
Reivindique seu crédito gratuito agora no Painel Scrapeless.

Etapa 3: Combinar Postagens Sem Ocultar Lacunas

Combine pelo ID exato da string do post sempre que possível. URLs podem ajudar os revisores, mas a análise de URL não deve substituir um identificador estável quando ambos estão disponíveis.

A tabela de correspondência deve preservar cada linha do registro:

Este passo de reconciliação é a trilha de auditoria entre operações de campanha e coleta de dados públicos. Ele impede que um painel silenciosamente remova um post necessário ou adicione um não relacionado porque usou uma hashtag similar.

Etapa 4: Armazenar Capturas de Métricas com Timestamp

Uma linha de captura deve incluir ID da campanha, ID do post, conta, URL do post, hora da coleta, hora da criação e cada contador público presente na resposta. Armazene campos ausentes como nulos em vez de zero.

SQLite funciona bem para um histórico local compacto porque uma chave composta pode evitar observações duplicadas. A documentação do SQLite CREATE TABLE descreve chaves primárias e restrições de tabela que podem impor uma linha por post e hora de coleta.

CREATE TABLE IF NOT EXISTS campaign_post_snapshots (
    campaign_id TEXT NOT NULL,
    post_id TEXT NOT NULL,
    collected_at TEXT NOT NULL,
    account TEXT NOT NULL,
    post_url TEXT,
    play_count INTEGER,
    like_count INTEGER,
    comment_count INTEGER,
    share_count INTEGER,
    collect_count INTEGER,
    repost_count INTEGER,
    PRIMARY KEY (campaign_id, post_id, collected_at)
);

Este esquema local não tem pré-requisitos externos e pode ser testado antes que uma credencial de API esteja disponível. O código de coleta abaixo cria a mesma tabela e insere registros combinados.

Etapa 5: Calcular Deltas e Distribuição de Desempenho

Um delta métrico é o valor observado mais tarde menos o valor observado anteriormente para o mesmo post e campo. Calcule-o apenas quando ambos os valores estiverem presentes. Se uma correção de plataforma ou redefinição de campo produzir um resultado negativo, mantenha-o para revisão em vez de reescrevê-lo como zero.

Use um par compartilhado de horários de captura ao comparar postagens. Um post observado por 72 horas não deve ser classificado diretamente contra um observado por 6 horas sem um rótulo de idade ou intervalo explícito.

Os resumos da campanha se beneficiam de várias visualizações:

• Postagens combinadas divididas pelas postagens do registro
• Últimos totais cumulativos de métricas
• Deltas por post durante um intervalo comum de captura
• Mediana e faixa para cada métrica
• Participação do post principal no total de plays ou interações observadas
• Contagem de métricas nulas e entradas de registro não combinadas

A documentação do módulo statistics do Python define cálculos de mediana. Uma visualização de distribuição ajuda a mostrar se o desempenho é amplo ou concentrado, mas continua sendo uma descrição de contadores públicos.

O TikTok Ads Manager fornece um ambiente separado de primeira parte para relatórios de campanhas pagas. Sua orientação de desempenho da campanha não deve ser confundida com este fluxo de trabalho de postagens públicas: as fontes de dados, acesso e métricas disponíveis diferem.

Etapa 6: Montar o Pipeline de Relatórios em Python

O seguinte script lê um CSV de registro, coleta uma amostra inicial limitada para cada conta listada, reconcilia IDs de post exatos, insere instantâneas combinadas no SQLite e escreve um arquivo de cobertura para revisão.

Nota: O código abaixo requer um token de API Scrapeless ativo em SCRAPELESS_API_KEY, um campaign-roster.csv fornecido pelo leitor e postagens públicas da campanha que aparecem nas amostras coletadas.

import csv
import json
import os
import sqlite3
from datetime import datetime, timezone
from urllib.request import Request, urlopen

ENDPOINT = "https://api.scrapeless.com/api/v1/scraper/request"
TOKEN = os.environ["SCRAPELESS_API_KEY"]
REQUESTED_COUNT = 35


def run_actor(actor, actor_input):
    data = json.dumps({"actor": actor, "input": actor_input}).encode()
    request = Request(
        ENDPOINT,
        data=data,
        headers={"x-api-token": TOKEN, "content-type": "application/json"},
        method="POST",
    )
    with urlopen(request, timeout=60) as response:
        return json.load(response)


with open("campaign-roster.csv", newline="", encoding="utf-8") as roster_file:
    roster = list(csv.DictReader(roster_file))

for row in roster:
    row["username"] = row["username"].lstrip("@")
    row["post_id"] = str(row["post_id"])

collected_at = datetime.now(timezone.utc).isoformat()
items_by_account = {}

for username in sorted({row["username"] for row in roster}):
    profile = run_actor("scraper.tiktok.user.detail", {"unique_id": username})
    response = run_actor(
        "scraper.tiktok.user.work",
        {"sec_uid": profile["sec_uid"], "cursor": "0", "count": REQUESTED_COUNT},
    )
    with open(f"{username}-{collected_at[:10]}-raw.json", "w", encoding="utf-8") as raw_file:
        json.dump(response, raw_file, ensure_ascii=False, indent=2)
    items_by_account[username] = {
        str(item.get("id") or item.get("post_id") or ""): item
        for item in response.get("items") or []
    }

connection = sqlite3.connect("campaign-reporting.db")
connection.execute("""
CREATE TABLE IF NOT EXISTS campaign_post_snapshots (
    campaign_id TEXT NOT NULL,
    post_id TEXT NOT NULL,
    collected_at TEXT NOT NULL,
    account TEXT NOT NULL,
    post_url TEXT,
    play_count INTEGER,
    like_count INTEGER,
    comment_count INTEGER,
    share_count INTEGER,
    collect_count INTEGER,
    repost_count INTEGER,
    PRIMARY KEY (campaign_id, post_id, collected_at)
)
""")

coverage = []
for row in roster:
    item = items_by_account.get(row["username"], {}).get(row["post_id"])
    status = "matched" if item else "unmatched"
    coverage.append({**row, "status": status, "collected_at": collected_at})
    if not item:
        continue
    connection.execute(
        """INSERT OR REPLACE INTO campaign_post_snapshots VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
        (
            row["campaign_id"], row["post_id"], collected_at, row["username"],
            item.get("url") or item.get("post_url"), item.get("play_count"),
            item.get("like_count"), item.get("comment_count"), item.get("share_count"),
            item.get("collect_count"), item.get("repost_count"),
        ),
    )

connection.commit()
connection.close()

with open("campaign-coverage.csv", "w", newline="", encoding="utf-8") as output:
    writer = csv.DictWriter(output, fieldnames=coverage[0].keys())
    writer.writeheader()
    writer.writerows(coverage)

Execute a mesma coleta na próxima hora de observação planejada e, em seguida, junte linhas de captura consecutivas por ID da campanha e ID do post. Calcule cada delta apenas onde ambos os valores métricos são não nulos e mantenha os dois timestamps de coleta no resultado.

Modelo de Relatório da Campanha

O relatório deve separar cobertura de desempenho:

Lidar com Dados de Campanha Responsavelmente

A reportagem da campanha pode conectar conteúdo de criadores públicos com contratos, rótulos internos ou decisões comerciais. Restringir o acesso à lista e anotações internas, minimizar os dados pessoais retidos e definir quem pode corrigir um erro de atribuição.

Para programas de influenciadores, a orientação de divulgação da FTC é uma referência primária útil para responsabilidades de divulgação nos Estados Unidos. Isso não substitui aconselhamento jurídico ou as regras que se aplicam em outra jurisdição.

Scrapeless fornece o perfil e posts de atores através da API de Scraping. Revise a página de preços atual antes de escolher as contagens de conta e a frequência de instantâneas.

Conclusão: relate o que as instantâneas provam

A reportagem de campanha do TikTok precisa de uma lista explícita, correspondência exata de ID de post, observações com timestamp e lacunas de cobertura visíveis. Esses controles transformam contadores públicos em um registro auditável de posts correspondidos e mudanças de métricas, mantendo alcance, vendas e reivindicações de atribuição em suas fontes de dados adequadas.

Pronto para Construir um Relatório de Métricas de Campanha?

Junte-se ao Scrapeless Discord ou à comunidade do Telegram para comparar padrões de modelagem de dados. Crie uma conta no Painel Scrapeless quando a lista da campanha estiver pronta.

FAQ

Q: O que é a reportagem de campanha do TikTok com métricas de postagens públicas?

A reportagem de campanha do TikTok com métricas de postagens públicas rastreia contadores visíveis para um conjunto definido de postagens de campanha em horários registrados. Mede essas observações e suas mudanças, não o alcance único, vendas ou atribuição causal.

Q: Como o fluxo de trabalho decide quais postagens pertencem a uma campanha?

A lista fornecida pelo usuário decide a adesão à campanha. O pipeline corresponde a IDs de postagem exatos e mantém postagens ausentes ou inesperadas fora dos totais de desempenho até que sejam revisadas.

Q: Qual é a diferença entre uma instantânea de métrica e um delta?

Uma instantânea é um contador público cumulativo observado em um momento. Um delta é a diferença entre duas instantâneas válidas para a mesma postagem, métrica e intervalo definido.

Q: A contagem de reproduções pode ser relatada como alcance da campanha?

A contagem de reproduções não deve ser relatada como alcance único da campanha. É um contador de postagens públicas e não estabelece quantas pessoas distintas viram o conteúdo.

Q: Postagens de campanha não correspondidas devem receber métricas zero?

Postagens de campanha não correspondidas devem receber um status unmatched e métricas nulas. Zero afirmaria um valor observado que a coleção não produziu.

Q: O fluxo de trabalho substitui o TikTok Ads Manager?

O fluxo de trabalho de postagens públicas não substitui o TikTok Ads Manager ou outros sistemas de campanha de primeira parte. Ele produz um conjunto de dados separado dos campos de postagens públicas suportadas.

Q: A coleta de dados de campanha pública é legal?

A legalidade depende da jurisdição, finalidade, dados, método de acesso, contratos e termos aplicáveis. Limite a coleta a campos públicos necessários, proteja os dados da lista interna e obtenha aconselhamento jurídico para o programa específico.