# AntiAdblock Guard — Guia público de instalação e operação URL oficial: https://antiadblockguard.com Documentação: https://antiadblockguard.com/guides Este guia não contém chaves nem dados de conta. Use os valores gerados no painel do proprietário para integrar um site. ## Diagnóstico, CSP e atualização do detector Entrega completa no seu domínio, diagnóstico e status alternativo. Fonte: https://antiadblockguard.com/guides/diagnostico-e-csp ### Atualize a entrega Máxima A partir do Pro, baixe novamente o arquivo PHP, o plugin WordPress ou route.js na tela Entrega Máxima. Substitua a instalação preservando o nome e confira as regras atualizadas no painel. Verifique novamente para confirmar o protocolo 2. Ele encaminha carregador, script, coleta, diagnóstico e controle de conectividade pelo domínio do cliente. Instalações antigas mantêm as funções anteriores até a atualização. Nenhuma entrega oferece garantia contra todas as listas. ### Instalação com CSP Em Sua tag de instalação, abra Instalação com CSP e use essa tag no lugar da anterior. Ela não usa onerror inline. Quando sua política usa nonce, gere um valor imprevisível a cada resposta no servidor, use o mesmo valor no cabeçalho CSP e no atributo nonce da tag. O carregador propaga esse nonce aos scripts criados e ao estilo do aviso. A política precisa permitir os scripts AdSense e IMA, além de connect-src para coleta, diagnóstico e controle. style-src deve autorizar o estilo do aviso pelo nonce. img-src precisa permitir sua logo. Não adicione unsafe-inline para contornar uma configuração incorreta. As rotas de fallback também precisam estar autorizadas. Um nonce de script com strict-dynamic delega confiança a scripts criados por ele, inclusive as sondagens; avalie isso com o responsável pela segurança do seu site. ### Aviso renderizado pelo servidor Em Entrega Máxima, baixe guard-status.html e inclua o fragmento no template do seu servidor, fora do conteúdo protegido. O visitante verá uma mensagem neutra enquanto a checagem não concluir. O detector oculta o fragmento quando há resultado conclusivo. Sem JavaScript ou com toda a entrega bloqueada, a mensagem continua visível. Ela não confirma adblock e não bloqueia a navegação. Estilize o fragmento no CSS do seu site. ### Leia o diagnóstico A aba Diagnóstico mostra carregador iniciado, detector executado, checagem concluída, abertura do aviso, falhas na coleta e uso de fallback. As confirmações usam um ID aleatório por carregamento e não armazenam IP, URL ou user-agent nessa tabela. Os dados são enviados pelo navegador e não são uma prova inviolável. Se o carregador e seu diagnóstico forem bloqueados juntos, não há confirmação. O comando agendado compara taxas em duas janelas de 24 horas, exige ao menos 100 inícios em cada janela e emite no máximo um alerta por site a cada 24 horas. Falta de tráfego, isoladamente, não gera esse alerta. ### Versões e rollback Em Administração → Detector, selecione uma versão estável e opcionalmente uma versão em teste para 1 a 100 por cento dos sites. Os grupos são estáveis por site e não usam cookies. Apenas versões revisadas e incluídas na aplicação podem ser selecionadas; não existe campo para executar código remoto arbitrário. O histórico permite restaurar a distribuição anterior. O rollback vale para novos carregamentos; páginas já abertas precisam ser recarregadas. A versão 1.0.2 tem diagnóstico parcial e serve como rollback. ### Agendamento na hospedagem O operador precisa executar php artisan schedule:run a cada minuto pelo cron da hospedagem. A tarefa adsinal:diagnose-delivery roda de hora em hora, gera alertas e remove diagnósticos com mais de 30 dias. A matriz de navegadores é uma rotina separada de desenvolvimento/CI e não deve executar navegadores na hospedagem compartilhada. ## Cadastre e verifique seu primeiro site Do domínio à propriedade verificada. Fonte: https://antiadblockguard.com/guides/primeiro-site ### Cadastre o domínio Em Sites, clique em Adicionar site e informe o nome e o domínio. Caminhos e portas não fazem parte do domínio. Cada domínio cadastrado ocupa uma vaga do plano. ### Verifique a propriedade No card Propriedade do domínio em Configuração, copie o CNAME para seu DNS e clique em Verificar domínio. O mesmo registro comprova a propriedade e prepara o subdomínio. CNAME verificado e HTTPS confirmado são estados diferentes. O TXT fica disponível como alternativa para liberar somente a entrega central. ### Teste local No ambiente de desenvolvimento, localhost e 127.0.0.1 permitem ativação manual. Esse estado serve para testes e não confirma DNS público. ## Instale a tag e confira o primeiro contato Onde colocar a tag e como saber se está funcionando. Fonte: https://antiadblockguard.com/guides/instalar-script ### Instalação Verifique o domínio em Configuração. Em seguida, copie a tag do card Sua tag de instalação e cole uma vez no head de todas as páginas que deseja monitorar. O carregamento é assíncrono e a tag inclui data-cfasync="false" para não ser adiada pelo Rocket Loader. No WordPress, use um recurso confiável para inserir scripts no cabeçalho; Pro, Max e Business oferecem um plugin de entrega própria, disponível em Entrega Máxima. ### Verifique a tag Depois de publicar, use Verificar tag no head. O sistema lê por HTTPS o HTML da página inicial e procura a URL exata do script deste site dentro do head. Uma tag comentada, de outro site ou fora do head não é aprovada. Tags inseridas somente depois de executar JavaScript podem não aparecer nessa leitura. Encontrar a tag não comprova execução: confira também o último evento recebido. ### Confira os eventos Abra uma página do site e volte à visão geral. Último contato registra o evento mais recente. Sem contato nos últimos 10 minutos significa ausência de tráfego recente ou falha na instalação; não prova que a tag foi removida. ### Problemas comuns Confira o domínio cadastrado, verificação, coleta habilitada, política CSP do site e a aba Network do navegador. Restrições de rede e bloqueadores também podem impedir a tag padrão. ## Entenda a entrega first-party CNAME, roteamento e HTTPS são partes da mesma instalação. Fonte: https://antiadblockguard.com/guides/first-party ### Subdomínio próprio O script pode ser carregado por um subdomínio seu, apontado por CNAME para a infraestrutura AntiAdblock Guard. Isso exige que o operador configure o destino de entrega, o roteamento dos hostnames e certificados TLS válidos. ### Estados reais A configuração mostra separadamente propriedade, CNAME e entrega HTTPS. O estado ativo exige resposta do script com identificação correta no subdomínio. Um registro DNS sozinho não significa que a entrega esteja operacional. ### Rotação e limitações Gerar outro hostname invalida a verificação de entrega. Configure o novo CNAME, verifique e substitua a tag. A partir do Pro, a entrega Máxima adiciona uma rota alternativa no servidor do cliente. Ela tem verificação própria. A emissão automática de certificados dos subdomínios ainda depende da infraestrutura de publicação. ## Recuperação e Detection API Escolha entre mostrar o aviso ou decidir pela sua integração. Fonte: https://antiadblockguard.com/guides/modos ### Recuperação Quando as checagens visuais ou de rede indicam possível bloqueio, o script mostra o aviso configurado. O botão verifica novamente. Você pode permitir fechar o aviso ou exigir uma nova checagem sem bloqueio. Visitas sem indício de bloqueio não abrem o aviso. ### Detection API Disponível no Max e Business. Nesse modo não aparece aviso. Ouça window.addEventListener("adsinal:detection", callback). event.detail contém detected e site. O evento é emitido também quando o detector não identifica bloqueio e a visita foi aceita. No Free e Pro, o evento público não é emitido. ### Cobertura atual O detector combina elementos isca com carregamento de scripts e verificação dos objetos públicos criados por eles. O núcleo foi adaptado do CHP Adblock Detector (MIT), com checagem adicional do SDK IMA para listas que substituem o AdSense por um script inofensivo. Os scripts do AdSense e IMA são solicitados ao Google com crossorigin=anonymous e referrerPolicy=no-referrer, sem credenciais e sem solicitar anúncios; o código dos SDKs é executado e o IP do visitante é visível ao provedor. Uma indicação de bloqueio deve se repetir com controle de conectividade funcionando. Timeout, modo offline e CSP não são tratados isoladamente como bloqueio. Testado em perfis isolados com uBlock Origin Lite e Brave com filtros inicializados. Não identifica qual extensão está instalada nem garante cobertura universal. ### Falhas de coleta A detecção local não depende do sucesso do envio da visita. Falhas de rede ou HTTP 5xx têm uma nova tentativa com o mesmo identificador de página, sem duplicar eventos aceitos. Recusas explícitas de acesso ou quota são respeitadas. O aviso pode ser exibido durante uma falha temporária de telemetria, mas a métrica só aparece no painel quando o servidor aceita o evento. ## Personalize o aviso do seu site Mensagem, cores, logo e fundo em uma tela própria. Fonte: https://antiadblockguard.com/guides/personalizar ### Conteúdo A partir do Pro, abra Personalizar no site. Edite título, mensagem e botão. O texto é tratado como texto, sem interpretação de HTML. Salve e carregue uma nova página do site para receber a configuração atualizada. ### Identidade Escolha cores de destaque, fundo e texto com contraste legível. A logo aceita endereço HTTPS de imagem. Evite imagens com dados pessoais e hospede o arquivo em um domínio confiável. A prévia reflete as mudanças antes de salvar. ### Fundo e fechamento A opacidade controla quanto da página fica visível atrás do aviso. A opção de fechar vale para qualquer bloqueio detectado; o motor atual não distingue bloqueio de rede. ## Leia métricas e estatísticas O que cada número mede e por que pode haver diferenças. Fonte: https://antiadblockguard.com/guides/metricas ### Visitas e detecções Uma visita é um carregamento de página registrado pelo script. Não é um visitante único. Cada tipo de evento é contado uma vez por página. A taxa de detecção divide detecções por visitas registradas. ### Rechecagem Mensagem exibida conta a abertura do aviso. Uma nova checagem sem bloqueio não comprova receita recuperada ou anúncio exibido. Os gráficos usam eventos reais agregados por dia no horário de Brasília. ### O que não é contado Se o script não carregar ou a rede impedir o envio, a visita não chega ao AntiAdblock Guard. A quota considera apenas detecções, não requisições de página. ## Planos, limites e cobrança Capacidade de sites, quota mensal e assinatura em reais. Fonte: https://antiadblockguard.com/guides/planos ### Uso Free inclui 1 site e 10 mil detecções mensais. Pro inclui 2 sites e 200 mil; Max, 3 sites e 3 milhões; Business, 5 sites e 20 milhões. Aviso personalizado está disponível a partir do Pro; Detection API, a partir do Max; entrega Máxima, a partir do Pro. A página Plano e uso mostra o consumo real da conta. ### Ciclo No Free, o ciclo é o mês de calendário no horário de Brasília. Nos planos pagos, ele acompanha a data de início da assinatura mensal. Ao atingir a quota, novas detecções são recusadas até a renovação ou ampliação do plano. ### Stripe O checkout e o portal seguro da Stripe cuidam do cartão, faturas, mudanças e cancelamento. O plano só muda após confirmação assinada. Cancelar ao final do período preserva o acesso até a data informada. Os pagamentos dependem da configuração da conta Stripe do AntiAdblock Guard. ## Proteja a tag e renove a chave de coleta Origem, tokens e o efeito da renovação. Fonte: https://antiadblockguard.com/guides/seguranca ### Proteções A coleta valida domínio de origem, token temporário e versão da chave. O token expira após uma hora. Essas medidas limitam usos indevidos, mas um código público de navegador não oferece uma identidade inviolável. ### Renove a chave Em Configuração, confirme a renovação da chave. Os tokens já emitidos deixam de valer imediatamente. A tag não muda; novas páginas recebem a versão atual. Páginas abertas antes da renovação podem precisar ser recarregadas. ### Privacidade A aplicação armazena tipo do evento, caminho da página, horário e referência aleatória do carregamento. Não usa cookies do visitante para a coleta. Evite colocar informações pessoais em URLs. Logs do servidor podem conter IP e precisam de política de retenção na hospedagem. ## Instale a entrega Máxima no seu domínio Arquivo PHP ou plugin WordPress, verificação e fallback pelo domínio principal. Fonte: https://antiadblockguard.com/guides/maximum-detection ### Padrão e Máximo Padrão utiliza o subdomínio first-party quando CNAME e HTTPS estão verificados e mantém fallback central. Máximo, disponível a partir do Pro, acrescenta uma rota no domínio principal. Se o subdomínio falhar, a tag tenta essa rota antes do serviço central. Trata-se de disponibilidade de entrega: o motor continua baseado em elemento isca e não garante identificar todo bloqueador. ### Pré-requisitos Tenha acesso ao servidor do domínio cadastrado. Para o arquivo avulso, use PHP 8.0 ou superior, extensão cURL e saída HTTPS permitida. O domínio público deve usar HTTPS válido. Sites estáticos e hospedagens sem execução PHP exigem uma implementação de rota específica; o arquivo fornecido não é executável nesses ambientes. No desenvolvimento local, o AntiAdblock Guard usa localhost/127.0.0.1 com uma porta de teste separada. ### Instalar o arquivo PHP 1. Cadastre e verifique a propriedade do site. 2. Abra Configuração → Set up Maximum Detection → PHP. 3. Clique em Baixar arquivo PHP. Envie esse arquivo para a raiz pública do site, preservando o nome gerado. Não envie como texto, não renomeie e não exponha seu código-fonte: ele contém a chave privada desta instalação. 4. Confira a URL exibida no painel e clique em Check and install. A prova assinada confirma que o arquivo correto responde no domínio esperado. Em Apache/LiteSpeed compatível, o arquivo tenta adicionar somente três regras AntiAdblock Guard ao .htaccess, com backup e teste da página inicial. Se não puder instalar as regras, informa o motivo e mantém a rota direta; o painel mostra regras manuais. Uma falha no teste tenta reverter a alteração. 5. Ative Máximo. Copie e substitua a tag atualizada no head das páginas. 6. Abra uma página e confirme o último contato da rota e os eventos. A prova do arquivo não substitui esse teste de comunicação. ### Instalar com Next.js No App Router com runtime Node.js, baixe route.js e coloque em app/NOME-DO-ARQUIVO/route.js ou src/app/NOME-DO-ARQUIVO/route.js, usando o nome exato exibido no painel (incluindo .php). Acrescente os três rewrites fornecidos no painel a next.config.js ou next.config.mjs, preservando regras existentes. Mantenha o arquivo fora de repositórios públicos porque contém a chave privada do site. Publique, verifique a rota direta e o rewrite no painel, ative Máximo e substitua a tag no head. Exportação estática de Next.js não executa Route Handlers. ### Outras plataformas Node, Nuxt, Astro e sites estáticos precisam de uma rota no próprio domínio que execute código no servidor ou na borda. Sites apenas estáticos precisam de uma função edge ou backend. Ainda não há pacote automático para essas plataformas; abra um ticket em Suporte no painel. Permaneça no Padrão até a integração estar pronta e verificada. ### Instalar com WordPress O plugin gerado exige WordPress instalado na raiz do domínio cadastrado e permalinks/rewrite funcionando. Em Configuração → Máximo, baixe o ZIP WordPress. No wp-admin, vá a Plugins → Adicionar plugin → Enviar plugin, envie o ZIP e ative. O plugin registra a rota e insere a tag no head das páginas públicas; usuários com permissão de editar posts são ignorados. Verifique a rota no AntiAdblock Guard e ative Máximo. Não instale também uma tag manual para evitar duplicidade. O plugin é específico do site e contém sua chave privada. Ao mudar domínio oficial do AntiAdblock Guard ou hostname de entrega, gere e reinstale o pacote atualizado. ### Como o fallback funciona A tag gerada usa primeiro o subdomínio verificado, depois a rota verificada do domínio principal, e por último o AntiAdblock Guard. Se não houver subdomínio ativo, a rota Máxima pode ser o primeiro caminho. O arquivo só encaminha as ações fixas de script e coleta ao AntiAdblock Guard; não aceita destinos externos informados pelo visitante. O script recebido pela rota também envia eventos por essa rota. Há limites curtos de conexão e tempo total; falhas não criam um bloqueio de conteúdo. O erro de carregamento pode acionar o próximo caminho, conforme a tag. Políticas CSP devem permitir os endereços e o fallback da instalação. ### Verificar, trocar e revogar Arquivo verificado significa que ele respondeu à prova de instalação com a chave esperada. Último contato da rota registra quando ela conseguiu buscar o script no AntiAdblock Guard. Ativar Máximo exige plano compatível e verificação. Revogar integração invalida imediatamente a chave do arquivo/plugin sem apagar o site ou o histórico; remova a instalação do cliente e baixe outra para reconectar. A renovação da chave de coleta do navegador é independente da revogação da integração de servidor. Em downgrade, o caminho Máximo é bloqueado e o fallback central continua disponível nas tags geradas. ### Teste com uma IA Forneça à sua IA o guia público ou o download em texto, a plataforma do seu site e a URL da rota indicada no painel. Solicite a instalação no head e a conferência de CSP, código HTTP, tipos MIME, timeout, certificado e eventos. Não envie senhas ou chaves privadas em prompts públicos. Teste o fallback bloqueando o subdomínio em um navegador de teste, sem alterar o DNS de produção. O domínio oficial e as chaves da cobrança são do operador, não devem ser inventados pela IA.