CDCStream/skills

Diferença semanal da biblioteca de anúncios

Colete os anúncios atualmente visíveis de cada concorrente nas bibliotecas públicas de anúncios, compare-os com o snapshot da semana anterior e escreva um relatório curto do que é novo, o que parou e o que os novos anúncios estão dizendo.

O que as bibliotecas públicas de anúncios podem e não podem informar

Declare estes limites em todos os relatórios. Não deixe o leitor inferir mais.

• As bibliotecas públicas de anúncios não mostram gastos, impressões ou conversões para anúncios comerciais comuns. O Google publica faixas de gastos e impressões apenas para anúncios eleitorais; o Meta mostra detalhamentos de alcance apenas para alguns anúncios entregues na UE e políticos; o LinkedIn mostra impressões e segmentação para um subconjunto de anúncios. Nunca estime orçamento ou desempenho a partir da contagem de anúncios.
• "Não está na biblioteca" não significa "não está anunciando": as bibliotecas têm escopo por país e podem ter um atraso de um dia ou mais.
• A biblioteca do TikTok cobre apenas anúncios exibidos na UE/EEE, Reino Unido e Suíça. Fora desses países, diga "TikTok: não coberto" — não reporte zero anúncios.
• As datas de primeira/última exibição de um anúncio são dias corridos, não horários exatos.

Entradas a coletar primeiro

1. Concorrentes: nome da marca e, se conhecido, URL da página do Meta, nome do anunciante no Google e nome da empresa no LinkedIn.
2. Países (códigos de duas letras). Padrão: US. Adicione um país da UE/Reino Unido como GB ou DE se o TikTok for relevante.
3. Caminho do arquivo de snapshot. Padrão: ad-library-snapshot.json no diretório de trabalho.
4. Se deve buscar detalhes e textos dos novos anúncios (mais créditos, melhor relatório).

Estimativa de créditos — mostre antes de executar

Por concorrente, por país:

Etapa	Endpoint	Créditos
Encontrar página do Meta	/v1/ad-library/facebook/search-companies	2
Anúncios do Meta	/v1/ad-library/facebook/company-ads	2
Encontrar anunciante do Google	/v1/ad-library/google/advertiser-search	1
Anúncios do Google	/v1/ad-library/google/company-ads	2
Anúncios do LinkedIn	/v1/ad-library/linkedin/search-ads	2
Anúncios do TikTok (UE/EEE/Reino Unido/CH apenas)	/v1/ad-library/tiktok/search	2 (até 5 em seu caminho alternativo)

Isso representa cerca de 11 créditos por concorrente por país (9 onde o TikTok não é coberto). As etapas de busca podem ser ignoradas em execuções posteriores salvando o ID da página e o ID do anunciante no snapshot.

Opcional, apenas para novos anúncios: detalhes (.../ad-details, 2 cada) e texto do anúncio do Meta (/v1/ad-library/facebook/ad-transcript, 2 cada). Limite estes — por exemplo, a 5 novos anúncios por concorrente — e informe isso na estimativa.

Imprima a estimativa (concorrentes × países × 11, mais o limite de detalhes) e verifique o saldo com GET /v1/account/balance (gratuito). Peça confirmação ao usuário antes de gastar.

Como chamar a Captapi

Qualquer caminho funciona; use o que o ambiente tiver.

• MCP: ferramentas nomeadas conforme o endpoint, por exemplo facebook_ad_library_company_ads, google_ad_library_company_ads, linkedin_ad_library_search_ads, tiktok_ad_library_search.
• REST: GET https://api.captapi.com<path>?<params> com cabeçalho Authorization: Bearer $CAPTAPI_API_KEY.

Chamadas com falha custam 0 créditos. Um erro retryable: true pode ser repetido uma vez após uma breve espera; retryable: false é uma resposta final — registre-a, não faça loop.

Passos

1. Carregue o snapshot se existir. Ele mapeia concorrente → país → biblioteca → {ids: [...], meta: {...}} mais os IDs de busca salvos.
2. Resolva IDs apenas onde o snapshot não tiver:
   • Meta: facebook/search-companies?q=<marca>&country=<cc> → selecione a página com nome correspondente; mantenha seu pageId. Se várias parecerem certas, pergunte.
   • Google: google/advertiser-search?q=<marca>&country=<cc> → mantenha o ID do anunciante do resultado correspondente.
3. Colete anúncios atuais para cada concorrente e país:
   • facebook/company-ads?url=<pageId ou URL da página>&country=<cc>&status=active
   • google/company-ads?advertiser=<id do anunciante ou nome>&country=<cc>
   • linkedin/search-ads?company=<nome>&country=<cc>
   • tiktok/search?q=<marca>&country=<cc> — apenas para UE/EEE/Reino Unido/CH.
4. Diferencie por ID de anúncio contra o snapshot: novo (agora, não antes), parado (antes, não agora), contínuo.
5. Enriqueça novos anúncios até o limite acordado: .../ad-details para datas e mídia, facebook/ad-transcript para título/corpo/CTA/URL de destino do Meta.
6. Escreva o relatório (formato abaixo) e salve o novo snapshot — apenas depois que o relatório for escrito, para que uma execução com falha nunca sobrescreva a semana anterior.

Formato do relatório

Para cada concorrente:

• Uma linha por biblioteca: novo N · parado N · rodando N, ou o motivo de estar faltando (não coberto neste país, busca falhou, 0 anúncios encontrados).
• Novos anúncios: título ou primeira linha do texto, formato (imagem/vídeo/carrossel), data da primeira exibição, domínio de destino e o endpoint de origem, por exemplo (fonte: /v1/ad-library/facebook/company-ads).
• Temas: 2–4 tópicos sobre ângulos que os novos anúncios compartilham (oferta, público, produto). Marque cada um como [precisa de revisão humana] — é uma interpretação.
• Anúncios parados: contagem, mais o anúncio de maior duração que parou.

Termine com a seção de limites acima, um total de créditos para a execução em uma linha e o caminho do snapshot.

Onde um humano deve revisar

• Qual página ou anunciante é "o" concorrente quando a busca retorna vários.
• Qualquer afirmação de tema ou estratégia — as bibliotecas mostram criativos, não intenção.
• Qualquer conclusão sobre orçamento ou desempenho: não há dados para isso; o relatório deve dizer isso em vez de adivinhar.