Manual do Ad-Clean Agent

Versão 1.0 · Chrome / Edge / Brave (Manifest V3, Chrome 111+)

Sumário

1. Instalação
2. A interface
3. Como o bloqueio funciona
4. O módulo do YouTube
5. Agente heurístico
6. Listas de filtro
7. Regras próprias e o seletor de elemento
8. Licença Pro
9. Privacidade
10. Quando algum site quebra
11. Reportar um anúncio que passou
12. Perguntas técnicas

1. Instalação

Pela Chrome Web Store

Em breve. Assinantes Pro recebem o pacote e o passo a passo por e-mail junto com a chave.

Carregando sem compactação (desenvolvedor / assinante Pro)

1. Descompacte o pacote em uma pasta que você não vá apagar.
2. Abra chrome://extensions.
3. Ligue Modo do desenvolvedor (canto superior direito).
4. Clique em Carregar sem compactação e escolha a pasta.
5. Fixe o ícone na barra pelo menu de extensões (o alfinete).

O Chrome mostra um aviso sobre extensões em modo desenvolvedor a cada início. É comportamento do navegador para qualquer extensão fora da loja.

2. A interface

Popup (clique no ícone)

Página de opções (Regras e listas)

Licença, whitelist completa, regras próprias em sintaxe Adblock, assinaturas de listas, estatísticas e exportar/importar configuração.

Badge do ícone

O número no ícone é a contagem daquela aba, zerada a cada navegação.

3. Como o bloqueio funciona

Quatro camadas, nessa ordem:

1. Rede (declarativeNetRequest) — o navegador nem chega a pedir o recurso. Dois rulesets embutidos: ads (redes de anúncio, incluindo chinesas e de marketplace) e trackers (analytics, pixels, afiliados), este último desligável.

2. CSS antecipado — no primeiro instante do carregamento, antes de a página pintar, um bloco de regras display:none é injetado. Nada de "flash" de anúncio.

3. Remoção no DOM — o que a lista não cobre, a varredura em JavaScript remove, e o container que ficou vazio é colapsado (com trava para nunca apagar body, main, article ou qualquer bloco que ainda tenha conteúdo visível).

4. MutationObserver — anúncio injetado depois do carregamento passa pelas mesmas camadas. Há ainda uma varredura de segurança a cada 4 segundos para páginas que reescrevem estilo fora de mutações observáveis.

Overlays e pop-ups têm tratamento próprio: elementos fixos com z-index alto que cobrem a tela e se identificam como anúncio são removidos, e a trava de rolagem que eles deixam no body é desfeita.

4. O módulo do YouTube

O YouTube não entrega o anúncio de vídeo por um domínio separado — ele vem descrito dentro do JSON do player. Bloquear por rede não resolve. O módulo age em duas frentes:

Antes do player ler (contexto da página)

Interceptamos JSON.parse, window.fetch nas rotas /youtubei/v1/player, /next, /browse, /search, e as variáveis ytInitialPlayerResponse e ytInitialData. De cada resposta são removidos adPlacements, playerAds, adSlots e os renderers de anúncio de feed. O pré-roll não chega a existir.

O que escapa e chega à tela

Seletores mudam. O YouTube altera nomes de classe com frequência. A camada de JSON é estável; a de DOM é a que envelhece. Se algum anúncio começar a aparecer, reporte — a correção sai rápido.

5. Agente heurístico (Pro)

Lista de filtro só pega o que alguém já catalogou. Sites regionais, lojas e portais asiáticos ficam meses de fora. O agente decide sozinho, por pontuação:

Bloqueia a partir de 4 pontos — nenhum sinal isolado chega lá, sempre exige combinação. Embeds legítimos (YouTube, Vimeo, Maps, Spotify, reCAPTCHA, Stripe, PayPal, Disqus…) são imunes por lista fixa.

6. Listas de filtro

Em Regras e listas → Assinaturas, cole a URL de qualquer lista no formato Adblock. A extensão baixa, converte as regras de rede para declarativeNetRequest e aplica os seletores cosméticos na página. Atualização automática a cada 12 horas.

Sugestões já embutidas na página de opções:

• EasyList — anúncios em geral
• EasyPrivacy — trackers
• EasyList Portuguese — sites em português
• Fanboy's Annoyance — pop-ups, banners de cookie

