Skip to content
Guia da Central de Ajuda · Distribuição de passes
4 min de leituraVerificado 2026-11-16

Parâmetros de rastreamento UTM

Rastreie campanhas de marketing, fontes de anúncios e funis de conversão em links de distribuição de passes e PassFlows com atribuição de primeiro toque.

Neste guia

Visão geral de atribuição de marketing e acompanhamento de campanhas

Ao distribuir passes digitais através de anúncios em redes sociais, parcerias com influenciadores, newsletters por e-mail, expositores QR em loja e redes de afiliados, medir o ROI de cada canal é essencial. A Passinstance inclui Acompanhamento Nativo de Parâmetros UTM (UTM Attribution Engine e UTM Tracking API em /templates/:templateId/utm-tracking) para captar origens de tráfego, monitorizar conversões de inscrição de passes e registar atribuição de marketing de primeiro toque diretamente em cada registo de passe emitido.

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
PIPELINE DE ATRIBUIÇÃO UTM E TELEMETRIA
ETAPA 01 PONTO DE CONTACTO DA CAMPANHA DE MARKETING
Cliente clica na ligação ou lê código QR com etiquetas UTM: https://app.passinstance.com/f/vip-club?utm_source=instagram&utm_medium=story...
ETAPA 02 MOTOR DE INGESTÃO E ATRIBUIÇÃO UTM
Ingere parâmetros de consulta: utm_source, utm_medium, utm_campaign, etc.
Capta o cabeçalho HTTP Referer e o landingUrl inicial
Impõe Atribuição de Primeiro Toque (ATTRIBUTION_MODEL = 'FIRST_TOUCH')
ETAPA 03 PERSISTÊNCIA DE ATRIBUIÇÃO DO PASSE (BASE DE DADOS)
Persistido permanentemente no campo JSON Pass.attribution:
utm_source: "instagram"
utm_medium: "story"
utm_campaign: "summer_promo_2026"
tag: "influencer_sarah"
capturedAt: Carimbo ISO | capturedFrom: "PASSFLOW"
ETAPA 04A EXPORTAÇÃO CSV E ANÁLISES
Incluído em POST/passes/export
Filtrar coortes por campanha
ETAPA 04B WEBHOOKS DE INTEGRAÇÃO
Reencaminhado em pass.created
Sinc. com CRM / Google Analytics4

Etiquetas e parâmetros UTM suportados

A Passinstance adota a taxonomia UTM padrão da indústria do Google Analytics em conjunto com etiquetas personalizadas:

Chave de parâmetroFinalidadeValor de exemploMelhor utilização
utm_sourceIdentifica a plataforma de tráfego ou origemfacebook, instagram, newsletter, counter_qrDeterminar que plataforma trouxe o visitante
utm_mediumO canal de marketing ou meio de entregacpc, social, email, print_flyer, smsDistinguir anúncios pagos de meios orgânicos ou material impresso
utm_campaignNome da campanha promocional específicaspring_launch_2026, black_friday_vip, store_openingAgrupar passes emitidos sob uma iniciativa específica
utm_termPalavra-chave de pesquisa paga ou segmento de audiêncialoyalty_rewards, coffee_club, fitness_subAcompanhar palavras-chave específicas ou variantes de audiência
utm_contentCriativo de anúncio específico ou variante de CTAblue_button, story_ad_v2, table_stand_4Testes A/B de variações de anúncios ou diferentes balcões
utm_idID de campanha de CRM ou automação de marketingcamp_01j8k9m2, ad_99214Correlacionar emissão de passes com IDs do Google Ads ou HubSpot
tagIdentificador de categorização em formato livrestore_munich, partner_nike, staff_alexEtiquetas de acompanhamento personalizadas do seu fluxo de negócio

Modelo de atribuição de primeiro toque (FIRST_TOUCH)

A Passinstance implementa um Modelo de Atribuição de Primeiro Toque (ATTRIBUTION_MODEL = 'FIRST_TOUCH', FIRST_TOUCH_SOURCE = 'UTM_FIRST_TOUCH'):

  1. 1
    Fixação na Sessão: Quando um potencial cliente acede pela primeira vez a um PassFlow público (/f/:slug) ou a uma Ligação Inteligente (/d/:slug) com parâmetros UTM, a Passinstance grava o conjunto de atribuição no armazenamento da sessão.
  2. 2
    Invariante de Primeiro Toque: Se o cliente sair da página, comparar planos ou regressar horas depois através de uma ligação direta, a origem original da campanha que o trouxe inicialmente à sua marca é preservada.
  3. 3
    Telemetria Imutável do Passe: Assim que o passe é gerado, o objeto de atribuição fica selado dentro do registo do passe na base de dados. Edições ou atualizações subsequentes do passe nunca substituem a telemetria original de aquisição.

Configurar regras UTM através do Painel e da API

Através do Painel:

  1. 1
    Abra o seu modelo no Painel.
  2. 2
    Aceda a Funcionalidades -> UTM e Acompanhamento (/templates/:templateId/utm-tracking).
  3. 3
    Ative Ativar Acompanhamento de Parâmetros UTM.
  4. 4
    Defina parâmetros predefinidos para ligações padrão do modelo ou estabeleça chaves de atribuição obrigatórias para campanhas de parceiros.

Através da API (UTM Tracking API):

HTTP
PUT /api/v1/templates/{templateId}/utm-tracking HTTP/1.1
Host: api.passinstance.com
X-API-Key: <API_KEY>
Content-Type: application/json

{
  "enabled": true,
  "defaultSource": "direct",
  "defaultMedium": "web",
  "allowedTags": ["store_location", "promoter_id", "partner_code"],
  "trackDeviceTelemetry": true
}

Exportar atribuição UTM nas exportações de passes

Todos os parâmetros de atribuição captados são incluídos ao exportar coortes de passes para CSV ou ao consultar passes através da API REST (POST /passes/export e GET /api/v1/passes):

Colunas de telemetria exportadas:

  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content
  • utm_id
  • tag
  • attribution_model (FIRST_TOUCH)
  • attribution_captured_at (carimbo temporal ISO)
  • attribution_captured_from (PASSFLOW, SMART_LINK ou DIRECT_API)
  • attribution_landing_url
  • attribution_referrer

Exemplo de linha de exportação CSV:

CSV
id,serialNumber,externalId,status,utm_source,utm_medium,utm_campaign,tag,capturedAt
pass_01j9x1,PI-8821,CUST-901,ACTIVE,instagram,story,spring_launch_2026,influencer_maya,2026-03-15T14:22:10Z

Exemplos de construção de URLs para campanhas de marketing

Ao distribuir as suas ligações públicas, anexe parâmetros UTM utilizando a sintaxe padrão de parâmetros de consulta URL:

1. Código QR em expositor de mesa em loja:

TEXT
https://app.passinstance.com/f/coffee-club?utm_source=in_store&utm_medium=qr_code&utm_campaign=table_tents&tag=table_12

2. Anúncio Swipe-Up em Instagram Story:

TEXT
https://app.passinstance.com/f/coffee-club?utm_source=instagram&utm_medium=story_ad&utm_campaign=summer_promo_2026&utm_content=video_b

3. Rodapé de newsletter por e-mail:

TEXT
https://app.passinstance.com/f/coffee-club?utm_source=newsletter&utm_medium=email&utm_campaign=weekly_digest_wk11

Documentação relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.