Guia de instalação do Next.js

Adicione o Velo ao Next.js

Instale o banner de cookies do Velo e o Google Consent Mode v2 no Next.js com uma linha no seu layout raiz. Com acesso ao código do site, a maioria das instalações leva poucos minutos. Se você usa Google Tag Manager, esta página também explica esse caminho.

Instruções e fontes das imagens revisadas em 7 de novembro de 2026.

Funciona com as plataformas em que você cria

WordPressShopifyWebflowWixHubSpotPrestaShopDrupalBigCommerceShopwareNext.jsAstroSquare

O que você precisa no Next.js

Antes de começar

  • Onde. app/layout.tsx → head
  • Plano. App Router ou Pages Router
  • Entra no ar. Depois do próximo deploy
  • Tempo típico. Cerca de cinco minutos

Depois que estiver no ar

  • Seu banner segue os padrões que você define para a região de cada visitante.
  • As tags esperam até o visitante escolher.
  • Cada escolha fica registrada, e o Consent Mode v2 a repassa às suas tags do Google.
CMConsent Mode v2GPCGlobal Privacy ControlUEGDPREUALeis estaduais dos EUA

Duas formas de instalar o Velo no Next.js

Escolha o caminho que combina com a forma como o seu site já carrega as tags. Os dois terminam com o mesmo banner e os mesmos sinais.


Cole uma linha no seu layout raiz

Adicione o trecho de código do seu site ao head global do site, depois publique e teste no site no ar. Se as suas tags de medição já rodam pelo Google Tag Manager, use o caminho mais abaixo.

Usa o Tag Manager? Esqueça o código

Se o Google Tag Manager já está no seu site, esta é a forma mais fácil de adicionar o Velo. Você não mexe em código, são quatro passos curtos e todas as suas tags ficam em um só lugar.

Cerca de cinco minutosTempo típico de instalação no Next.js
Depois do próximo deployQuando o banner entra no ar
1,500Sessões mensais no plano Free, para um site
Carregue o trecho de código uma única vez, a partir do layout raiz. Uma tag em um useEffect roda quando suas outras tags já podem disparar, e next/script sem estratégia espera a hidratação. Teste uma página que você abre por um Link, além de um recarregamento completo. O banner deve continuar no lugar, sem uma segunda cópia.
!
Um ponto de atençãoInstalação no Next.js
Veja todas as plataformas compatíveis

Tudo o que uma configuração de consentimento precisa

O mesmo banner, os mesmos registros e as mesmas análises em todos os planos. O Pro adiciona sites ilimitados, análises ilimitadas e o seu próprio logotipo.


Seu banner pergunta no idioma do visitante e segue os padrões que você define para a região dele.

Cada escolha fica registrada, e o Consent Mode v2 a repassa às suas tags do Google.


Google Consent Mode v2Modo avançado em todos os planos, com um template para o Google Tag Manager.
Regras pelo país do visitanteOpt-in onde a lei pede, e regras mais rígidas para até 60 países.
Leis de privacidade dos EUAUm banner opt-out com a opção “Não vender nem compartilhar”.
Global Privacy ControlOs sinais GPC são respeitados em todos os planos.
Recusar, tão fácil quanto aceitarRecusar fica ao lado de aceitar na primeira camada.
O idioma do visitanteConforme o navegador, com seus próprios textos do banner em cada idioma.
Layouts e temasCanto, barra ou caixa centralizada, nas suas cores, claro ou escuro.
Teste A/B do seu bannerRode de 2 a 8 versões do banner lado a lado.
Registro de consentimentosCada decisão fica guardada por 3 anos, com consulta de comprovante por ID.
Painel de consentimentoTaxas de aceite e de recusa em períodos de 7 a 90 dias.
Varreduras de cookies e rastreadoresCategorias a partir de assinaturas conhecidas, mais sugestões de IA que você aprova.
Bloqueio de scriptsOs scripts esperam pela categoria de consentimento deles antes de rodar.

Cole uma linha no seu layout raiz

Adicione o trecho de código do seu site ao head global do site, depois publique e teste no site no ar. Se as suas tags de medição já rodam pelo Google Tag Manager, use o caminho mais abaixo.

Copie a linha

