GCLID em cadastros Next.js: contrato local com testes de consentimento

Para preservar um GCLID em um cadastro Next.js, separe captura permitida, continuidade do contexto e associação ao lead no servidor. O exemplo abaixo testa esse contrato em memória. Ele não é uma aplicação Next.js completa e não cria cookies, cadastros reais ou conversões em anúncios.

Resumo: O contrato local captura um identificador sintético apenas com permissão explícita, conserva a primeira entrada durante a navegação e descarta atribuição quando a permissão é retirada. O cadastro recebe um ID controlado pelo servidor, ignorando a identidade enviada pelo formulário. As assertions verificam ausência, duplicidade e adulteração. Esses resultados cobrem a lógica ilustrativa; integração com Next.js, CMP, armazenamento, banco e provedor exige testes próprios antes de qualquer implantação.

Por FunnelSheet. Revisado em 15 de setembro de 2026. Transparência: publicamos conteúdo sobre ClickTrail e temos interesse comercial nesse ecossistema. O teste é editorial, sintético e local; não usa dados de clientes nem demonstra uma integração de produção.

O que foi testado e o que precisa existir no aplicativo?

Foi testado um programa JavaScript autônomo com Node.js v24.15.0, usando apenas módulos nativos. Ele modela a decisão de capturar, manter ou remover contexto e a associação a um cadastro fictício. Nenhuma versão de Next.js foi instalada ou executada nesta validação.

Em uma implementação Next.js, o navegador observa a URL, a camada de consentimento informa a permissão aplicável e o servidor valida o cadastro. A documentação de formulários do Next.js explica como formulários enviam dados para Server Actions. Essa infraestrutura resolve transporte e execução; as regras de atribuição continuam sendo responsabilidade da aplicação.

O repositório público nextjs-google-ads-offline-conversions foi inspecionado em um commit fixo. O arquivo de captura local estava diferente desse commit. Por isso, este tutorial apresenta um contrato independente e não atribui ao pacote público os testes de consentimento realizados aqui. Confirme a versão efetivamente incorporada antes de reutilizar qualquer trecho.

Como impedir captura antes da permissão?

Faça o estado não resolvido produzir o mesmo bloqueio de captura que a recusa, dentro da política escolhida para este exemplo. A presença de gclid na URL não expressa consentimento. Uma marcação escondida no formulário também não é uma fonte confiável para essa decisão.

O contrato usa três valores explícitos: granted, denied e unknown. Somente o primeiro permite retornar atribuição. Esses valores pertencem à ilustração; não são uma tradução automática dos estados de qualquer CMP. Na adaptação, documente qual permissão a operação exige e de onde o servidor obtém sua versão atual.

O ponto de bloqueio fica antes da leitura do identificador. Isso torna o teste negativo objetivo: quando a permissão não existe, a saída deve ser nula. Em um navegador real, será necessário verificar também cookies, armazenamento e requisições. Um teste em memória não pode comprovar a ausência desses efeitos em scripts que ele não executou.

Como conservar o GCLID durante a navegação?

Conserve a primeira captura válida em vez de exigir que toda página continue carregando o parâmetro na URL. Na ilustração, a página de entrada tem TEST_B06; a página de cadastro não tem parâmetro, mas recebe o contexto já permitido.

O exemplo usa memória, que termina com o processo. Essa escolha permite testar a regra sem esconder dependências de navegador. Ela não oferece persistência entre recargas ou dispositivos. A implementação real precisa escolher armazenamento, escopo, validade e comportamento após retirada, além de testar a navegação usada pelo aplicativo.

A página de entrada armazenada contém apenas origem e caminho. O parâmetro fictício email=omitido não acompanha o registro. Essa é uma decisão de minimização do exemplo, não uma garantia sobre toda a biblioteca ClickTrail. Além disso, valores duplicados de GCLID são rejeitados para evitar uma escolha ambígua. O limite de 128 caracteres é didático e não deve ser tratado como o limite oficial do Google.

Como executar o contrato completo sem chamar provedores?

Salve o código abaixo em capture-contract.mjs e execute node capture-contract.mjs. A saída esperada é a última mensagem do programa, sem erros de assertion. O bloco foi executado localmente; não precisa de pacote npm, credenciais ou acesso a uma conta de anúncios.

import assert from 'node:assert/strict';

// Contrato editorial sintético: memória local, sem cookies ou rede.
function capture(previous, input, consent) {
  if (consent !== 'granted') return null;
  const url = new URL(input);
  if (url.origin !== 'https://example.invalid') throw new Error('origin');
  if (previous) return previous;
  const ids = url.searchParams.getAll('gclid');
  if (ids.length !== 1 || !/^[A-Za-z0-9_-]{1,128}$/.test(ids[0])) return null;
  return Object.freeze({ gclid: ids[0], landing: url.origin + url.pathname });
}

