Como raspar a Biblioteca de Anúncios do Facebook com o Navegador Scrapeless Scraping

TL;DR:

• A Biblioteca de Anúncios do Facebook é uma superfície pública — visualizar anúncios nela não exige login. Qualquer pessoa pode abrir facebook.com/ads/library, pesquisar um anunciante ou palavra-chave e ler todos os anúncios ativos e inativos que uma Página está veiculando, incluindo o nome do anunciante, o texto do anúncio e as datas em que cada anúncio foi exibido.
• A página é renderizada completamente do lado do cliente, então HTTP simples retorna uma shell vazia. Os cartões de anúncios são gerados por JavaScript após a resposta inicial, e a grade de resultados está atrás de um verificador anti-bot, então um simples requests.get não vê anúncios algum.
• O Scrapeless Scraping Browser renderiza a página do lado da nuvem e devolve o DOM pintado. Conectando-se via Chrome DevTools Protocol com egressos residenciais dos EUA e uma sessão aquecida retorna a grade de resultados totalmente renderizada, que é processada como qualquer página estática.
• Descubra cada anúncio a partir do anexo de texto estável Library ID: e não de uma classe CSS hash. Cada cartão de anúncio possui um rótulo Library ID: <dígitos>; subindo a partir desse anexo para seu contêiner de cartão único sobrevive à mudança de nomes de classe do React que quebram seletores frágeis.
• Uma pesquisa por palavra-chave retornou 27 cartões de anúncios na primeira renderização e 104 após rolar a grade seis vezes. A paginação aqui é uma rolagem infinita: a grade acrescenta mais cartões conforme você rola, então você lê o DOM após cada rolagem até que a contagem pare de crescer.
• Gratuito para começar. Novas contas Scrapeless incluem o tempo de execução gratuito do Scraping Browser — inscreva-se em app.scrapeless.com.

Introdução: leia os anúncios públicos de qualquer marca

A Biblioteca de Anúncios do Facebook é o arquivo de transparência pública da Meta sobre os anúncios veiculados no Facebook e Instagram. Cada anúncio ativo — e, para anúncios de questão social, eleitorais e políticos, cada um inativo também — é listado com o anunciante, a parte criativa e as datas em que foi exibido. Pesquisadores competitivos, equipes de segurança de marca e analistas de anúncios a consultam para ver exatamente qual mensagem uma Página está colocando na frente dos usuários neste momento.

A fricção está na renderização, não no acesso. Visualizar anúncios públicos não precisa de conta, mas a página constrói toda a sua grade de resultados no navegador após a primeira resposta, e a grade é bloqueada por defesas contra tráfego automatizado que um cliente HTTP simples ativa imediatamente. Baixe a URL com requests e os cartões de anúncios simplesmente não estão nos bytes que você recebe de volta — eles são gerados depois por JavaScript que nunca é executado. A marcação que renderiza inclina-se para nomes de classe React rotativos e hash, então um seletor preso a uma string de classe quebra na próxima implantação do front-end.

Este guia constrói a extração em Python em cima do Scrapeless Scraping Browser, um navegador em nuvem que renderiza a página com egressos residenciais dos EUA e retorna o DOM finalizado. O padrão é o mesmo loop render → descobrir → extrair → paginar que movimenta qualquer scraper, com uma reviravolta: os pontos de descoberta se ancoram no texto durável Library ID: que cada cartão imprime, então a análise sobrevive à mudança de nomes de classe. A mesma divisão de renderização estática versus dinâmica, em JavaScript, é abordada no tutorial Cheerio e Puppeteer.

O Que Você Pode Fazer Com Isso

