> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/pt-br/configuration/section-banners.md). # Banners de seção Exiba um banner promocional ou de patrocinador sob qualquer seção da página inicial adicionando um arquivo de dados ao build — sem mudança no código, sem commit, funciona em qualquer implantação. Toda seção da página inicial termina com um espaço fixo para banner — um cartão no estilo informativo com um título, uma nota e um botão de chamada para ação (`frontend/components/widgets/InfoBanner.vue`). O que aparece em um espaço, se aparecer algo, é decidido puramente pelos dados: um arquivo por seção em `frontend/data/banners/`. O diretório é **ignorado pelo git**. Um clone novo não mostra banners em lugar nenhum; colocar um arquivo em uma implantação *é* é a decisão de exibir aquele banner ali. Isso faz do recurso uma configuração de implantação, e não código do produto: o site oficial e qualquer fork usam exatamente o mesmo mecanismo, e o texto da campanha nunca toca nos pacotes de idioma nem no histórico do git. {% hint style="info" %} Ao contrário das ferramentas listadas em [Recursos vinculados ao IPCheck.ing](/developer/pt-br/configuration/features-tied-to-ipcheck-ing.md), os banners têm **nenhum** `originalSite` etapa de aprovação. O local da implantação é a única etapa de aprovação — uma instância auto-hospedada pode executar seus próprios banners apenas com um arquivo de dados. {% endhint %} Dois usos típicos: * **Autopromoção** — aponte uma seção para uma ferramenta integrada com um `para` destino interno. A seção de Vazamento de DNS do site oficial faz isso para destacar o Teste Aprofundado de Vazamento de DNS. * **Patrocinadores** — aponte para uma página de destino externa com `url`, e deixe o tratamento de UTM integrado atribuir o tráfego. ## Os seis espaços O componente de espaço está permanentemente ligado na parte inferior de cada seção; a `seção` prop corresponde ao nome do arquivo de dados. A maioria das seções também fornece ao espaço um sinal de "estabilizado" — seu próprio *testes concluíram uma passagem completa* sinal — pelo qual um banner espera por padrão (veja `requireSettled` abaixo). | `seção` | Seção da página inicial | Estabilizada quando | | --------------- | ------------------------- | ------------------------------------------------------------ | | `ipinfo` | Cartões de IP | Todo cartão de IP visível está estabilizado | | `conectividade` | Conectividade | Uma passagem completa de verificação foi estabilizada | | `webrtc` | Teste WebRTC | O teste STUN foi resolvido | | `dnsleak` | Teste de Vazamento de DNS | O teste da página inicial foi resolvido (sucesso ou timeout) | | `speedtest` | Teste de Velocidade | Uma execução do teste de velocidade foi concluída | | `advanced` | Ferramentas Avançadas | Imediatamente — a grade de cartões não executa testes | ## O arquivo de dados `frontend/data/banners/
.js` — o nome do arquivo é o espaço. O arquivo faz exportação default de `nulo` (espaço explicitamente desativado) ou **um** objeto simples, sem imports, para que o executor de testes puro do Node possa carregá-lo. O contrato canônico está no comentário de cabeçalho de `frontend/utils/banners.js`; mantenha isso como referência caso esta página e o código algum dia divirjam. {% code title="frontend/data/banners/ipinfo.js" %} ```js export default { id: 'vps', // único em todos os arquivos de banner icon: 'Server', // nome do ícone lucide (string) track: 'IPInfoVPS', // id da campanha — o rótulo de analytics copy: { en: { title: 'VPS Rápido', note: 'Proposta em uma linha.', cta: 'Saiba mais' }, zh: { title: '高速 VPS', note: '一句话说明。', cta: '立即获取' }, }, // Destino do clique — exatamente UM de `url` (externo) ou `to` (interno): url: 'https://sponsor.example.com/deal', utm: { source: 'ipcheck.ing', medium: 'referral', campaign: 'ipinfo-vps' }, }; ``` {% endcode %} | Campo | Obrigatório | Significado | | ---------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | sim | Único em todos os arquivos de banner na implantação | | `icon` | sim | Um ícone Lucide **name** como string. O componente o mapeia para um ícone importado; o dicionário é `Globe`, `Megaphone`, `Server`, `Shield`, `Sparkles`, `Zap`, e um nome desconhecido recai para `Megaphone`. Os nomes permanecem como strings, então o arquivo de dados não precisa de imports | | `track` | sim | ID da campanha — vira o rótulo no evento de clique (veja Analytics abaixo) | | `copy` | sim | Mapa de texto embutido indexado pelo código de localidade da UI: `{ en: { title, note, cta }, ?: { … } }`. O inglês é obrigatório e completo; qualquer outra localidade é opcional e cai diretamente no inglês — este mapa é uma simples busca, não a cadeia de fallback de localidade. O texto é dado por campanha **por design** — nunca chaves de pacotes de idioma | | `url` | um dos dois | Destino externo: abre em uma nova aba com parâmetros UTM adicionados | | `utm` | não (`url` somente) | Atribuição UTM, chaves **sem** o `utm_` prefixo (`{ source, medium, campaign }`). A função auxiliar adiciona o prefixo e anexa `utm_content=` — a localidade do visitante — para que as campanhas vejam qual interface de idioma converteu. Os parâmetros de consulta existentes em `url` são preservados | | `para` | um dos dois | Destino interno: um push do vue-router, por exemplo `'/?tool=enhanceddnsleaktest'` para abrir uma gaveta de ferramentas. Sem tratamento de UTM | | `requireSettled` | não (padrão `true`) | Aguarde o sinal de estabilização da seção antes de aparecer. Defina `falso` para mostrar imediatamente — por exemplo em `advanced`, ou um banner que não deve depender dos resultados dos testes | | `transição` | não (padrão `true`) | Aparição/desaparição com fade e deslizamento. Defina `falso` para uma troca instantânea | | `varredura` | não (padrão `falso`) | Uma varredura de luz na borda que é reproduzida quando o banner entra na área visível (e se repete ao reentrar). Respeita `prefers-reduced-motion` | Exatamente um de `url` / `para` deve estar presente — ambos ou nenhum falha na validação. ## Implantando um banner O espaço descobre seus dados com um glob em tempo de build (`import.meta.glob` sobre `frontend/data/banners/*.js`), então os arquivos precisam estar no lugar **when `pnpm build` é executado** — eles são compilados no bundle, não lidos em tempo de execução. Portanto, a receita de implantação é: 1. Coloque os arquivos de dados em `frontend/data/banners/` na máquina de build (uma etapa de CI, uma fase de build do Docker, ou manualmente). 2. Execute `pnpm test` — `tests/banners.test.js` valida quaisquer arquivos presentes: cada arquivo é puro e carregável pelo Node, os campos obrigatórios são strings não vazias, exatamente um de `url` / `para` está definido (`utm` somente com `url`), o texto em inglês está completo, as flags opcionais são booleanas, e os ids são únicos. Sem arquivos, o bloco é aprovado vacuamente. 3. Compile e implante como de costume. Remover um banner é o mesmo movimento ao contrário: exclua o arquivo (ou faça com que ele `export default null`) e recompilhe. Nada muda no git de qualquer forma. ## Analytics Um clique dispara um evento através do wrapper de analytics regular do app: categoria `Seção`, nome do evento `BannerClick_
`, rótulo = o `track` valor do banner. A seção vai no nome do evento em vez de em um parâmetro porque os relatórios do GA4 listam nomes de eventos por padrão. ## Próximo * [Frontend](/developer/pt-br/architecture/frontend.md) — onde o espaço fica na arquitetura do componente. * [Recursos vinculados ao IPCheck.ing](/developer/pt-br/configuration/features-tied-to-ipcheck-ing.md) — os recursos que *são* apenas do site oficial; banners não são um deles. * [Testes](/developer/pt-br/development/testing.md) — o executor de testes que valida os arquivos de dados. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ipcheck.ing/developer/pt-br/configuration/section-banners.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.