Pular para o conteúdo
LojaVirtual.com.br Central de ajuda

Como adicionar JavaScript e códigos personalizados na loja

Use códigos personalizados para instalar um chat, inserir uma metatag ou adicionar um comportamento à vitrine. Você pode colar o código recebido de um fornecedor ou pedir uma proposta à IA. Use códigos de fontes em que você confia: um script ativo pode acessar o conteúdo da vitrine. Nunca cole senhas, tokens privados ou dados de clientes.

Onde encontrar

Abra Aparência > Personalizar e escolha Códigos personalizados nas ações rápidas ou no menu Mais opções (•••).

Os códigos ficam sempre no tema que você está editando. Eles acompanham o rascunho, o ZIP e o histórico. Confira a prévia e publique o tema para ativar as mudanças na loja.

Scripts comuns não executam no checkout, na confirmação do pedido nem na conta do comprador. O código padrão do Google Tag Manager tem uma exceção para funcionar também no checkout e na confirmação. Scripts escolhidos explicitamente para Finalização do pedido também têm execução própria, somente nessa página. Veja abaixo como registrar as compras.

Cadastrar e editar sem depender da IA

Ao abrir a tela, a listagem mostra os nomes e se cada código está ativo ou desativado. Essa leitura não usa IA. Cada item tem os botões Editar e Remover. Clique em Inserir para abrir um segundo modal com o formulário de um novo código; Editar abre esse formulário preenchido.

  1. Informe um nome que ajude a reconhecer o código, como “Chat de atendimento”.
  2. Escolha Onde aplicar?: site inteiro, categoria, produto ou página específica.
  3. Escolha a posição: Cabeçalho da página ou Final da página, conforme a orientação do fornecedor.
  4. Cole o HTML ou JavaScript em Código. O formato é identificado automaticamente.
  5. Mantenha Código ativo, à direita do nome, marcado para executar. Desmarque para desativar sem perder o conteúdo.
  6. Clique em Salvar no rascunho. O formulário fecha e a listagem é atualizada. Confira a prévia e publique o tema para ativar a mudança na loja.

Para excluir um cadastro, clique em Remover na listagem e confirme a remoção. Ela também fica no rascunho até publicar. O botão de salvar permanece visível. Fica desabilitado quando faltam campos obrigatórios ou quando não há alterações e a IA está desmarcada.

Aplicar no site inteiro, em uma categoria, produto ou página

  • Site inteiro: páginas da vitrine. Scripts comuns não executam no checkout, confirmação e conta; o código padrão do Google Tag Manager funciona também no checkout e confirmação.
  • Categoria específica: selecione a categoria. Inclui suas paginações e filtros, sem incluir categorias filhas automaticamente.
  • Produto: aparece um campo separado para escolher o produto que receberá o código.
  • Página específica: selecione a página inicial, carrinho, busca, a Finalização do pedido ou uma página institucional. Produtos ficam na opção Produto.

Você pode alterar o alcance de um cadastro existente. Ao salvar uma categoria ou página, o editor abre a prévia desse destino. Os códigos são inseridos pela plataforma depois de montar a página: funciona também com Liquid próprio, sem acrescentar uma chamada especial no arquivo. O cadastro acompanha o tema em custom-codes.json.

Ajuda com IA antes de salvar

No formulário, Ajuda com IA é uma caixa de seleção marcada por padrão. Ao desmarcar, Salvar no rascunho salva diretamente o código informado. Marcada, essa mesma ação passa o código pela IA antes de salvá-lo.

Quando o campo Código está vazio e a ajuda está marcada, o texto dentro do campo explica que a IA revisa, corrige e atualiza o código com os dados disponíveis da loja, incluindo um exemplo com ID DO PEDIDO. Ao desmarcar, ele mostra apenas a orientação para colar HTML ou JavaScript.

Não é necessário escrever um pedido. A instrução é fixa: conferir o código, corrigir problemas quando necessário e devolver o conteúdo completo e funcional, preservando sua finalidade e os identificadores informados. A IA também identifica o formato. Posição, alcance e ativação continuam como você escolheu. Confira a prévia antes de publicar.

Forneça os identificadores exigidos pelo serviço, como o ID e rótulo de conversão do Google Ads. Se a IA falhar ou faltar informação indispensável, o formulário permanece aberto e nada é salvo. As edições do tema não consomem a cota de IA dos recursos extras.

Scripts escritos diretamente no Liquid continuam nos arquivos originais e não aparecem nesta listagem. O modal não importa nem altera esses trechos.

Limitações e solução de problemas

Se a lista não carregar, use Tentar carregar novamente. Uma falha de conexão não significa que o tema esteja sem códigos. Erros ao salvar ou pedir ajuda à IA preservam o formulário para nova tentativa. A mensagem identifica problemas de nome, código, destino ou limites. Se a resposta da IA for inválida, informa que a falha veio da revisão e orienta tentar novamente, sem salvar o resultado.

