Tracciamento dei clic sui link HubSpot: scrivere i clic nella timeline del deal

Se il tuo team commerciale lavora in HubSpot ma il tracciamento delle campagne vive in uno strumento di link corti, hai due timeline che non si parlano mai. Il marketer vede i clic; l'AE vede le fasi del deal. Nessuno vede il collegamento tra loro. Questa guida spiega come collegare Elido a HubSpot in modo che ogni clic su un link corto appaia nella timeline del contatto, i valori UTM arrivino nelle proprietà del CRM e le soglie di volume di clic possano far avanzare le fasi del deal.

Il meccanismo si basa su tre API HubSpot: la Timeline Events API per i record per ogni clic, la Contacts API per la scrittura delle proprietà e la Deals API per l'avanzamento delle fasi. L'autenticazione avviene tramite OAuth 2.0 con gli scope documentati in HubSpot OAuth scopes. HubSpot è attivo su Elido da aprile 2026, e il connettore gestisce la rotazione dei token di aggiornamento, i tentativi ripetuti e le scritture idempotenti nella timeline. Il resto è configurazione.

TL;DR

• Connessione tramite OAuth con tre scope: crm.objects.contacts.write, crm.objects.deals.read, timeline. Senza tutti e tre, HubSpot rifiuterà l'installazione.
• Elido pubblica ogni clic come Timeline Event con l'eventTemplateId provisionato all'installazione. I parametri UTM arrivano nel payload dell'evento e in tre proprietà di contatto personalizzate (elido_last_utm_source, _campaign, _medium).
• Le proprietà analitiche HubSpot come original_source_drill_down_1 sono solo di primo contatto. Usa proprietà personalizzate per l'attribuzione continuativa, non quelle integrate.
• Le regole di soglia di clic (es. "50 clic sul link di proposta fanno avanzare il deal a Engaged") vengono eseguite lato server in api-core. Configurale nelle Impostazioni del Workspace, non nei workflow HubSpot.
• Gli errori 401 sull'integrazione significano quasi sempre una catena di token di aggiornamento interrotta. Reinstalla dalla tessera del marketplace - non incollare token manualmente.

Come i clic arrivano nella timeline del contatto HubSpot

Un clic su un link corto in Elido segue un percorso in cinque fasi prima di apparire in HubSpot.

1. Il gestore di reindirizzamento all'edge (services/edge-redirect) legge il clic, determina la destinazione e scrive l'evento di clic in Redpanda. Questo è il hot-path, con p50 di circa 5 ms; HubSpot non è mai sul percorso della richiesta.
2. click-ingester legge il topic Redpanda e persiste in ClickHouse per gli analytics.
3. Il connettore HubSpot all'interno di api-core (in precedenza services/hubspot-connector prima della consolidazione) si iscrive a un topic fan-out. Per ogni clic su un workspace con HubSpot connesso, costruisce un payload di Timeline Event.
4. Il connettore risolve il contatto: se il clic porta un contact_id Elido (impostato tramite il parametro ?eid= o tramite una condivisione del dashboard con sessione attiva), questo viene mappato direttamente a un contatto HubSpot. Se è presente solo un fbclid o gclid, Elido tenta una corrispondenza via email sull'ultimo invio di modulo negli ultimi 14 giorni; altrimenti l'evento viene tenuto in una coda in attesa per 72 ore.
5. Il connettore effettua un POST a /crm/v3/timeline/events con l'ID del template di evento provisionato all'installazione. La scrittura nella timeline è idempotente su eventId, quindi i tentativi ripetuti sono sicuri.

Il payload dell'evento include tokens per i campi strutturati che HubSpot mostra (slug del link, URL di destinazione, nome della campagna, paese, dispositivo) e extraData per tutto il resto (set UTM completo, referrer, frammenti di user-agent, timestamp grezzo). L'interfaccia timeline di HubSpot renderizza i token; gli extraData sono disponibili tramite API ma nascosti nella vista predefinita.

La tabella di mapping UTM-proprietà

