Como as Regras inteligentes escolhem o destino

Depois de ler esta página você consegue prever onde qualquer visitante cai num link ou QR Code com Regras inteligentes, explicar um resultado que pareceu errado e corrigir a regra se ela estava errada. Os passos para configurar cada tipo de regra estão nos guias linkados ao final.

O caminho de decisão

Para cada requisição a um link curto (ou leitura de um QR Code dinâmico), a CodeQR verifica, nesta ordem:

Antes de escolher qualquer destino — senha errada ou ausente, link expirado, link banido ou um Formulário de pré-redirecionamento não preenchido encerram a requisição aqui. As Regras inteligentes nunca rodam nesses casos.
Visualização de link personalizado para robôs — se o link tem Visualização de link personalizado ativa (Starter ou superior) e a requisição vem de um robô conhecido, o robô recebe a página de prévia.
Camuflagem de links — um link camuflado sempre mostra a sua URL de destino dentro da camuflagem. As Regras inteligentes são ignoradas; o destino de uma regra nunca é camuflado.
Regras inteligentes — as regras rodam de cima para baixo. A primeira cuja condição combina decide o destino (uma URL fixa ou uma variante de uma divisão). Se nenhuma combina, a avaliação continua.
Segmentação iOS, depois Segmentação Android, depois Segmentação Geográfica — os botões antigos por recurso, só se estiverem ligados.
URL de destino — a URL principal do link, o destino padrão de todos os demais.

A URL escolhida recebe os parâmetros de query que estavam no link curto (?utm_source=…, ?ref=…); com Monitoramento de conversão ativo, cq_id é anexado. A resposta é um redirecionamento HTTP 302 (301 para um domínio raiz) marcado como must-revalidate, então os navegadores não guardam um destino antigo no cache de redirecionamento.

Cinco Regras inteligentes no construtor de links em ordem de avaliação: Dispositivo é iOS, Dispositivo é Android, Origem UTM é newsletter, Idioma é Español, e por fim Todo o tráfego dividido 50/50

Dentro do passo 4: como uma regra combina

Uma condição por regra: atributo é / não é valor. Não existe E. Para expressar "visitantes iOS do Brasil", coloque uma regra País é Brasil com o destino iOS brasileiro acima da regra geral Dispositivo é iOS — ou aceite que a regra que vier primeiro vence.
O valor é comparado por inteiro e sem diferenciar maiúsculas. newsletter combina com Newsletter; news não combina com newsletter.
Se a requisição não traz valor para o atributo — localização desconhecida, sem referenciador, ?utm_source= vazio, idioma do navegador fora dos dez suportados — a regra não combina, diga ela é ou não é. O visitante continua descendo a lista.
Uma regra Todo o tráfego (sem condição) combina com todos, sempre divide e precisa ser a última: qualquer coisa abaixo dela nunca rodaria.
Uma regra que combina decide na hora. As regras abaixo não são consultadas, mesmo que sejam "mais específicas".

O que a CodeQR lê da requisição

Dispositivo — Lido de: o nome do sistema operacional no user agent do navegador · Consequências: O Safari do iPad se apresenta como Mac (macOS); tablets Android no modo desktop do Chrome reportam Linux; "Solicitar site para computador" esconde o sistema móvel. Não existe valor celular/tablet.
País, Região (estado), Cidade, Continente — Lido de: o endereço IP do visitante, resolvido pela rede de borda da CodeQR · Consequências: VPNs, proxies corporativos, gateways de operadoras móveis e relays de privacidade colocam o visitante onde o endereço de saída está registrado. A resolução de país acerta para a grande maioria; região e cidade são aproximadas — uma base de IP amplamente usada publica cerca de 99,8% de acerto no nível de país, cerca de 80% no de região e 66% no de cidade. Localização desconhecida → nenhuma regra de localização combina.
Idioma — Lido de: a lista Accept-Language do navegador: a primeira entrada que seja um de pt en es fr de zh ru it ja ko, sem a região (pt-BR → pt) · Consequências: A localização não importa; um visitante no Brasil com o navegador em inglês combina com English. Safari e janelas anônimas enviam um único idioma.
Referenciador — Lido de: o hostname do cabeçalho Referer sem o www. inicial · Consequências: Aplicativos, mensageiros e leituras de QR Code não enviam nenhum; navegadores enviam só a origem entre sites, e nada de HTTPS para HTTP ou em links noreferrer. l.facebook.com e facebook.com são valores diferentes.
Origem/Mídia/Campanha/Termo/Conteúdo UTM — Lido de: a query string do link curto como foi clicado · Consequências: Parâmetros digitados na URL de destino ou acrescentados com o UTM Builder não estão no link curto e não disparam regras.