O X fecha o formulário e volta à lista sem confirmação. Campos não salvos são descartados; códigos já salvos no rascunho permanecem. O título e o botão de salvar ficam fixos, com rolagem apenas nos campos. Durante a revisão ou o salvamento, aguarde a conclusão para fechar. O X da listagem encerra a tela.

  • A prévia é temporária e isolada do painel. Ferramentas que exigem cookies, domínio autorizado ou a origem real da loja podem não funcionar nela. Alertas nativos também são bloqueados.
  • Use URLs HTTPS completas. Não são aceitos iframes, atributos como onclick, alterações de política de segurança nem módulos JavaScript. Código que depende de eval também pode ser bloqueado.
  • Liquid não é interpretado dentro desses códigos. Não use expressões Liquid para buscar dados do comprador ou do pedido.
  • Aceita até 30 cadastros, 20 mil caracteres por código e 40 mil caracteres de código no conjunto.

Para quem veio do sistema antigo

Scripts do sistema antigo não são convertidos automaticamente. Para reutilizar um código, crie um cadastro, cole o trecho e confira sua compatibilidade antes de publicar. Esta tela altera apenas o tema em edição.

Configurar conversão com IA

Cole o código do Google Ads, Meta/Facebook ou outra ferramenta no campo Código, mantenha Ajuda com IA marcada e clique em Salvar no rascunho. A IA identifica a ferramenta e o evento pelo código informado. Para conversões de compra compatíveis, adapta o envio do valor, da moeda e da identificação do pedido aos dados da loja. Isso configura os valores enviados à ferramenta; não altera preços dos produtos.

Se o evento estiver ambíguo, faltar informação ou não houver suporte ao evento no alcance escolhido, a IA informa o que precisa ser ajustado e não salva. Visitar uma página não comprova uma compra, um cadastro ou uma adição ao carrinho. As conversões de compra usam o pagamento aprovado e não executam na prévia. A assistência não garante o recebimento pelo fornecedor; confira a configuração antes de publicar.

As orientações de configuração são enviadas à IA automaticamente. O formulário mantém apenas o campo de código e a opção Ajuda com IA, sem um bloco adicional de ajuda de conversão. O exemplo abaixo é específico do Google Ads.

Exemplo: preencher o ID do pedido com IA

Em Página específica → Finalização do pedido, você pode colar <script>var id_pedido_feito = "ID DO PEDIDO";</script> e salvar com Ajuda com IA marcada. A IA recebe a instrução de substituir o texto de exemplo pelo acesso ao ID real da loja, preservando o nome da variável. Você não precisa informar o número de um pedido real.

O preenchimento acontece quando os dados do pedido pago chegam à página. Não é imediato ao carregar o script e não acontece na prévia. Código que depende desse ID precisa aguardar esses dados; a IA deve adaptar esse trecho junto. Apenas preencher uma variável não cria uma conversão nem exige ID de Google Ads ou Meta. Já os identificadores exigidos por uma ferramenta de conversão precisam ser informados por você.

Sem Ajuda com IA, textos como ID DO PEDIDO permanecem como foram colados. Se estiver em Site inteiro ou em outra página, escolha Página específica → Finalização do pedido em Onde aplicar? e clique em Salvar no rascunho novamente.

Google Ads na finalização do pedido

  1. Escolha Inserir → Página específica → Finalização do pedido.
  2. Use o exemplo abaixo, preenchendo o ID e o rótulo da ação de conversão do Google Ads. A ajuda da IA é opcional para adaptar o envio ao total da compra e ao identificador da transação fornecidos pela loja.
  3. Confira o código, clique em Salvar no rascunho e publique o tema. A prévia usa um pedido fictício e não executa esses scripts de conversão.

O código fica restrito à confirmação do pedido. Visitar produto, carrinho ou a etapa de escolha do pagamento não dispara a conversão. A função de compra aguarda pagamento aprovado; gerar Pix ou boleto ainda não conta como compra paga.

Para quem configura o código, a função send(order, complete), registrada em window.lojavirtualPurchase, recebe order.order_total (total em reais), order.currency (BRL), order.order_id (número do pedido) e order.transaction_id (identificador estável da loja e do pedido). Use o último em transaction_id no Google Ads e ligue event_callback a complete. Há um exemplo técnico completo de conversão direta, incluindo a instalação da tag e os campos a substituir.

Após o callback de processamento da tag, a loja guarda uma marca por destino e transação no navegador. Atualizar ou reabrir a página não reenvia essa conversão enquanto a marca estiver disponível. O histórico mantém até 100 eventos por 30 dias. Se o armazenamento estiver bloqueado, for apagado ou a compra for aberta em outro dispositivo, o mesmo identificador permite ao Google Ads reconhecer a repetição na mesma ação de conversão. Veja a orientação do Google sobre IDs de transação.

Se a tag estiver bloqueada e não confirmar o processamento, a loja permite tentar de novo ao reabrir. O callback não comprova atribuição no Google. Confira o recebimento no destino em ambiente de teste; não use pedidos reais para testes automatizados. Se o pagamento for aprovado depois de fechar a página, o envio depende de reabrir a confirmação.

