Adicione parâmetros UTM a um link curto

Parâmetros UTM contam à sua ferramenta de análise de onde veio a visita. O Construtor UTM do construtor de links acrescenta esses parâmetros à sua URL de destino, então o Google Analytics — e qualquer outra ferramenta instalada no seu site — enxerga a campanha. A CodeQR também relata por eles.

Disponibilidade

Plano: todos, inclusive o gratuito.
Onde: Construtor UTM no construtor de links, abaixo da divisória Opcional. Existe também uma página Construtor de UTM avulsa, no menu ao lado de Adicionar Link na página Links.

Antes de começar

Preencha URL de destino primeiro: os campos ficam desabilitados enquanto a CodeQR não tem um endereço válido para receber os parâmetros.

E saiba de uma coisa antes de mexer na chave, porque ela explica todo o resto: os parâmetros ficam dentro da sua URL de destino. A CodeQR não guarda UTM em um lugar separado. Enquanto você digita, o campo URL de destino muda na sua frente.

Passos

No construtor de links, ligue o Construtor UTM.
Preencha os campos que você usa. O mínimo de sempre é Origem UTM e Mídia UTM; Campanha UTM dá nome à campanha.
Olhe a URL de destino — ela agora termina com ?utm_source=…&utm_medium=….
Clique em Criar link.

A seção Construtor UTM com origem, mídia, campanha, termo e conteúdo preenchidos

Os seis campos são Indicação (ref), Origem UTM, Mídia UTM, Campanha UTM, Termo UTM e Conteúdo UTM. Os cinco UTM são os padrões que toda ferramenta entende. Indicação (ref) grava ?ref= em vez disso, o que algumas ferramentas e programas de afiliados leem; a CodeQR guarda esse valor na URL como os demais, mas não o trata como campo de campanha nos relatórios.

Convenções que evitam retrabalho

Escreva tudo em minúsculas. O Google Analytics 4 trata Newsletter e newsletter como origens diferentes, o que parte uma campanha em duas linhas.
Use - ou _ no lugar de espaços. Um espaço chega como %20 ou + conforme a ferramenta que enviou, e isso também vira linha separada.
Mantenha o mesmo vocabulário entre campanhas — escolha email ou newsletter para a mídia e fique com ele.
Desligar a chave apaga os parâmetros da sua URL de destino. É assim que se removem; é assim também que se perdem sem querer.

O que acontece quando o destino já tem parâmetros

O que já estava na URL de destino permanece. O construtor acrescenta ou substitui apenas os seis campos que ele controla, então um destino como https://example.com/cardapio?mesa=12 continua com mesa=12.

Há um segundo caso, menos óbvio: o visitante que chega com parâmetros próprios. Tudo que vem no link curto é repassado ao destino, e um parâmetro de mesmo nome vence o que está guardado no link. Um link cujo destino leva utm_source=newsletter, aberto como go.example.com/cardapio?utm_source=instagram&extra=1, cai em:

https://example.com/cardapio?utm_source=instagram&extra=1&utm_medium=email&utm_campaign=agosto

O utm_source do visitante substituiu o do link; os outros parâmetros sobreviveram. É isso que torna um mesmo link curto reaproveitável em vários canais — acrescente ?utm_source= ao link curto na hora de compartilhar e o destino enxerga o canal que você nomeou.

Onde os números aparecem

A CodeQR mostra campanhas em Análise → relatório de UTM, descrito em Meça campanhas UTM em links e QR codes. Esses números vêm dos parâmetros guardados com o link, então editar os valores de UTM de um link muda o agrupamento das visitas passadas.

As Regras inteligentes também leem parâmetros UTM para mandar origens diferentes a páginas diferentes — veja Roteie o tráfego de campanha por UTM ou referenciador.

Monte a URL de campanha sem criar um link

A página Construtor de UTM avulsa monta o endereço sozinha: preencha URL de destino e os cinco campos UTM, leia o resultado em Sua URL de campanha e use Copiar URL para uma página que você vai linkar em outro lugar, ou Salvar como link curto para abrir o construtor já preenchido.

The standalone UTM Builder page with the campaign URL assembled

Faça o mesmo pela API

Coloque os parâmetros dentro de url. Não existe campo utm_source no corpo da requisição — enviar um não tem efeito nenhum:

curl -X POST https://api.codeqr.io/links \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/cardapio?utm_source=newsletter&utm_medium=email&utm_campaign=agosto","domain":"go.example.com","key":"cardapio-agosto"}'

A resposta lê os valores de volta da URL para campos próprios, que você pode filtrar e exportar:

{
  "url": "https://example.com/cardapio?utm_source=newsletter&utm_medium=email&utm_campaign=agosto",
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "agosto"
}

Verifique se funcionou

curl -sSI https://go.example.com/cardapio-agosto

HTTP/2 302
location: https://example.com/cardapio?utm_source=newsletter&utm_medium=email&utm_campaign=agosto

A linha location é exatamente o que o navegador vai pedir, então o que está ali é o que a sua ferramenta de análise recebe. No Google Analytics, a visita aparece nessa origem e mídia no relatório em tempo real em poucos minutos.

Solução de problemas

Minha ferramenta mostra a visita como direta

Os parâmetros não estão chegando. Confira a linha location acima: se eles não estão lá, a chave foi desligada depois de preenchida, ou alguém editou o destino na mão. Verifique também se a página de destino não redireciona de novo — um redirecionamento no seu próprio site pode descartar a query string.

A mesma campanha aparece duas vezes

São duas grafias do mesmo valor, quase sempre diferindo em maiúsculas ou num espaço. Padronize o valor e edite os links; as visitas novas agrupam certo, e o relatório de UTM da CodeQR segue os valores atuais do link.

Os parâmetros sumiram da minha URL de destino

Desligar o Construtor UTM remove os seis da URL. Ligue de novo e preencha, ou cole a URL completa, com parâmetros, em URL de destino — os campos se preenchem a partir dela.

Os campos de UTM estão cinza

Ainda não há um destino válido. Cole um endereço completo, começando com https://, e eles ficam editáveis.