O que isso significa para os dados envolvidos: a regra é avaliada a partir dos cabeçalhos da requisição e da localização derivada do endereço IP do visitante na borda. O clique que a CodeQR registra guarda o país, a região, a cidade e o continente derivados, a família de dispositivo, navegador e sistema operacional, o referenciador e a URL de destino — não o endereço IP, a string completa do user agent nem coordenadas, que são gravados vazios. O teste de divisão grava um cookie próprio (cq_id) no domínio do seu link curto por 1 hora, ou 30 dias com monitoramento de conversão. Nada mais é armazenado especificamente para as Regras inteligentes.

Dividir tráfego: atribuição e fixação

A variante de um visitante é função do link e do seu ID de clique, repartida pelos pesos. O ID de clique fica no cookie cq_id, restrito ao caminho do link curto, então o mesmo navegador cai na mesma variante por 1 hora, ou 30 dias quando o Monitoramento de conversão está ativo. Uma janela anônima, outro navegador ou outro aparelho é um visitante novo. Mudar os pesos muda as fronteiras dos baldes, então alguns visitantes recorrentes trocam. Bots também ganham balde, mas não são contados.

Bots, robôs e prévias de link

A CodeQR reconhece robôs e buscadores de prévia comuns pelo user agent (mecanismos de busca, facebookexternalhit, WhatsApp, Slack, Twitter/X, LinkedIn, ChatGPT e qualquer agente que se chame "bot").
Robôs reconhecidos ainda recebem um destino das suas regras — a menos que o link tenha Visualização de link personalizado ativa, caso em que recebem a página de prévia. QR Codes nunca servem a página de prévia.
Robôs reconhecidos não são contados como cliques ou leituras. Buscadores que se parecem com um navegador normal (a prévia do iMessage da Apple, alguns scanners de segurança de e-mail) são contados como uma pessoa e roteados como uma.
Um robô não tem sistema operacional de celular nem, em geral, Accept-Language, e o IP dele é de um data center: normalmente não combina com nenhuma regra de Dispositivo ou Idioma e pode combinar com uma regra de País do país do data center. Ele recebe esse destino e, numa divisão, uma variante — mas não deixa clique nenhum.

Cache e tempo

Salvar um link ou QR Code atualiza o redirecionamento na hora; não há atraso de propagação.
O redirecionamento 302 não fica em cache no navegador. Se um visitante "ainda vê a página antiga", a causa é o cookie fixo da divisão (acima), um favorito da própria página de destino ou o cache da página de destino — não o link curto.
A análise deduplica cliques repetidos do mesmo visitante por alguns minutos; o redirecionamento acontece toda vez mesmo assim.

Análise

Só o destino final é registrado. Análise de um link ou QR Code mostra o card URLs com cliques (e, por evento, leads e vendas) por destino — é assim que você vê qual regra ou variante disparou. Duas regras ou variantes apontando para a mesma URL são indistinguíveis. Quando a Camuflagem de links vence, a URL registrada é a URL de destino camuflada.

Analytics URLs card listing clicks per destination URL for one link

Solução de problemas

Um visitante do país X caiu na página do país Y