Copie o trecho de código de instalação completo deste site no seu painel do Velo. O exemplo abaixo mostra o formato; substitua your-site-id antes de usá-lo. Mantenha o endpoint da API fornecido pelo seu painel.

Trecho de código de exemplo
<script src="https://cdn.veloconsent.com/v1/velo.js" data-api="https://app-staging.veloconsent.com" data-velo-site="your-site-id" async></script>

Cole no seu layout raiz

Com o App Router, abra o layout raiz (app/layout.tsx ou src/app/layout.tsx). Se ele não tiver um elemento <head>, adicione um acima de <body> e cole dentro dele o trecho de código completo do Velo, acima de qualquer tag de análise ou publicidade. Com o Pages Router, cole dentro de <Head> em pages/_document.tsx, e crie esse arquivo se o projeto não tiver um. O trecho é JSX válido como está. Não o coloque em um useEffect nem em next/script com a estratégia padrão, porque os dois o carregam quando suas outras tags já podem disparar. Faça o deploy e teste uma página que você abre por um Link, além de um recarregamento completo.

Next.js · layout raiz
// app/layout.tsx on the App Router. On the Pages Router, the same
// line goes inside <Head> in pages/_document.tsx.
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        {/* Paste the complete Velo snippet from your dashboard here. */}
        <script src="https://cdn.veloconsent.com/v1/velo.js"
                data-api="https://app-staging.veloconsent.com"
                data-velo-site="your-site-id" async></script>
      </head>
      <body>{children}</body>
    </html>
  );
}
Referência de configuração conferida com a documentação da plataforma. Não é uma captura de tela do painel administrativo. Referência de configuração verificada · 7 de novembro de 2026. Documentação da plataforma ↗

Publique e confira o site no ar

Salve e publique a mudança seguindo os passos da plataforma acima e depois limpe qualquer cache do site ou da CDN. Abra a URL publicada em uma sessão nova do navegador. Confira o banner onde as suas regras de região o exigem, teste aceitar e recusar e verifique os padrões e as atualizações de consentimento antes de as suas tags de medição rodarem. Confirme que o site aparece como instalado no seu painel do Velo.

O banner do Velo com a aparência padrão. O texto, as cores e as configurações por região do seu banner podem ser diferentes.

Usa o Tag Manager? Esqueça o código

Se o Google Tag Manager já está no seu site, esta é a forma mais fácil de adicionar o Velo. Você não mexe em código, são quatro passos curtos e todas as suas tags ficam em um só lugar.

O guia completo do Tag Manager

Adicione o Velo ao Tag Manager

Abra o template do Velo, clique em Add to workspace e escolha o seu contêiner. Abrir o template do Velo ↗

Cole o ID do seu site

No Tag Manager, abra Tags e clique em New. Clique em Tag Configuration, escolha Velo CMP e cole o ID do seu site. Você encontra esse ID no seu painel do Velo. Deixe todo o resto como está.

Faça carregar primeiro

Clique em Triggering, escolha Consent Initialization – All Pages e clique em Save. Assim o Velo começa antes das suas outras tags.

Publique e confira

Clique em Submit e depois em Publish. Só o Preview não coloca o Velo no ar. Depois abra o seu site em uma janela anônima, teste o banner e confira se o site aparece como instalado no seu painel do Velo.

Ou entregue para um agente

Copie o prompt no Claude, ChatGPT, Cursor ou no assistente que você já usa. Ele carrega tudo o que está nesta página: os dois caminhos, a ordem em que as tags precisam carregar e as verificações que provam que deu certo.

Instalar com IA

O prompt

Cole este prompt no seu assistente e depois informe o ID do seu site e o trecho de instalação completo ou as configurações do GTM que estão no seu painel do Velo.

Prompt de instalação · Next.js
Instale o Velo no Next.js.

Guia atual: https://veloconsent.com/nextjs

Antes de editar, pegue no painel do Velo o ID do meu site e o trecho de código de instalação completo ou as configurações do GTM. Confirme qual ferramenta de consentimento e quais tags de medição já rodam no site.