Para listas chinesas, EasyList China e a lista do AdGuard para chinês funcionam do mesmo jeito.

Limites do Chrome (não são nossos): 30.000 regras por ruleset estático e 5.000 regras dinâmicas no total — usamos teto de 4.000 para assinaturas. Regras que o formato não expressa (regex, $csp, $removeparam, scriptlets, cosméticos estendidos) são descartadas na conversão; na EasyList real isso é cerca de 4% das linhas.

O plano gratuito permite 1 assinatura; o Pro, ilimitadas.

7. Regras próprias e o seletor de elemento

Pelo mouse

Popup → Bloquear um elemento… → passe o mouse (a área fica destacada em vermelho) → clique. Esc cancela. A regra é salva para aquele domínio e reaplicada nas próximas visitas.

Escrevendo

Em Regras e listas → Regras personalizadas, uma por linha, sintaxe Adblock:

exemplo.com##.banner-lateral     → só nesse site (e subdomínios)
##.pop-up-newsletter             → em todos os sites

Seletor inválido é recusado na hora de salvar, com a mensagem do erro. Gratuito: 10 regras. Pro: ilimitadas.

8. Licença Pro

Ativar

Regras e listas → Licença → cole a chave (XXXX-XXXX-XXXX-XXXX) → Ativar.

Trocar de máquina

Cada licença vale para 3 dispositivos. Para liberar uma vaga, clique em Desativar neste dispositivo antes de sair da máquina antiga. Perdeu o acesso ao aparelho? Peça a liberação pelo suporte.

Sem internet

A licença é revalidada uma vez por dia. Offline, o Pro continua funcionando por 14 dias antes de voltar ao plano gratuito.

Vencimento

Nada é desinstalado e nenhuma regra sua é apagada — a extensão só volta ao comportamento do plano gratuito.

9. Privacidade

A extensão nunca envia URL, título de página, histórico, formulários ou conteúdo de página. Nada.

O que a estatística anônima envia (e dá para desligar em Regras e listas):

Detalhes na política de privacidade.

10. Quando algum site quebra

Na ordem, do mais simples ao mais específico:

1. Whitelist o site no popup — resolve na hora, pausa tudo naquele domínio.
2. Desligue "Bloquear trackers e pixels" — a causa mais comum. Sites que carregam conteúdo pelo Google Tag Manager, ou lojas cujo botão de compra passa por um redirecionador de afiliado, dependem desses domínios.
3. Desligue "Remover elementos na página" — se o layout ficou estranho mas o conteúdo está lá, o problema é cosmético.
4. Desligue o agente heurístico — se sumiu algum bloco que era conteúdo real.
5. Reporte. Com o site e o que sumiu, viramos isso em exceção para todo mundo.

Player de vídeo que não inicia em site de notícia costuma ser o bloqueio do imasdk.googleapis.com. Whitelist o site ou avise no reporte.

11. Reportar um anúncio que passou

Pelo popup, o botão Reportar anúncio não bloqueado já abre o formulário preenchido com o site e a versão. Ou direto:

• Anúncio não bloqueado
• Sugestão de melhoria
• Site quebrou

O que faz um bom reporte: a URL exata, uma captura de tela com o anúncio destacado e, se souber, o seletor do elemento.

12. Perguntas técnicas

Por que o contador de bloqueios de rede fica em zero? A API que reporta bloqueios (onRuleMatchedDebug) só existe em extensão carregada sem compactação. Instalada pela loja, o Chrome não expõe esse dado — o contador passa a mostrar apenas o que é removido na página. É limitação do navegador.

Por que preciso recarregar a página ao mudar uma chave? As camadas de rede e o CSS antecipado agem no início do carregamento. Sem recarregar, a mudança só vale para o próximo request. O popup recarrega sozinho.

Ele funciona dentro de iframes? Sim, os content scripts rodam em todos os frames.

Consome muita memória? As listas grandes ficam no motor de CSS do navegador (barato); o JavaScript só varre um conjunto pequeno de seletores. A varredura de overlay olha apenas filhos diretos do body e diálogos, em vez de percorrer a página inteira.

Firefox? Ainda não. O modelo de extensão é outro; um port é plano futuro.