Como rastrear instalações da Google Play a partir de UTMs do seu site

Um link no site não precisa identificar uma pessoa para ser útil na aquisição de um app. Ele precisa preservar uma campanha entre os pontos de passagem que importam: o site de origem, a landing do app, o link da loja e a primeira abertura no Android.

Essa distinção faz diferença quando o site e o app usam projetos de analytics separados. Tentar ligar a identidade do navegador à identidade do dispositivo transforma uma pergunta simples de aquisição em um problema de privacidade, consentimento e modelo de dados. Na maior parte dos produtos pequenos, isso não é necessário. A pergunta útil é outra: qual posição no site levou tráfego para a landing, qual campanha chegou à loja e quais parâmetros a Google Play devolveu depois para o app.

Este processo responde a essa pergunta mais estreita. Ele usa UTMs estáveis, um evento de CTA na landing e a API Google Play Install Referrer. O resultado é atribuição agregada por origem, campanha e posição. Não é uma prova individual de que um clique específico causou uma instalação específica.

Comece pela pergunta que os dados conseguem responder

A pergunta prática costuma ser:

Qual campanha e qual posição do site trouxeram tráfego para a loja e instalações?

Ela é diferente de:

Este visitante do navegador virou este usuário instalado?

A primeira pode ser respondida com valores de campanha. A segunda exige um desenho de identidade difícil de justificar em um site público e ainda falha quando a pessoa troca de navegador, dispositivo, conta ou momento de instalação.

Use quatro campos convencionais ao longo do caminho:

Parâmetro	Função
utm_source	Propriedade ou canal de origem
utm_medium	Tipo de encaminhamento, como referral
utm_campaign	Iniciativa de aquisição medida
utm_content	Posição dentro dessa iniciativa

Um site institucional pode montar o link assim:

utm_source=seu-site-institucional
utm_medium=referral
utm_campaign=site-para-app
utm_content=hero

Só utm_content deve variar por posição. Um link do cabeçalho pode usar header, um card pode usar catalog e o rodapé pode usar footer. Criar uma campanha nova para cada botão parece detalhado no começo, mas deixa o dashboard cheio de rótulos que não podem ser comparados.

Construa a primeira passagem em um único lugar

O erro mais comum é escrever a URL completa do destino em cada componente. Ela funciona até o dia em que a campanha muda, uma versão localizada perde um parâmetro ou uma nova superfície de navegação entra sem tracking.

Coloque a construção da URL em um helper pequeno. Ele recebe o locale e a posição, escolhe a rota localizada da landing e adiciona a campanha compartilhada.

type Placement = "hero" | "header" | "catalog" | "footer";

function getAppLandingHref(locale: string, placement: Placement): string {
  const path = locale === "pt-BR" ? "/pt-BR/" : "/";
  const url = new URL(path, "https://sua-landing-do-app.exemplo");

  url.searchParams.set("utm_source", "seu-site-institucional");
  url.searchParams.set("utm_medium", "referral");
  url.searchParams.set("utm_campaign", "site-para-app");
  url.searchParams.set("utm_content", placement);

  return url.toString();
}

Todo link para a landing deve usar esse helper. O site de origem ainda pode registrar um evento local, como app_destination_clicked, mas os UTMs são o contrato que atravessa domínios e projetos de analytics.

Mantenha QA visível sem tratá-lo como aquisição

Tráfego local é útil para conferir payloads. Desligar analytics em desenvolvimento cria uma lacuna: produção vira o primeiro lugar em que uma campanha malformada, uma propriedade ausente ou um flush quebrado aparece.

Envie os eventos de desenvolvimento, mas adicione uma propriedade de cohort como traffic_cohort em todos eles. Use qa localmente e external em preview ou produção. No dashboard, mostre as duas séries separadas em vez de somá-las.

Com isso, QA continua sendo evidência de que links e eventos foram exercitados. Relatórios comerciais podem usar apenas external. O erro não é enviar QA; é somar QA com tráfego externo e chamar o resultado de aquisição real.

Preserve a campanha da landing até a Google Play

A segunda passagem é onde muitos fluxos tecnicamente corretos quebram. O site institucional passa UTMs para a landing, mas a landing aponta para uma URL limpa da loja. O app acaba vendo uma instalação orgânica porque a Google Play nunca recebeu os valores originais.

Leia a URL da landing uma vez, normalize os valores e adicione-os a cada CTA da Google Play antes da navegação. Preserve parâmetros que já existam na URL da loja em vez de sobrescrevê-los. Assim o mesmo código funciona para mais de um CTA.

const landingUrl = new URL(window.location.href);
const storeUrl = new URL(storeLink.href);

for (const [key, fallback] of Object.entries({
  utm_source: "seu-app",
  utm_medium: "website",
  utm_campaign: "store-cta",
  utm_content: storeLink.dataset.placement ?? "unknown",
})) {
  if (!storeUrl.searchParams.has(key)) {
    storeUrl.searchParams.set(key, landingUrl.searchParams.get(key) ?? fallback);
  }
}

storeLink.href = storeUrl.toString();