Escolha um único caminho de instalação:
A. Se o site já usa Google Tag Manager, adicione o template Velo CMP (publicado por veloconsent) pela Community Template Gallery. Defina o ID do meu site, o tema e o endpoint da API conforme o painel. Revise as opções avançadas; ads_data_redaction e url_passthrough vêm desligadas por padrão. Use Consent Initialization – All Pages, depois use o Preview e verifique o consentimento antes de publicar. Passo a passo completo: https://veloconsent.com/google-tag-manager

B. Para instalação direta: Com o App Router, abra o layout raiz, app/layout.tsx ou src/app/layout.tsx, adicione um elemento <head> acima de <body> se não houver um e cole dentro dele o trecho de código completo do Velo, acima de qualquer tag de análise ou publicidade. Com o Pages Router, cole dentro de <Head> em pages/_document.tsx, criando esse arquivo se o projeto não tiver um. O trecho é JSX válido como está. Não o carregue em useEffect nem com next/script na estratégia padrão: os dois o carregam quando suas outras tags já podem disparar. Faça o deploy e teste uma página aberta por um Link, além de um recarregamento completo.

Preserve o código que não tem relação com esta instalação. Evite instalações duplicadas do Velo ou padrões de consentimento concorrentes. Não presuma que colocar o código no head ou carregá-lo de forma assíncrona, por si só, garante a ordem das tags.

Confira o site publicado em uma sessão nova. Verifique o banner conforme as regras de região configuradas, os padrões iniciais de consentimento, as atualizações ao aceitar/recusar e o evento velo_consent_update. Confira se as tags que não são do Google seguem as categorias atribuídas a elas. Teste uma segunda página e qualquer checkout separado. Confirme que os sinais chegam ao painel do Velo.

Informe o que mudou, onde mudou e o resultado de cada verificação. Descreva qualquer acesso que faltou ou verificação que você não conseguiu concluir.
Trabalhando com um agente que lê a web? Aponte ele para veloconsent.com/llms.txt e /install.md para o mesmo contexto em texto puro.

Do diário

Notas sobre banners de cookies, Consent Mode e os dados que se perdem entre os dois.


Sites canadenses precisam do Consent Mode v2?
V
O diário do Velo11 de novembro de 2026
DiárioLer o post

Google Consent Mode v2 no Velo: o que há de novo

2 de novembro de 2026Ler o post

Como configurar o Google Consent Mode v2 no Shopify

2 de setembro de 2026Ler o post

Perguntas frequentes sobre o Velo no Next.js

Funciona com o App Router e com o Pages Router?

Sim. O App Router recebe o trecho no layout raiz e o Pages Router em pages/_document.tsx. Testamos os dois no Next.js 16, com recarregamentos completos e com navegação por Link.

Devo usar next/script?

Só com strategy="beforeInteractive" no layout raiz, que também funcionou nos nossos testes. Uma tag simples é mais fácil, porque está no HTML desde o primeiro byte, enquanto beforeInteractive é iniciado pelo próprio carregador do Next.js. Evite afterInteractive, o padrão, e lazyOnload, que carregam quando suas outras tags já podem disparar.

O banner continua na navegação do lado do cliente?

Sim. A navegação por Link mantém o mesmo documento, então o banner, o botão que o reabre e a escolha do visitante continuam no lugar, e a tag do layout não carrega de novo.

Meu site define uma Content Security Policy.

O trecho precisa de https://cdn.veloconsent.com em script-src e de https://app-staging.veloconsent.com em connect-src. Confira o console do navegador depois de publicar e permita o que mais a sua política bloquear.

Isso deixa o site mais lento?

O trecho de código do painel carrega de forma assíncrona. Como com qualquer script, meça o efeito dele no seu site e confira a ordem das suas tags; o carregamento assíncrono, por si só, não garante que os padrões de consentimento rodem antes das outras tags.

Um assistente de IA pode fazer isso por mim?

Sim. Copie o prompt em Instalar com agentes, logo abaixo, no Claude, ChatGPT, Cursor ou no assistente que você já usa. Ele carrega os passos desta página, a ordem em que as tags precisam carregar e as verificações que o agente tem que rodar antes de dizer que terminou.

Grátis para um site

Banner, análise e registros de consentimento para um site, grátis. Pro a partir de €7 por mês, mais IVA, para sites ilimitados.