Guia de instalação do Astro
Adicione o Velo ao Astro
Instale o banner de cookies do Velo e o Google Consent Mode v2 no Astro com uma linha no seu layout compartilhado. Com acesso ao código do site, a maioria das instalações leva poucos minutos. Se você usa o Google Tag Manager, esta página também cobre esse caminho.
Instruções e fontes das imagens revisadas em 7 de novembro de 2026.
O que você precisa no Astro
Antes de começar
- Onde. src/layouts/Layout.astro → head
- Plano. Qualquer projeto Astro
- 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.
Duas formas de instalar o Velo no Astro
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
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.
Se você usa ClientRouter, o Astro substitui todo o body da página a cada navegação, o que remove o banner e o botão que o reabre. Adicione o segundo script curto do passo 2 e os dois ficam. Sem ClientRouter, cada link é um carregamento completo da página e você não precisa desse script.
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.
Cole uma linha no seu layout
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.
<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 compartilhado
Abra o layout que todas as páginas compartilham, normalmente src/layouts/Layout.astro. Cole o trecho de código completo do Velo dentro de <head>, acima de qualquer tag de análise ou publicidade, e adicione is:inline à tag script para que o Astro a deixe exatamente como está. Se o layout usa <ClientRouter />, o Astro substitui o body a cada navegação, e isso remove o banner. Para mantê-lo, adicione no mesmo head um script is:inline que guarde #velo-banner-host e #velo-reopener-host em astro:before-swap e os adicione a document.body em astro:after-swap. Depois faça o build e o deploy.
<!-- src/layouts/Layout.astro: the layout every page shares -->
<html lang="en">
<head>
<meta charset="utf-8" />
<!-- Paste the complete Velo snippet from your dashboard here, then add is:inline. -->
<script is:inline src="https://cdn.veloconsent.com/v1/velo.js"
data-api="https://app-staging.veloconsent.com"
data-velo-site="your-site-id" async></script>
<!-- Only if this layout uses <ClientRouter />: keeps the banner across page swaps. -->
<script is:inline>
document.addEventListener('astro:before-swap', () => {
window.veloHosts = [...document.querySelectorAll('#velo-banner-host, #velo-reopener-host')];
});
document.addEventListener('astro:after-swap', () => {
document.body.append(...window.veloHosts);
});
</script>
</head>
<body>
<slot />
</body>
</html>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 ManagerAdicione 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 IAO 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.
Instale o Velo no Astro. Guia atual: https://veloconsent.com/astro 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: No layout que todas as páginas compartilham, normalmente src/layouts/Layout.astro, cole o trecho de código completo do Velo dentro de <head>, acima de qualquer tag de análise ou publicidade, e adicione is:inline à tag script para que o Astro a deixe exatamente como está. Se o layout usa <ClientRouter />, o Astro substitui o body a cada navegação, o que remove o banner: no mesmo head, adicione um script is:inline que guarde #velo-banner-host e #velo-reopener-host em astro:before-swap e os adicione a document.body em astro:after-swap. Faça o build e o deploy. 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.
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?
Google Consent Mode v2 no Velo: o que há de novo
Como configurar o Google Consent Mode v2 no Shopify
Perguntas frequentes sobre o Velo no Astro
Para quais sites Astro isto serve?
Qualquer projeto Astro com um layout compartilhado, seja estático ou renderizado no servidor, porque a tag fica no HTML que o layout gera. Testamos os passos no Astro 7 com saída estática.
Preciso adicionar is:inline?
É a opção segura. O Astro já deixa como está qualquer script com atributos além de src, então o trecho fica intacto de qualquer forma, e is:inline torna isso explícito. Mantenha os atributos data exatamente como o seu painel mostra.
O banner some quando clico em um link.
É o ClientRouter substituindo o body da página quando o visitante navega. Adicione o segundo script do passo 2 ao mesmo head, e o banner e o botão que o reabre passam para cada nova página. O transition:persist do Astro não ajuda aqui, porque o Velo adiciona esses elementos depois que a página carrega.
Meu site tem mais de um layout.
Coloque o trecho no layout base que os outros envolvem. Se os seus layouts não compartilham nenhum, adicione a cada um. O Velo ignora uma segunda cópia na mesma página, mas confira se o banner aparece em todas as seções do site.
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.