Questa è la parte che mette in difficoltà i team che cercano di fare il collegamento da soli. HubSpot ha due classi di proprietà "sorgente" che si comportano diversamente.

Proprietà analitiche (solo primo contatto). original_source_drill_down_1, hs_analytics_first_url, hs_analytics_first_referrer e il resto della famiglia hs_analytics_* vengono impostate una sola volta, quando il contatto viene creato per la prima volta. Le scritture successive tramite la Contacts API vengono silenziosamente scartate. HubSpot non restituisce un errore, il valore semplicemente non cambia. Se ti sei mai chiesto perché il valore "ultima campagna" sembra bloccato al 2024, ecco il perché.

Proprietà personalizzate (lettura/scrittura). Qualsiasi cosa tu definisca autonomamente è liberamente modificabile. Elido ne provisiona tre alla prima connessione: elido_last_utm_source, elido_last_utm_campaign, elido_last_utm_medium. Ogni clic applica un PATCH a queste proprietà sul contatto risolto. Il rollup a livello di deal usa i valori più recenti tramite un workflow HubSpot che copia dal contatto principale.

La Figura 2 qui sotto riassume il mapping che Elido applica per impostazione predefinita. Puoi sovrascrivere qualsiasi riga in Impostazioni del Workspace, poi Integrazioni, HubSpot, Mapping dei campi. Per articoli che richiedono un approfondimento sull'igiene UTM, il tutorial UTM end-to-end copre le convenzioni di denominazione, e la guida ai template UTM spiega come applicarle al momento della creazione del link.

Un esempio reale

Un account B2B SaaS prenota un webinar. L'email di follow-up contiene un link corto Elido a un PDF di prezzi con UTM utm_source=webinar&utm_campaign=q2-pricing&utm_medium=email. Il destinatario clicca due volte nell'arco di due giorni. In HubSpot:

• Compaiono due nuovi eventi di timeline sul contatto, entrambi intitolati "Clic: PDF prezzi Q2 (s.elido.me/abc123)".
• elido_last_utm_source = webinar, elido_last_utm_campaign = q2-pricing, elido_last_utm_medium = email.
• Il original_source_drill_down_1 esistente del contatto (impostato lo scorso settembre quando ha scaricato un ebook) non cambia. Questo è il comportamento corretto del primo contatto, non un bug.
• La proprietà elido_recent_link_clicks del deal associato si incrementa di 2 tramite un workflow HubSpot che ascolta la proprietà del contatto.

L'AE che guarda il deal vede ora un contatore di clic in aumento prima di chiamare. Il marketer che gestisce il webinar può applicare un filtro di lista HubSpot su elido_last_utm_campaign = q2-pricing e inviarlo a una sequenza di re-engagement. Stessi dati, due prospettive.

Collegare le soglie di clic alle fasi del deal

La visibilità nella timeline è il livello base. Le regole di soglia sono dove l'integrazione dimostra il suo valore reale, perché convertono il segnale di clic in un'azione CRM senza che nessuno debba monitorare una dashboard.

La struttura di una regola:

trigger:
  link_tag: "sales-collateral" # all links tagged this way count
  contact_window: 30d # rolling
  click_threshold: 50
action:
  type: advance_deal_stage
  pipeline: "default"
  from_stage: "appointmentscheduled"
  to_stage: "qualifiedtobuy"
  guard:
    require_associated_contact: true
    deal_amount_min: 5000 # only deals worth advancing

Le regole vivono in api-core e vengono eseguite sullo stesso topic fan-out che alimenta le scritture nella timeline. Ogni clic ricalcola il conteggio progressivo per (contact_id, link_tag). Quando il conteggio supera la soglia e il contatto è associato a un deal in from_stage, il connettore applica un PATCH a /crm/v3/objects/deals/{dealId} con properties.dealstage = qualifiedtobuy.

Alcune note pratiche.

Usalo per asset ad alto intento. Pagine di prezzi, PDF di proposte, replay di demo registrate. L'avanzamento basato su soglie su un tag di link di prospezione a freddo contaminerà il tuo pipeline entro una settimana. Il modo più rapido per perdere la fiducia degli AE è far avanzare un deal perché qualcuno ha scansionato un link con curl.