• Rastrear a criatividade ao vivo de um concorrente. Extraia todos os anúncios ativos que uma Página está veiculando para ver mensagens, ofertas e destinos de aterrissagem atuais.
• Construir um conjunto de dados de tendências criativas. Colete o texto de anúncios de vários anunciantes em uma categoria e analise a linguagem, ganchos e formatos que se repetem.
• Monitorar o tempo das campanhas. Leia a data de "Iniciou a veiculação" nos anúncios ativos e o intervalo de veiculação nos inativos para mapear quando as campanhas são lançadas e retiradas.
• Auditar a presença da marca. Confirme quais anúncios estão vinculados a uma Página verificada e identifique impostores veiculando anúncios sob um nome semelhante.
• Alimentar um pipeline de inteligência de anúncios. Transforme a grade de resultados renderizada em linhas estruturadas — anunciante, ID da biblioteca, status, datas — que uma análise subsequente ou um modelo possa ler.
• Acesse a grade que HTTP simples não pode. A Biblioteca de Anúncios renderiza do lado do cliente atrás de um verificador anti-bot, então eleve isso a um navegador em nuvem e mantenha o mesmo código de análise que você usaria em uma página estática.

Por Que Scrapeless Scraping Browser

O Scrapeless Scraping Browser é um navegador em nuvem personalizável e anti-detecção, projetado para rastreadores web e agentes de IA. Para a Biblioteca de Anúncios especificamente, ele oferece:

• Renderização de JavaScript do lado da nuvem. A grade de resultados é gerada após a resposta inicial; o navegador em nuvem executa a página e retorna um DOM que já contém os cartões de anúncios, então o BeautifulSoup processa como HTML estático.
• Proxies residenciais em mais de 195 países. A Biblioteca de Anúncios varia seu conteúdo por país de visualização, então fixar egressos residenciais dos EUA retorna os mesmos anúncios que um visitante dos EUA veria.
• Anti-detecção de impressão digital. A página protege sua grade por trás de uma verificação de bot; o navegador em nuvem apresenta uma superfície de navegador consistente e semelhante a um humano para que a grade seja renderizada em vez de um desafio.
• Uma chave de API para tudo. O SDK Python gera um browser_ws_endpoint que você se conecta com Playwright via CDP, e a mesma chave cobre o tempo de execução.

Obtenha sua chave de API no plano gratuito em app.scrapeless.com.

Pré-requisitos

• Python 3.10 ou mais recente
• O SDK scrapeless, playwright, e beautifulsoup4
• Uma conta Scrapeless e chave de API — inscreva-se em app.scrapeless.com
• Familiaridade básica com o terminal

Instalação

Instale o SDK, o cliente de protocolo e o parser HTML:

pip install scrapeless playwright beautifulsoup4
playwright install chromium

playwright install chromium baixa um cliente de protocolo local uma vez; a renderização real ainda ocorre na nuvem Scrapeless. O SDK scrapeless gera a sessão do navegador e beautifulsoup4 analisa o DOM retornado. Exporte sua chave antes de executar qualquer coisa: export SCRAPELESS_API_KEY=your_api_token_here.

Passo 1 — Renderize a página da Biblioteca de Anúncios e confirme a presença dos anúncios

Um scrape começa com uma renderização limpa. A URL da Biblioteca de Anúncios recebe a busca em parâmetros de consulta — q para a palavra-chave, country para a geografia do visualizador, active_status e ad_type para os filtros. Conecte-se ao navegador em nuvem, aqueça a sessão na página inicial pública do Facebook primeiro para que a solicitação carregue uma superfície de navegador estabelecida, em seguida, carregue a URL de busca e conte os cards de anúncios antes de escrever um único seletor de campo.

import re
from scrapeless import Scrapeless
from scrapeless.types import ICreateBrowser
from playwright.sync_api import sync_playwright

URL = ("https://www.facebook.com/ads/library/"
       "?active_status=all&ad_type=all&country=US&q=nike")
LIB = re.compile(r"Library ID:\s*\d+")