Se a mesma compra já é enviada pelo GTM, mantenha apenas um envio para essa ação. Preserve a configuração de consentimento e não envie a URL privada completa do pedido. Scripts gerais antigos não são migrados automaticamente para essa opção.

Registrar compras com Google Tag Manager

O Google Tag Manager (GTM) é o gerenciador que encaminha informações para ferramentas como Google Analytics e Google Ads. A LojaVirtual prepara os dados do pedido automaticamente. O responsável pelo marketing configura uma vez no GTM quais informações serão enviadas e para qual conta.

O que fazer na LojaVirtual

  1. No Google Tag Manager, copie o primeiro código de instalação, indicado para o cabeçalho da página. Ele contém o identificador que começa com GTM-.
  2. Aqui em Códigos personalizados, escolha Inserir e Site inteiro. Escolha a posição Cabeçalho da página, cole o primeiro código de instalação e salve no rascunho.
  3. Use o trecho JavaScript padrão, com o nome dataLayer. Não cole o segundo trecho com iframe/noscript nem misture outros códigos dentro da mesma tag. Trechos modificados podem não ser reconhecidos para uso no checkout.
  4. Confira e publique o tema. O GTM reconhecido não é carregado na prévia do editor. Se o tema já tinha o mesmo container ou outro rastreamento de compra, remova a instalação repetida.

O que a LojaVirtual informa

Na página de confirmação, a loja prepara uma dataLayer: uma caixinha de informações que o GTM pode ler. Ela contém número identificador da compra, produtos, quantidades, descontos, frete, créditos utilizados e valores em reais. Você não precisa digitar o valor de cada venda nem capturar o preço escrito na tela.

  • order_created significa pedido feito. Não significa que o pagamento foi recebido.
  • purchase significa pagamento aprovado, com data de confirmação registrada. Criar Pix ou boleto não dispara esse evento de compra paga.

Exemplo: produtos de R$ 100, desconto de R$ 10 e frete de R$ 15. O total do pedido é R$ 105. Para o Analytics, o valor dos produtos é R$ 90 e o frete é R$ 15, informado separadamente. Créditos da loja são tratados como pagamento; juros e acréscimos ficam separados dos produtos.

O que configurar no Google Tag Manager

  1. Configure a tag Google para sua conta. Se houver controle de consentimento, configure-o também no GTM antes das tags que dependem dele.
  2. Crie um acionador de Evento personalizado com o nome exato purchase.
  3. Para GA4, crie a tag de evento purchase com esse acionador e habilite os dados de comércio eletrônico vindos da dataLayer. Os dados ficam dentro de ecommerce. Não crie uma segunda compra acionada apenas pela URL da confirmação.
  4. Para Google Ads direto, use o mesmo acionador e as variáveis ecommerce.transaction_id, ecommerce.currency e o valor escolhido para a conversão. ecommerce.value é o valor líquido dos produtos; ecommerce.order_total é o total a pagar, incluindo frete e ajustes. Se você importar a compra do GA4 para o Ads, evite contar também a mesma compra por outra tag direta como conversão principal.
  5. Configure o identificador da transação em todas as tags de compra. Ele é estável, por exemplo lv-9-17. Isso ajuda o destino a reconhecer uma repetição da mesma compra.
  6. Não envie a URL completa da confirmação, que contém uma chave privada de acesso ao pedido. Na tag Google, defina page_location como a origem da loja mais /pedido/confirmacao para essa página; remova também essa chave de page_referrer. Isso vale inclusive para a visualização automática de página, antes do evento de compra.

Como conferir se funcionou

Use uma loja e contas de teste. No modo de prévia do GTM (Tag Assistant), confira se o container carrega na vitrine, no checkout e na confirmação. Faça um pedido fictício e confira o evento order_created, sem purchase enquanto estiver pendente. Após a confirmação do pagamento, confira purchase e os valores. Reabra a página para testar repetição.

Confira também o recebimento na ferramenta de destino, por exemplo o DebugView do GA4. Ver o container carregado ou a informação na dataLayer não comprova que a compra chegou ao Google. Pagamentos identificados pela plataforma como sandbox não são enviados como compra; a homologação desse caso deve usar dados simulados em ambiente isolado, sem pagamento real.

Limites deste funcionamento

O envio funciona somente enquanto o comprador está na página do pedido. Se ele fechar a página e o pagamento for aprovado depois, esse caminho não envia a compra naquele momento. Ao reabrir a confirmação, a loja consulta novamente a situação. Não existe uma fila de envio pelo servidor, e esta integração não cria tabelas no banco.

A loja consulta a situação até 20 vezes, em intervalos de 15 segundos, e também quando o pagamento muda na tela ou a página volta a ficar visível. Bloqueadores, recusa de cookies, falhas de conexão e configuração das tags podem impedir a coleta. Há proteção contra repetição no mesmo navegador; outros navegadores e dispositivos precisam da identificação da transação no destino. Um pedido cancelado não gera automaticamente um estorno no Analytics.

Veja também