Análise gratuita Sobre o Velo Suporte Contato
Começar com o Velo

Já tem uma conta? Entrar

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. A maioria das instalações leva poucos minutos quando você já tem acesso ao código do site. Se você usa Google Tag Manager, esse caminho também está nesta página.

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

Ondeapp/layout.tsx → head
PlanoApp Router ou Pages Router
Entra no arDepois do próximo deploy
Tempo típicoCerca de cinco minutos

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 o resultado. Se as suas tags de medição já rodam pelo Google Tag Manager, use o caminho abaixo.

Já usa o Google Tag Manager? Esqueça o código e faça por lá ↓

Três passos · cerca de cinco minutos

  1. 01

    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.

    <script src="https://cdn.veloconsent.com/v1/velo.js" data-api="https://app.veloconsent.com" data-velo-site="your-site-id" async></script>
  2. 02

    Cole no seu layout raiz

    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.

    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.veloconsent.com"
                    data-velo-site="your-site-id" async></script>
          </head>
          <body>{children}</body>
        </html>
      );
    }
    Referência de configuração verificada · 7 de novembro de 2026

    Referência de configuração conferida com a documentação da plataforma. Não é uma captura de tela do painel administrativo.

    Documentação da plataforma ↗
  3. 03

    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.

    Velo · banner de consentimento no ar
    Captura da interface no ar · 23 de setembro de 2026

    O banner real em veloconsent.com, capturado em 23 de setembro de 2026. O texto, o layout e as configurações regionais do seu banner podem ser diferentes.

    Site do Velo no ar ↗Ver em tamanho real ↗
Um ponto de atenção

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 aberta por um Link, além de um recarregamento completo: o banner deve continuar no lugar, sem uma segunda cópia.

Ainda comparando opções? Veja todas as plataformas compatíveis.

O mais fácil se você usa o Tag Manager

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.

  1. 01

    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 ↗
  2. 02

    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á.

  3. 03

    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.

  4. 04

    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.

O guia completo do Tag Manager Inclui o teste no Preview e as configurações opcionais. Ainda não tem Tag Manager neste site? Siga os passos acima.

Perguntas sobre o Next.js,
respondidas.

O que os times que instalam no Next.js perguntam primeiro.

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: ela 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.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.

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.

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 ampliodata) 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; as duas 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.

Google Consent Mode v2 no Velo: o que há de novo Consent Mode v2 ligado desde a instalação, banner nos requisitos do Google, análise de cada página com aviso por e-mail e suporte em primeiro lugar. 2 de novembro de 2026
Como configurar o Google Consent Mode v2 no Shopify Defina os padrões como denied acima do contêiner e então grave a escolha do visitante tanto no Google Consent Mode quanto na Customer Privacy API do Shopify, no mesmo clique. 2 de setembro de 2026
Google Consent Mode no Squarespace: configuração e limites O banner nativo do Squarespace bloqueia os cookies de análise, mas não envia sinais de Consent Mode. 16 de agosto de 2026