client = Scrapeless()  # lê SCRAPELESS_API_KEY do ambiente
session = client.browser.create(ICreateBrowser(proxy_country="US", session_ttl=240))

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(session.browser_ws_endpoint)
    ctx = browser.contexts[0] if browser.contexts else browser.new_context()
    page = ctx.pages[0] if ctx.pages else ctx.new_page()
    page.goto("https://www.facebook.com/", wait_until="domcontentloaded", timeout=60_000)
    page.wait_for_timeout(3_000)  # aqueça a sessão na página inicial pública primeiro
    page.goto(URL, wait_until="domcontentloaded", timeout=60_000)
    page.wait_for_timeout(8_000)  # deixe a grade de resultados renderizar no lado do cliente
    html = page.content()
    browser.close()

print("bytes html:", len(html), "| cards de anúncios na primeira renderização:", len(LIB.findall(html)))

Isto imprime uma linha como bytes html: 1796025 | cards de anúncios na primeira renderização: 27 — aproximadamente 1.8 MB de HTML renderizado contendo 27 cards de anúncios na primeira pintura (a contagem de bytes varia de execução para execução à medida que diferentes criativos carregam). O título da página é Biblioteca de Anúncios, e o Facebook reescreve a URL para adicionar seus próprios padrões (search_type=keyword_unordered, media_type=all, um bloco sort_data). O wait_until="domcontentloaded" mais um descanso fixo é deliberado: a Biblioteca de Anúncios transmite análises e solicitações de personalização que nunca ficam inativas, portanto esperar a ocioso de rede travaria até o tempo limite. Aquecer na página inicial primeiro é o que faz a grade ser renderizada em vez de um desafio anti-bot.

Passo 2 — Descubra cada anúncio a partir de um ponto de âncora estável, depois extraia seus campos

Os nomes das classes React da grade de resultados são hash e rotacionam entre implantações, portanto um seletor como div.x1lliihq é uma responsabilidade. O sinal durável é o texto que cada card imprime: Library ID: <dígitos>. Descubra a âncora nesse rótulo, suba para o maior ancestral que ainda envolve exatamente um ID de biblioteca — esse contêiner é um card de anúncio — depois leia os campos a partir do texto e links dentro dele.

from bs4 import BeautifulSoup

soup = BeautifulSoup(html, "html.parser")  # html do Passo 1

def single_card(node):
    # Maior ancestral cuja subárvore ainda contém exatamente um "Library ID:".
    best, n = node.parent, node.parent
    while n is not None and len(LIB.findall(n.get_text(" ", strip=True))) == 1:
        best, n = n, n.parent
    return best

def fields(card):
    txt = card.get_text("\n", strip=True)
    lib = re.search(r"Library ID:\s*(\d+)", txt)
    status = "Ativo" se re.search(r"\bActivo\b", txt) else (
        "Inativo" se "Inativo" em txt senão None)
    started = re.search(r"Iniciou em ([A-Z][a-z]+ \d{1,2}, \d{4})", txt)
    ran = re.search(r"([A-Z][a-z]+ \d{1,2}, \d{4}) - ([A-Z][a-z]+ \d{1,2}, \d{4})", txt)
    advertiser = None
    para a em card.find_all("a", href=True):
        se re.match(r"https://www\.facebook\.com/[^/?#]+/?$", a["href"]) e a.get_text(strip=True):

advertiser = a.get_text(strip=True)
break
return {
"library_id": lib.group(1) if lib else None,
"advertiser": advertiser,
"status": status,
"started_running": started.group(1) if started else None,
"active_range": list(ran.groups()) if ran else None,
}

seen, cards = set(), []
for node in soup.find_all(string=LIB):
card = single_card(node)
if id(card) not in seen:
seen.add(id(card))
cards.append(card)

records = [fields(c) for c in cards]
print("registros de anúncios extraídos:", len(records))
for r in records[:4]:
print(r)