function attach(form, trustedLeadId, saved, consent) {
  if (!/^synthetic-lead-\d+$/.test(trustedLeadId)) throw new Error('lead');
  if (typeof form.name !== 'string' || !form.name.trim()) throw new Error('name');
  return {
    leadId: trustedLeadId,
    name: form.name.trim(),
    attribution: consent === 'granted' && saved ? { ...saved } : null,
  };
}

const url = 'https://example.invalid/entrada?gclid=TEST_B06&email=omitido';
assert.equal(capture(null, url, 'denied'), null);
assert.equal(capture(null, url, 'unknown'), null);
const saved = capture(null, url, 'granted');
assert.deepEqual(saved, { gclid: 'TEST_B06', landing: 'https://example.invalid/entrada' });
assert.equal(capture(saved, 'https://example.invalid/cadastro', 'granted'), saved);
assert.equal(capture(saved, url, 'denied'), null);
assert.equal(capture(null, 'https://example.invalid/cadastro', 'granted'), null);
assert.equal(capture(null, url + '&gclid=outro', 'granted'), null);
assert.equal(capture(null, 'https://example.invalid/?gclid=%3Cscript%3E', 'granted'), null);
assert.throws(() => capture(null, 'https://outro.invalid/?gclid=TEST', 'granted'), /origin/);
const record = attach({ name: 'Teste', leadId: 'adulterado', gclid: 'adulterado' }, 'synthetic-lead-6', saved, 'granted');
assert.equal(record.leadId, 'synthetic-lead-6');
assert.equal(record.attribution.gclid, 'TEST_B06');
assert.equal(attach({ name: 'Teste' }, 'synthetic-lead-6', saved, 'denied').attribution, null);
assert.throws(() => attach({ name: '' }, 'synthetic-lead-6', saved, 'granted'), /name/);
console.log('B06: contrato local aprovado; sem cookies, rede ou app Next.js');

A variável saved representa contexto que a camada chamadora controla. O objeto congelado evita alteração acidental durante este teste, mas não autentica um cookie nem impede adulteração de uma requisição. Na aplicação real, nunca aceite do navegador um objeto chamado “confiável” apenas porque ele passou pela mesma função.

Como associar o contexto ao cadastro correto?

Resolva a identidade no servidor depois de validar a operação comercial. O formulário pode fornecer nome e outros dados necessários ao cadastro, mas não deve escolher livremente qual lead receberá a atribuição.

No teste, synthetic-lead-6 é passado separadamente, simulando uma referência controlada pelo servidor. O formulário tenta enviar outro leadId e outro gclid; ambos são ignorados pela associação. Isso verifica apenas a separação de responsabilidades. Não implementa autenticação, autorização, criação de lead, prevenção de abuso ou transação no banco.

Essas verificações devem existir no aplicativo que receber a função. A documentação de segurança do Next.js recomenda validar entrada e autorização nas operações de servidor. Considere também o caso em que o cadastro foi salvo, mas a preparação posterior falhou: a resposta não deve inventar uma conversão entregue.

Para acompanhar a próxima fronteira, o guia de formulário e CRM mostra por que campos transportados precisam ser comparados com o registro persistido. Uma atribuição corretamente associada em memória ainda não é uma linha gravada no CRM.

O que as falhas do teste ensinam?

Cada falha tem uma expectativa própria: sem sinal retorna nulo; origem incompatível lança erro; nome vazio impede associação; retirada remove atribuição da saída. Não transforme todos esses casos em um estado genérico de “erro no rastreamento”.

Se precisar inspecionar o registro resultante, faça isso com dados sintéticos como os apresentados. Não publique payloads com identificadores reais em logs de navegador. O diagnóstico local pelo ClickTrail MCP pode ajudar a organizar verificações, mas as ferramentas de envio locais não comprovam aceitação externa.

O que falta antes de integrar ao Next.js e aos anúncios?

Faltam as provas do ambiente real: comportamento da CMP, persistência, ação de servidor, banco e transporte externo. O contrato local reduz a ambiguidade das regras, mas não substitui nenhuma dessas verificações.

1. Fixe a versão do aplicativo e a fonte do contexto de consentimento.
2. Adapte a captura ao fluxo existente e teste entrada, navegação interna e recarga.
3. Confirme que recusa e retirada impedem armazenamento e envios proibidos pela política configurada.
4. Valide o cadastro e resolva sua identidade antes de associar o contexto.
5. Leia o registro persistido e teste repetição da submissão.
6. Só depois selecione um adaptador de conversão compatível com a conta e o caminho atualmente aceito pelo provedor.

O Google documenta requisitos próprios para conversões offline. Um objeto local não demonstra elegibilidade da conta, execução da chamada ou processamento. Nenhum desses estados foi testado aqui. Para orientar um agente na adaptação, use o guia de skills ClickTrail para agentes de código e peça evidência por fronteira, incluindo os casos negativos.