Skip to content
Guida del Centro assistenza · Distribuzione pass
4 min di letturaVerificato 2026-11-16

Parametri di tracciamento UTM

Monitora campagne di marketing, origini degli annunci e funnel di conversione sui link di distribuzione dei pass e su PassFlow con attribuzione al primo tocco.

In questa guida

Panoramica su attribuzione marketing e tracciamento campagne

Quando distribuisci pass digitali tramite inserzioni sui social media, collaborazioni con influencer, newsletter e-mail, espositori QR in negozio e reti di affiliazione, misurare il ROI di ciascun canale è fondamentale. Passinstance include un sistema nativo di Tracciamento dei parametri UTM (UTM Attribution Engine e UTM Tracking API su /templates/:templateId/utm-tracking) per acquisire le sorgenti di traffico, monitorare le conversioni di iscrizione ai pass e registrare l'attribuzione marketing first-touch direttamente su ogni record di pass emesso.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
PIPELINE DI ATTRIBUZIONE UTM E TELEMETRIA
FASE 01 TOUCHPOINT CAMPAGNA MARKETING
Il cliente fa clic su un link o scansiona un codice QR con tag UTM: https://app.passinstance.com/f/vip-club?utm_source=instagram&utm_medium=story...
FASE 02 MOTORE DI ACQUISIZIONE E ATTRIBUZIONE UTM
Acquisisce i tag query: utm_source, utm_medium, utm_campaign, utm_term
Registra l'header HTTP Referer e il landingUrl iniziale
Applica l'attribuzione First-Touch (ATTRIBUTION_MODEL = 'FIRST_TOUCH')
FASE 03 PERSISTENZA ATTRIBUZIONE PASS (DATABASE)
Salvata in modo permanente nel campo JSON Pass.attribution:
utm_source: "instagram"
utm_medium: "story"
utm_campaign: "summer_promo_2026"
tag: "influencer_sarah"
capturedAt: timestamp ISO | capturedFrom: "PASSFLOW"
FASE 04A ESPORTAZIONE CSV E ANALYTICS
Incluso in POST/passes/export
Filtra coorti per campagna marketing
FASE 04B WEBHOOK DI INTEGRAZIONE
Inoltrato in pass.created
Sincronizza con CRM / GA4

Tag e parametri UTM supportati

Passinstance standardizza la tassonomia UTM di Google Analytics riconosciuta nel settore insieme a tag personalizzati:

Chiave parametroScopoValore di esempioIdeale per
utm_sourceIdentifica la piattaforma di traffico o il referrerfacebook, instagram, newsletter, counter_qrDeterminare quale piattaforma ha generato il visitatore
utm_mediumIl canale marketing o il mezzo di distribuzionecpc, social, email, print_flyer, smsDistinguere annunci a pagamento da traffico organico o materiale stampato
utm_campaignNome specifico della campagna promozionalespring_launch_2026, black_friday_vip, store_openingRaggruppare i pass emessi nell'ambito di una specifica iniziativa
utm_termParola chiave a pagamento o segmento di audienceloyalty_rewards, coffee_club, fitness_subTracciare specifiche parole chiave degli annunci o varianti di audience
utm_contentSpecifica creatività pubblicitaria o variante CTAblue_button, story_ad_v2, table_stand_4Test A/B delle varianti di annuncio o dei diversi punti di esposizione
utm_idID campagna CRM o marketing automationcamp_01j8k9m2, ad_99214Correlare l'emissione del pass con gli ID di Google Ads o HubSpot
tagIdentificatore di categorizzazione liberostore_munich, partner_nike, staff_alexTag di tracciamento personalizzati specifici del tuo flusso operativo

Modello di attribuzione First-Touch (FIRST_TOUCH)

Passinstance implementa un Modello di attribuzione First-Touch (ATTRIBUTION_MODEL = 'FIRST_TOUCH', FIRST_TOUCH_SOURCE = 'UTM_FIRST_TOUCH'):

  1. 1
    Blocco nella sessione: quando un potenziale cliente atterra per la prima volta su un PassFlow pubblico (/f/:slug) o su uno Smart Link (/d/:slug) contenente parametri UTM, Passinstance memorizza il pacchetto di attribuzione nello storage di sessione.
  2. 2
    Invariante First-Touch: se il cliente naviga altrove, confronta piani o ritorna ore dopo tramite un link diretto, la sorgente della campagna originale che lo ha portato per prima al tuo brand viene preservata.
  3. 3
    Telemetria del pass immutabile: una volta generato il pass, l'oggetto di attribuzione viene sigillato nel record del pass sul database. Modifiche o aggiornamenti successivi del pass non sovrascriveranno mai la telemetria di acquisizione originale.

Configurazione delle regole UTM tramite Dashboard e API

Dalla Dashboard:

  1. 1
    Apri il modello nella dashboard.
  2. 2
    Vai su Funzionalità -> UTM e tracciamento (/templates/:templateId/utm-tracking).
  3. 3
    Attiva l'opzione Abilita tracciamento parametri UTM.
  4. 4
    Imposta i parametri predefiniti per i link standard del modello oppure definisci le chiavi di attribuzione richieste per le campagne partner.

Tramite 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
}

Esportazione dell'attribuzione UTM nei dati dei pass

Tutti i parametri di attribuzione acquisiti vengono inclusi quando esporti coorti di pass in CSV o interroghi i pass tramite REST API (POST /passes/export e GET /api/v1/passes):

Colonne di telemetria esportate:

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

Esempio di riga CSV esportata:

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

Esempi di composizione URL per campagne marketing

Quando distribuisci i tuoi link pubblici, aggiungi i parametri UTM usando la sintassi standard delle query string URL:

1. Codice QR su cavalierino da tavolo in negozio:

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

2. Inserzione Instagram Story con swipe-up:

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. Piè di pagina newsletter e-mail:

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

Documentazione correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.