Isso extrai 27 registros. Os primeiros imprimem como anunciantes reais e datas — `{'library_id': '1869276447125570', 'advertiser': 'Nike', 'status': 'Ativo', 'started_running': '17 de mar de 2026', 'active_range': None}`. Note as duas formas de data: um anúncio ativo imprime `Começou a rodar em <data>`, enquanto um anúncio inativo imprime um intervalo de execução `<início> - <fim>`, então o parser lê ambos e deixa o outro campo como `None`. O anunciante é extraído do primeiro link que aponta para uma URL de Página básica (`facebook.com/<página>/`), que é o lugar mais estável onde o nome da Página aparece no cartão.

> Obtenha sua chave de API no plano gratuito: [app.scrapeless.com](https://app.scrapeless.com/passport/login/?utm_source=website&utm_medium=blog&utm_campaign=scrapingbrowser&utm_term=scrape-facebook-ads)

---

## Etapa 3 — Carregar mais anúncios rolando a grade de resultados

A Biblioteca de Anúncios não pagina com números de página — ela adiciona mais cartões à medida que você rola. O padrão confiável é rolar a grade, esperar que os novos cartões sejam renderizados, reler o DOM e repetir até que a contagem de cartões pare de subir. Contar as ocorrências de `Library ID:` após cada rolagem informa quando a grade está esgotada para essa busca.

```python
session = client.browser.create(ICreateBrowser(proxy_country="US", session_ttl=240))

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(session.browser_ws_endpoint)
    ctx = browser.contexts[0] if browser.contexts else browser.new_context()
    page = ctx.pages[0] if ctx.pages else ctx.new_page()
    page.goto("https://www.facebook.com/", wait_until="domcontentloaded", timeout=60_000)
    page.wait_for_timeout(3_000)
    page.goto(URL, wait_until="domcontentloaded", timeout=60_000)
    page.wait_for_timeout(8_000)

    def card_count():
        return len(LIB.findall(page.content()))

    counts = [card_count()]
    for _ in range(6):  # a grade carrega mais cartões à medida que você rola
        page.mouse.wheel(0, 6_000)
        page.wait_for_timeout(2_500)
        counts.append(card_count())
    browser.close()

print("contagem de cartões após cada rolagem:", counts)

Isso imprime contagem de cartões após cada rolagem: [27, 37, 47, 66, 75, 85, 104] — a grade cresceu de 27 cartões na primeira renderização para 104 após seis rolagens. Quando duas contagens consecutivas correspondem, a grade parou de carregar para essa consulta e você pode parar de rolar. Mantenha o passo de rolagem modesto e o tempo de espera longo o suficiente para que novos cartões sejam renderizados, ou você contará antes que a grade tenha se atualizado.

Etapa 4 — Escrever a saída estruturada

A lista records da Etapa 2 já é uma lista de dicionários com chaves consistentes, portanto, escrevê-la em CSV ou JSON é apenas algumas linhas. Decida o esquema de antemão — as mesmas chaves em cada linha — para que um campo ausente se torne um None, nunca uma falha.

import csv
import json

# records é a lista de dicts construída na Etapa 2 (execute novamente a análise após a
# rolagem final na Etapa 3 para capturar cada cartão carregado).
fieldnames = ["library_id", "advertiser", "status", "started_running", "active_range"]
with open("facebook_ads.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.DictWriter(f, fieldnames=fieldnames)
    writer.writeheader()
    for row in records:
        writer.writerow({**row, "active_range": json.dumps(row["active_range"])})

with open("facebook_ads.json", "w", encoding="utf-8") as f:
    json.dump(records, f, ensure_ascii=False, indent=2)

print("gravou", len(records), "linhas em facebook_ads.csv e facebook_ads.json")

Esse é todo o loop: renderize a grade no navegador em nuvem, descubra cada cartão do ancla Library ID:, extraia o anunciante e as datas, role para carregar mais e armazene. Troque os parâmetros q e country na URL para apontá-los para qualquer anunciante, palavra-chave ou região que a Biblioteca de Anúncios atenda.

Manipulando dados de anúncios de forma responsável

A Biblioteca de Anúncios é uma superfície pública de transparência, e os anúncios nela são publicados por marcas para qualquer um ver — mas os registros ainda estão ligados a anunciantes identificáveis, então colete-os com cuidado:

• Permaneça na superfície pública. Tudo neste guia lê a mesma grade de resultados anônima e sem login que qualquer visitante vê. Não autentique para acessar visualizações restritas ou extrair qualquer coisa que a página pública não mostre.
• Colete dados de anúncios e anunciantes, não dados pessoais. Os campos úteis aqui são a Página do anunciante, o criativo e as datas de execução. Evite coletar nomes de comentaristas, reações ou qualquer informação pessoal vinculada a um anúncio.
• Minimize e mantenha o propósito. Extraia apenas os campos que sua análise necessita e não mais, e mantenha-os apenas enquanto o caso de uso exigir.
• Respeite os termos e limites de taxa da plataforma. Honre os Termos de Serviço da Meta e o Protocolo de Exclusão de Robôs, e mantenha o volume de solicitações educado; fixe a saída e limite a concorrência em vez de sobrecarregar a grade.

Para trabalhos comerciais ou sensíveis à conformidade, revise os termos aplicáveis da plataforma e consulte um advogado antes de construir um pipeline recorrente.

O Que Você Recebe de Volta

Após a análise, cada cartão de anúncio se reduz a um registro plano com um esquema consistente:

[
  {
    "library_id": "1869276447125570",
    "advertiser": "Nike",
    "status": "Ativo",
    "started_running": "17 Mar 2026",
    "active_range": null
  },
  {
    "library_id": "308819044896583",
    "advertiser": "Nike",
    "status": "Inativo",
    "started_running": null,
    "active_range": ["15 Ago 2023", "24 Jul 2025"]
  }
]
// O esquema reflete exatamente o que a análise da Etapa 2 emite. Os valores dos campos são amostras ilustrativas.

Algumas coisas a esperar na prática:

• Contagem de cartões muda entre execuções. A mesma consulta pode retornar um número ligeiramente diferente de cartões dependendo de quais anúncios estão ativos e quão longe a grade foi carregada; trate a contagem como uma instantânea, não como um total fixo.
• Duas formas de data, um esquema. Anúncios ativos têm uma única data de Iniciado em; anúncios inativos têm um intervalo de execução. O analisador preenche o que quer que esteja presente e deixa o outro como None.
• Ancore no texto, verifique novamente se houver desvio. O rótulo ID da Biblioteca: é muito mais durável do que as classes React criptografadas, mas a Meta ainda muda o layout do cartão periodicamente — verifique novamente os padrões de descoberta e campos quando a marcação mudar.
• Fique de olho na sua saída. proxy_country="US" mantém os anúncios retornados consistentes com um espectador dos EUA; troque o código do país para corresponder à região que você precisa, já que a Biblioteca de Anúncios varia os resultados por país.

Conclusão: escale seu pipeline de extração da Biblioteca de Anúncios

Ler a Biblioteca de Anúncios do Facebook se resume a quatro movimentos: renderizar a grade de resultados em um navegador na nuvem, descobrir cada anúncio a partir do ancla estável ID da Biblioteca:, extrair o anunciante e as datas de execução, e rolar para carregar mais até que a contagem se estabilize. A única parte de HTTP puro, mesmo com a semântica HTTP correta, não consegue — executar a grade do lado do cliente atrás do verificador anti-bot — se eleva limpidamente para o Scrapeless Scraping Browser, que renderiza a página e devolve o DOM que seu analisador já compreende.

A partir daqui, escale da maneira que todo scraper de produção escala: ancore seletores no gancho mais durável e verifique-os novamente quando o layout mudar, fixe a saída dos EUA para corresponder ao público que os anúncios estão mirando, trate campos ausentes como anuláveis e mantenha a concorrência educada por host. Para a mesma divisão de renderização em JavaScript, o guia de Cheerio e Puppeteer orienta na decisão estática vs. dinâmica no Node.js, e a superfície do SDK e CLI está documentada em docs.scrapeless.com. Compare as opções de tempo de execução na página de preços quando estiver pronto para executá-lo em volume.

Pronto para Construir Seu Pipeline de Dados Impulsionado por IA?

Junte-se à nossa comunidade para reivindicar um plano gratuito e conectar-se com desenvolvedores que constroem pipelines de inteligência de anúncios: Discord · Telegram.

Inscreva-se em app.scrapeless.com para obter tempo de execução gratuito do Scraping Browser e adapte os padrões acima às necessidades de pesquisa de sua Biblioteca de Anúncios em anunciantes, palavras-chave e regiões.

Perguntas Frequentes

Q: É legal fazer scraping da Biblioteca de Anúncios do Facebook?
A Biblioteca de Anúncios é um arquivo público de transparência, e os anúncios nela estão visivelmente disponíveis publicamente sem login, o que geralmente a coloca em uma posição mais firme do que dados restritos. As regras ainda variam por jurisdição e pelos Termos de Serviço da Meta, portanto, revise os termos da plataforma, colete dados de anunciantes e anúncios em vez de informações pessoais e consulte um advogado para uso comercial.

Q: Eu preciso fazer login para ler a Biblioteca de Anúncios?
Não. Anúncios públicos na Biblioteca de Anúncios aparecem para visitantes anônimos, e este guia é lido na mesma superfície sem login. Não se autentique para acessar visualizações que a página pública não mostra.

Q: Preciso de um proxy?
Sim. A Biblioteca de Anúncios varia seus resultados de acordo com o país do espectador e bloqueia a grade por meio de uma verificação de bot, então use proxies residenciais e defina o país com proxy_country para que a página retorne os anúncios que um visitante local veria. A sessão do Scraping Browser inclui essa saída.

Q: A página mostra um desafio ou uma grade vazia em vez de anúncios — como faço para obter uma renderização limpa?
Isso é a verificação anti-bot na solicitação. Renderize através do Scrapeless Scraping Browser com saída residencial dos EUA fixada e aqueça a sessão carregando facebook.com primeiro na mesma sessão antes de navegar para a URL da Biblioteca de Anúncios, para que a solicitação tenha uma superfície de navegador estabelecida e parecida com a humana quando a grade carregar.

Q: Meus seletores pararam de funcionar após uma mudança de layout — e agora?
Os nomes das classes React da Biblioteca de Anúncios são criptografados e giram, então nunca se fixe neles. Ancore a descoberta no texto Library ID: que cada cartão imprime e leia os campos a partir de padrões de texto e links de página diretos. Quando a Meta altera o layout do cartão, verifique aqueles padrões de texto em vez de perseguir cadeias de classe.

Q: Como faço para percorrer mais do que a primeira tela de anúncios?
A grade usa rolagem infinita, não números de página. Role a página, aguarde os novos cartões aparecerem, releia o DOM e repita até que a contagem de Library ID: pare de crescer — em uma execução, ela subiu de 27 cartões para 104 em seis rolagens.

Q: Quantas pesquisas posso executar em paralelo?
Mantenha a concorrência moderada — cerca de três sessões por host é um teto razoável — para que você permaneça dentro de taxas de solicitação educadas. As sessões de navegador em nuvem são mais pesadas do que solicitações HTTP, então limite-as mais do que limitaria uma busca estática.

Q: Posso fazer isso sem um agente de IA?
Sim. O fluxo de Python e SDK acima funciona de ponta a ponta por conta própria. Um agente é uma camada de conveniência em cima; o loop renderizar → descobrir → extrair → rolar é código simples que você pode agendar diretamente.