Tiktok Dashboard

TikTok Dashboard. Metricas Diarias Automaticas

Quando Usar

• Quando o aluno quiser monitorar o crescimento do proprio perfil no TikTok de forma automatica, sem precisar abrir ferramentas toda manha.
• Como base de dados para /copy-social (conteudo baseado no que ja funciona) e para analisar padroes de videos que viralizaram.
• Quando o aluno precisar mostrar evolucao de metricas para clientes ou parceiros.

Nao usar para:

• Analisar perfis de concorrentes (adaptar o script passando outro username).
• Perfis privados (o Apify nao coleta dados de perfis privados).

O Que Entrega

Como Funciona

atualizar.py
  ├── POST Apify (ator TikTok, sync) — perfil
  │     username → seguidores, seguindo, likes totais, bio, avatar
  │     Baixa avatar → base64
  ├── POST Apify (ator TikTok, sync) — videos
  │     username → ultimos N videos
  │     Para cada video: views, likes, comentarios, compartilhamentos,
  │                      saves, duracao, hashtags, descricao, data
  │     Baixa thumbnail de cada video → base64
  ├── Calcula metricas: engajamento = (likes+comentarios+shares) / views
  ├── Atualiza historico.json com snapshot do dia
  └── Regenera dashboard.html com dados + thumbnails embutidos como variavel JS

O dashboard.html e sempre autossuficiente: dados e thumbnails embutidos diretamente no HTML. Nao depende de servidor local. Funciona abrindo direto no navegador, inclusive offline apos a primeira geracao.

APIs Utilizadas

Ator utilizado: clockworks~tiktok-scraper (o mais estavel e completo em 2026).

Chamada sync (endpoint run-sync-get-dataset-items). Uma unica chamada retorna perfil (via authorMeta do primeiro item) e todos os videos. Nao ha chamada separada de perfil.

Por que sync e nao async: mesmo motivo do Instagram: endpoints async retornam run IDs que podem ficar inacessiveis dependendo do plano. Sync e mais simples e confiavel.

Todas as thumbnails em base64: TikTok CDN pode bloquear imagens em HTML local. O script baixa cada thumbnail com requests usando User-Agent e Referer adequados.

Custo por execucao: a definir (depende do ator escolhido e do numero de videos coletados).

Compatibilidade por Sistema Operacional

Instalacao da dependencia (unica):

pip install requests

Configuracao Necessaria

Dashboard: O Que Mostra

ESTRUTURA OBRIGATORIA — todas as secoes devem estar presentes, nesta ordem:

1. Cabecalho (perfil): avatar em base64 (fallback: inicial do nome), @username, bio, total de likes, ultima atualizacao
2. Visao Geral (KPIs): seguidores, engajamento medio (%), total de videos, formato/duracao mais comum
3. Evolucao ao Longo do Tempo: tendencia de seguidores e engajamento medio entre execucoes. So aparece com 2+ snapshots em historico.json.
4. Desempenho por Duracao: videos agrupados por faixa de duracao (ate 15s, 16-30s, 31-60s, 60s+). Media de views, likes, engajamento.
5. Melhores Horarios para Postar: heatmap 7x24 (dia da semana x hora). Intensidade = engajamento medio.
6. Frequencia de Postagem: videos por semana vs engajamento. Insight comparando semanas mais ativas.
7. Top 3 Videos: os 3 com maior views ou engajamento, com thumbnail em base64, views, likes, comentarios, shares, saves, taxa de engajamento e link.
8. Analise de Hashtags: top 10 hashtags por engajamento medio. Barras horizontais.
9. Tamanho da Descricao vs Engajamento: 3 buckets (curta, media, longa) com engajamento medio por faixa.
10. Linha do Tempo (graficos): views, likes, engajamento (%), saves ao longo do tempo. Canvas puro, tooltip.
11. Barra de Filtros: filtros por duracao e periodo (7/15/30 dias). Afeta grade de videos, Top 3 e KPIs.
12. Todos os Videos (grade): thumbnail em base64, views, likes, comentarios, shares, saves, data, descricao truncada e link.

NUNCA omitir nenhuma dessas 12 secoes.

Metricas TikTok (diferente do Instagram)

Nota de implementacao: os nomes exatos dos campos dependem do ator Apify escolhido. Verificar no JSON de retorno antes de codar.

Fluxo

PASSO -1. Verificar Plataforma Ativa (OBRIGATORIO — executar antes de qualquer outra coisa)

Leia .env. Verifique o valor de TIKTOK_ATIVO.

Cenario: TIKTOK_ATIVO=false (aluno ja disse que nao tem TikTok)

Voce marcou que nao tem um perfil ativo no TikTok.

Quer atualizar essa preferencia?

1. Sim, tenho TikTok agora — configurar o dashboard
2. Nao, pode ignorar

Se escolher 1: apague a linha TIKTOK_ATIVO=false do .env (ou troque por TIKTOK_ATIVO=true) e continue para o PASSO 0. Se escolher 2: encerre sem fazer nada.

Cenario: TIKTOK_ATIVO nao existe no .env (primeira vez)

Voce tem um perfil ativo no TikTok que quer monitorar?

1. Sim, tenho TikTok
2. Nao tenho TikTok

Se escolher 1: salve TIKTOK_ATIVO=true no .env (Edit cirurgico, adicionar linha). Continue para o PASSO 0. Se escolher 2: salve TIKTOK_ATIVO=false no .env. Encerre com:

Tudo bem. Se um dia criar um perfil no TikTok, e so chamar essa skill de novo.

Cenario: TIKTOK_ATIVO=true (aluno confirmou que tem TikTok)

Continue direto para o PASSO 0 sem perguntar nada.

PASSO 0. Detectar Estado