Il blocco guard è importante. Senza require_associated_contact, i clic anonimi (qualcuno che invia il link a un amico) possono attivare la regola. Senza deal_amount_min, farai avanzare deal di prova da 400 € in fasi riservate alle opportunità enterprise.

Le regole inverse non sono simmetriche. Elido non retrocede automaticamente le fasi per inattività, perché i report HubSpot trattano le inversioni di fase come sospette. Se vuoi gestire i deal inattivi, costruisci un workflow HubSpot su hs_lastmodifieddate, non come regola Elido.

Per i meccanismi di inoltro delle conversioni, la guida all'inoltro delle conversioni documenta lo schema degli eventi, la politica di retry e la coda di lettere morte. La pagina delle funzionalità di tracciamento delle conversioni mostra lo stesso flusso per Meta CAPI, GA4 e Mixpanel; HubSpot è una delle tante destinazioni.

Scegliere tra regole basate su tag e su link

Hai due modi per definire l'ambito di una regola di soglia. Le regole basate su tag coprono un insieme di link che condividono un tag (es. tutti e 12 i link della tua sequenza di nurturing Q2 contano verso la stessa soglia). Le regole basate su link si limitano a un singolo link corto.

Usa le regole basate su tag quando il percorso del prospect attraversa più punti di contatto (questo è il caso della maggior parte del B2B). Usa quelle basate su link quando l'asset stesso è il segnale - un singolo link di proposta dove i clic dal terzo in poi indicano che il deal è reale. Entrambi i tipi di regole coesistono; un account engineer ha recentemente configurato un workspace con 8 regole basate su tag e 14 basate su link in esecuzione in parallelo senza conflitti.

La rotazione dei token di aggiornamento e il 401 che stai per ricevere

HubSpot OAuth utilizza token di aggiornamento rotativi. Ogni chiamata a /oauth/v1/token con grant_type=refresh_token restituisce un nuovo token di aggiornamento e invalida il precedente. Questo è ottimo per la sicurezza e pessimo per chiunque tenti di gestire i token manualmente.

Il connettore di Elido gestisce la rotazione correttamente. Il flusso:

1. Il token di accesso scade ogni 30 minuti (valore predefinito di HubSpot; il valore expires_in nella risposta del token lo conferma).
2. Circa 90 secondi prima della scadenza, il connettore chiama l'endpoint di aggiornamento con il token di aggiornamento corrente.
3. HubSpot restituisce un nuovo access_token + nuovo refresh_token + nuovo expires_in.
4. Elido li memorizza entrambi atomicamente nella tabella dei token. Il vecchio token di aggiornamento è ora invalidato.

Le situazioni in cui questo fallisce:

Ripristini del database. Se ripristini un backup precedente all'ultimo aggiornamento, il token di aggiornamento memorizzato è già invalidato a monte. La prima chiamata di aggiornamento restituisce un 401 con BAD_REFRESH_TOKEN. Sintomo: tutte le chiamate API HubSpot da Elido falliscono fino alla reinstallazione.

Copie di token tra ambienti. Uno sviluppatore copia i token HubSpot di un workspace da staging a locale. Entrambi gli ambienti tentano ora di aggiornare lo stesso token. Quello che viene eseguito per primo vince; l'altro fallisce al prossimo tentativo.

Modifiche manuali alla riga del token. Allettante durante il debug, mai una buona idea. La colonna token_version viene incrementata atomicamente con l'aggiornamento; le modifiche manuali interrompono il controllo di concorrenza ottimistica e il prossimo aggiornamento fallisce.

Lunghi periodi di inattività. HubSpot non documenta una scadenza rigida per i token di aggiornamento, ma in pratica i token non utilizzati per 6 o più mesi a volte restituiscono 401. Se hai un workspace inattivo dall'estate scorsa, aspettati di dover reinstallare.