O tráfego dele saiu por um endereço registrado em Y — VPN, proxy da empresa, gateway de operadora móvel, relay de privacidade — ou a base de IP está desatualizada para aquele endereço. Pergunte em que rede ele estava; confira o card Países em Análise para ver onde a CodeQR posicionou o clique. Mantenha a URL de destino utilizável para qualquer pessoa e não coloque nada com consequência jurídica ou de preço atrás de uma regra de Cidade ou Região (estado).

A regra nunca combina com ninguém

Compare o valor com o que a requisição carrega: iOS/Android/Windows/Mac OS/Linux para Dispositivo (não mobile); BR e não Brasil; SP e não São Paulo ou BR-SP; instagram.com e não https://www.instagram.com/; um UTM que esteja no link curto, não no destino. Lista completa na referência.

Duas regras se aplicam ao mesmo visitante — qual vence?

A que está mais acima na lista. A ordem importa: coloque regras específicas (cidade, campanha) acima das gerais (país, dispositivo). Uma regra Todo o tráfego só pode ser a última.

Configurei uma regra Dispositivo é iOS e também a Segmentação iOS

A Regra inteligente vence; Segmentação iOS, Segmentação Android e Segmentação Geográfica só são consultadas quando nenhuma Regra inteligente combinou. Pode deixar os botões antigos desligados.

As regras estão ligadas, mas todo visitante vê a URL de destino

Confira a Camuflagem de links: um link camuflado ignora as Regras inteligentes. Depois confira se o link não está expirado ou protegido por senha de um jeito que encerre a requisição antes. Depois confira os valores (item anterior).

A mesma pessoa sempre recebe a mesma variante

Esperado: atribuição fixa por 1 hora, ou 30 dias com monitoramento de conversão. Teste numa janela anônima.

O link mostra cliques antes de eu compartilhar — ou mais cliques do que pessoas que poderiam ter clicado

Prévias de link (WhatsApp, Slack, iMessage, Facebook, LinkedIn, Telegram) e scanners de segurança de e-mail buscam a URL. Robôs reconhecidos não são contados; buscadores que se parecem com navegadores são. Rajadas de cliques segundos depois de enviar um e-mail ou mensagem são a assinatura.

A prévia do link mostra a minha página padrão, não a do país ou da loja

Robôs de prévia raramente combinam com uma regra de Dispositivo ou Idioma e recebem a URL de destino (ou uma regra de País do data center deles). Quem toca no link é roteado pela própria requisição.

Um visitante no Brasil com o navegador em inglês recebeu a página em inglês

Idioma é o idioma do navegador, não a localização. Se a localização deve vencer, coloque a regra de País acima da regra de Idioma.

A regra de Região nunca dispara

Use o código ISO 3166-2 sem prefixo (SP, RJ, CA), nunca o nome nem a forma com o país na frente.

A loja abriu mas o app não, ou "o app não abriu" no iOS

Links que abrem o app (Universal Links, App Links) não são honrados atrás de um redirecionamento pela Apple nem pelo Google. Aponte as regras para as URLs das lojas (https://apps.apple.com/…, https://play.google.com/store/apps/details?id=…) e deixe a loja entregar ao app; nunca market:// nem itms-apps://.

Usuários de iPad combinam com macOS, não com iOS

O Safari no iPadOS se identifica como Mac. Decida se Mac e iPad devem dividir um destino e acrescente uma regra Dispositivo é macOS conforme o caso.

Mudei uma regra e o visitante ainda vê a página antiga

Mudanças de regra valem na hora. Se for uma divisão, o cookie do visitante mantém a variante dele pela janela fixa. Se for uma URL fixa, ele provavelmente está abrindo um favorito ou uma cópia em cache da página de destino em um aplicativo, ou o seu próprio site guardou o conteúdo antigo em cache.

A análise não me diz qual regra disparou

Só os destinos são registrados. Dê a cada regra e variante a sua própria URL (acrescente um caminho ou ?v=b) para o card URLs conseguir distingui-las.

A API recusou minhas regras

403 em Free/Starter/Pro ou em QR Code estático; 400 unprocessable_entity para erros de formato, com o índice da regra que falhou na mensagem. A lista completa está em Crie Regras inteligentes com a API, o MCP e automações.