Antes de qualquer pergunta, leia em paralelo:

1. .env na raiz do projeto — existe APIFY_API_TOKEN com valor? existe TIKTOK_USER com valor?
2. meus-produtos/{ativo}/entregas/tiktok-dashboard/dashboard.html — o arquivo existe?

Cenario A. Dashboard ja configurado (dashboard.html existe)

Mostre o menu sem perguntas:

Dashboard do TikTok ja esta configurado.

Perfil monitorado: @{TIKTOK_USER do .env}

O que quer fazer?

1. Abrir o dashboard agora
2. Atualizar os dados agora
3. Trocar o perfil monitorado
4. Recriar o script do zero

Cenario B. Primeira configuracao

1. Username do TikTok

Prioridade: ler .env primeiro (TIKTOK_USER). Se encontrar, confirme:

Encontrei o TikTok configurado: @{username}

E esse mesmo perfil que quer monitorar?

1. Sim, pode continuar
2. Nao, quero usar outro

Se nao encontrar, pergunte:

Qual o usuario do seu perfil no TikTok? (so o nome, sem o arroba)
(ex: meuperfil)

Normalize: sem @, lowercase. Salve com Edit cirurgico no .env: TIKTOK_USER=<username>.

2. Token Apify

Se APIFY_API_TOKEN estiver no .env: use diretamente, nao pergunte. Se nao estiver: execute a skill configurar-apify e retorne aqui apos concluir.

PASSO 1. Confirmacao

Configuracao confirmada:

- Perfil TikTok: @{username}
- Token Apify: configurado
- Script: .claude/skills/tiktok-dashboard/scripts/atualizar.py
- Dashboard: meus-produtos/{ativo}/entregas/tiktok-dashboard/dashboard.html

1. Tudo certo, gerar agora
2. Quero ajustar algo

PASSO 2. Executar

python .claude/skills/tiktok-dashboard/scripts/atualizar.py --abrir

macOS / Linux: python3 ...

Leia o log para confirmar sucesso:

tail -10 meus-produtos/{ativo}/entregas/tiktok-dashboard/log.txt

Erros comuns:

PASSO 3. Entrega

Apos confirmar sucesso no log, atualize o painel de entregas:

py -3 scripts/painel-incremental.py --secao dashboards

(macOS/Linux: python3 scripts/painel-incremental.py --secao dashboards)

Se o painel ainda nao existir, informe:

O painel de entregas ainda nao foi criado para este produto.
Rode /produto-concepcao primeiro para gerar o painel, depois atualize os dashboards.

Informe ao aluno:

Dashboard do TikTok gerado.

Acesse pelo Painel de Entregas:
meus-produtos/{ativo}/painel-entregas.html  (aba Dashboards)

Para atualizar os dados quando quiser:
python .claude/skills/tiktok-dashboard/scripts/atualizar.py
(depois rode: py -3 scripts/painel-incremental.py --secao dashboards)

Perfil monitorado: @{username}

Sem agendamento automatico: o aluno roda o script manualmente.

PASSO 4. Verificar Proxima Plataforma na Fila

Apos confirmar entrega com sucesso, verifique se meus-produtos/{ativo}/.dashboard-queue.json existe.

Se o arquivo NAO existir: exibir os "Proximos Passos" normalmente e encerrar. (Skill foi chamada diretamente, sem fila.)

Se o arquivo EXISTIR:

1. Leia o conteudo do arquivo.
2. Mova "tiktok" de pendentes para concluidos (Edit cirurgico no JSON).
3. Verifique se ainda ha itens em pendentes.

Se pendentes estiver vazio: delete o arquivo .dashboard-queue.json. Exiba:

Todos os dashboards foram gerados.

E encerre.

Se pendentes tiver proxima plataforma, exiba a oferta de continuacao:

TikTok concluido.

Proximo na fila: {Plataforma} ({@username ou canal, se ja estiver no .env})

1. Gerar o dashboard do {Plataforma} agora
2. Parar por aqui (posso continuar depois chamando /dashboard-social)

• Opcao 1: executar a skill correspondente (youtube-dashboard).
• Opcao 2: encerrar sem alterar a fila. Na proxima chamada a /dashboard-social, o arquivo sera detectado e oferecera retomada automatica.

Regra: nunca exibir os "Proximos Passos" quando o arquivo de fila existir. A fila tem prioridade sobre as sugestoes de conteudo.

Regras

• Sempre ler .env antes de pedir o token Apify ao usuario. Se APIFY_API_TOKEN estiver presente, usar diretamente.
• O token Apify e o username ficam no .env (APIFY_API_TOKEN e TIKTOK_USER). Nunca hardcodar no script.
• Dashboard em HTML puro. Sem libs externas alem de Google Fonts. Canvas puro para graficos.
• Nao usar travessao em nenhum texto exibido no dashboard.
• Design system Fluxo Criativo: fundo #000000, surface #111111, borda #252525, texto #e8e8e6, muted #a8a8a3, neon #c4ff5e como cor de destaque principal. Fontes JetBrains Mono + Space Grotesk via Google Fonts. Cards com border-top:2px solid, sem sombra, sem border-radius.
• Se o perfil for privado, informar e encerrar com orientacao.
• CRITICO — Thumbnails obrigatorias em base64: NUNCA usar URL do CDN do TikTok diretamente como src de img. Baixar via requests com User-Agent adequado.
• CRITICO — Engajamento no TikTok e calculado sobre views, nao sobre seguidores. Formula: (likes + comentarios + shares) / views * 100.

Proximos Passos Apos Configurar

• /copy-variacao-post — criar variacoes dos videos com mais views
• /copy-social — criar conteudo novo baseado nos videos com mais engajamento
• /copy-anuncio — transformar os dados em anuncios com angulos testados