La soluzione in tutti e quattro i casi è la stessa: apri la tessera del marketplace HubSpot dalle Impostazioni del Workspace, clicca su Reinstalla, accetta gli scope. HubSpot emette un nuovo codice di autorizzazione, Elido lo scambia con una nuova coppia di token e l'integrazione riprende. Nessun dato viene perso; gli eventi di timeline in coda durante l'interruzione vengono svuotati entro un minuto. La documentazione OAuth di HubSpot descrive il flusso del codice di autorizzazione in modo più dettagliato.

E le integrazioni tramite incolla del token?

Alcuni vendor consentono di incollare un token di accesso Private App invece di eseguire OAuth. HubSpot lo supporta, e aggira completamente il problema della rotazione - i token Private App non scadono e non ruotano. Elido non usa questa strada per HubSpot perché le Private App sono legate a un singolo account HubSpot e non possono essere installate su più portali da un singolo workspace Elido. Se hai un solo portale HubSpot e vuoi saltare l'installazione dal marketplace, contattaci tramite /contact; il connettore supporta entrambe le modalità, non è semplicemente esposta nell'interfaccia predefinita.

Monitorare la catena di aggiornamento

Due segnali ti dicono se l'aggiornamento funziona correttamente.

Il contatore Prometheus hubspot_refresh_attempts_total{result="ok|error"} vive in api-core. Un tasso di errore sostenuto superiore all'1% su un workspace è il segnale di allarme precoce. La maggior parte dei workspace mostra zero errori per settimane. La guida all'osservabilità spiega come collegarlo agli avvisi.

La pagina Integrazioni nelle Impostazioni del Workspace mostra il timestamp dell'ultimo aggiornamento riuscito per integrazione. Se HubSpot mostra "Ultimo aggiornamento: 6 giorni fa" mentre tutto il resto mostra pochi minuti, quello è il workspace da esaminare per primo.

Mettere tutto insieme

Una sequenza di implementazione ragionevole per un team che adotta l'integrazione:

1. Installa da /integrations, accetta i tre scope. Attendi 60 secondi per consentire a HubSpot di provisioning il template dell'evento di timeline.
2. Conferma il primo clic. Inviati un link corto Elido con ?eid=<il_tuo_hubspot_contact_id>, cliccaci da un dispositivo diverso, aggiorna la tua pagina di contatto HubSpot. L'evento di timeline dovrebbe apparire entro 30 secondi.
3. Aggiungi le tre proprietà personalizzate Elido alla tua vista contatto. Impostazioni del Workspace, poi Contatti, poi Personalizza barra laterale. Qui marketing e vendite vedono finalmente gli stessi valori UTM.
4. Aspetta due settimane prima di configurare le regole di soglia. Hai bisogno di dati di clic reali per sapere cosa significa "alta intenzione" per il tuo mix di asset; le soglie arbitrarie impostate il giorno dell'installazione sono di solito sbagliate. La pagina delle soluzioni per i marketer e il primer sugli analytics dei link aiutano a inquadrare cosa misurare.
5. Configura la tua prima regola su un singolo asset ad alto intento (pagina dei prezzi, link di proposta). Osserva per una settimana. Regola la soglia e il guard dell'importo del deal. Ripeti.

Il set completo di funzionalità è documentato nel catalogo delle integrazioni e il codice sorgente del connettore vive sotto il pacchetto hubspot in services/api-core. Se stai valutando la piattaforma più in generale, Elido pricing copre il tier in cui è inclusa l'integrazione HubSpot (Pro e superiori), e la panoramica del tracciamento delle conversioni lato server confronta HubSpot con le altre destinazioni CRM e analytics a cui Elido inoltra.

Una regola finale da tenere a mente: considera gli eventi di timeline come la fonte di verità per l'engagement; le proprietà personalizzate come la fonte di verità per l'ultima campagna; non fidarti mai della famiglia hs_analytics_* per niente al di là del primo contatto. Questo trittico copre il 95% di ciò che marketing e vendite discutono, e il modello dati di HubSpot inizia finalmente a sembrare onesto.