Registre o clique de CTA antes de navegar e inclua os campos de campanha da landing junto da posição do CTA. Um evento normal do navegador pode ser perdido quando a página descarrega, então faça um flush best-effort antes de navegar na mesma aba. Não prenda a navegação esperando analytics por tempo indefinido. A pessoa chegar à loja vale mais que uma requisição extra.

O evento mostra que a landing gerou intenção. A URL mostra à Google Play quais valores devem voltar para o Android após a instalação. São sinais diferentes e precisam continuar separados no relatório.

Leia o Install Referrer uma vez no Android

O Android pode pedir à Google Play o referrer da instalação depois que o app é instalado. A API devolve uma query string bruta, que não deve ser encaminhada inteira para analytics. Extraia só os campos de campanha necessários, valide o formato e registre o resultado uma vez.

const parameters = new URLSearchParams(rawReferrer);

const attribution = {
  source: normalize(parameters.get("utm_source")),
  medium: normalize(parameters.get("utm_medium")),
  campaign: normalize(parameters.get("utm_campaign")),
  content: normalize(parameters.get("utm_content")),
};

trackEvent("install_referrer_resolved", {
  install_referrer_status: attribution.source ? "attributed" : "unattributed",
  ...attribution,
});

Persista uma marca local de processamento somente depois que algum provider aceitar o evento. Se a primeira tentativa falhar porque o dispositivo está offline, tente de novo numa abertura posterior. Se a marca for gravada antes da entrega, o único resultado de atribuição daquela instalação pode sumir sem aviso.

Essa fronteira de parsing também é o ponto para rejeitar valores inesperados. Uma validação conservadora de tamanho e caracteres é suficiente para rótulos de campanha. Não envie o referrer bruto, IDs de clique de anúncios, dados de conta ou parâmetros arbitrários como telemetria de produto.

Faça o dashboard seguir as fronteiras reais

O dashboard deve mostrar uma cadeia de medidas relacionadas, não um funil de usuário inventado. Uma primeira versão útil tem três seções.

Interesse no site e na landing

• Visualizações da landing agrupadas por origem e campanha.
• Cliques de CTA da loja agrupados por campanha e posição.
• Tráfego QA e externo em séries separadas.

Loja e atribuição de instalação

• install_referrer_resolved agrupado por origem da instalação.
• O mesmo evento agrupado por campanha e posição.
• Status de referrer atribuído, não atribuído ou inválido.

Ativação inicial do produto

• Primeira inicialização do app.
• Conclusão do onboarding.
• Primeira ação relevante no produto.

A última seção mostra se o app instalado foi de fato aberto e usado. Ela não conserta atribuição. Um evento de bootstrap pode ocorrer depois de uma instalação antiga, e o Install Referrer pode chegar em momento diferente do clique original. Os nomes das métricas precisam deixar isso claro.

Não divida simplesmente o total de CTAs da loja pelo total de Install Referrer e chame o resultado de “taxa de conversão” sem definir uma janela de atribuição e denominadores compatíveis. A pessoa pode abrir a loja agora, instalar amanhã ou instalar em outro dispositivo. Tendências agregadas por campanha continuam úteis, mas não são um livro-caixa determinístico de clique para instalação.

Valide o caminho inteiro antes de publicar o dashboard

Testes unitários comprovam a montagem da URL e o parser. Eles não provam que um link do navegador mantém UTMs depois da navegação ou que a Google Play entrega o referrer em uma instalação Android real.

Use esta sequência curta de validação:

1. Abra o site institucional local com analytics habilitado.
2. Inspecione um link de cada posição e confirme os quatro UTMs.
3. Siga um link e confirme que a landing recebe os mesmos valores.
4. Inspecione o CTA da Google Play na landing e confirme que ele preservou a campanha.
5. Em uma build Android parecida com release, instale usando esse link e abra o app conectado.
6. Confira o evento sanitizado install_referrer_resolved no analytics em tempo real.
7. Confirme que QA e tráfego externo estão separados.

O artigo sobre separar analytics Web e mobile por runtime explica por que browser e nativo precisam de fronteiras explícitas. A mesma separação ajuda a inspecionar a aquisição: as camadas Web relatam interesse pela campanha; a camada Android relata o resultado de atribuição entregue pela loja.

Checklist

• Mantenha source, medium e campaign estáveis em todo o caminho.
• Varie apenas content conforme a posição que gerou o encaminhamento.
• Gere URLs da landing por um helper único.
• Preserve UTMs da landing em todos os CTAs da Google Play.
• Registre intenção do CTA antes da navegação, com flush limitado.
• Faça parsing e sanitização do Install Referrer antes de rastrear.
• Emita o evento de atribuição uma vez e tente novamente se a entrega falhar.
• Mostre QA e externo em séries distintas.
• Trate contagens por campanha como atribuição agregada, não como uma afirmação causal individual.

O desenho é deliberadamente modesto. Ele não tenta saber quem era a pessoa em cada site e dispositivo. Ele preserva uma campanha tempo suficiente para responder à pergunta que um time pequeno consegue usar: qual posição está levando pessoas à loja e quais valores de campanha ainda chegam ao Android na primeira abertura?