Tracking dei click sui link HubSpot: scrivere i click sulla timeline del deal

Se il tuo team vendite vive in HubSpot ma il tracking delle campagne vive in uno strumento di link brevi, hai due timeline che non si parlano mai. Il marketer vede i click; l'account executive vede lo stadio del deal. Nessuno vede la linea che li collega. Questa guida illustra come collegare Elido a HubSpot in modo che ogni click su un link breve compaia sulla timeline del contatto, i valori UTM finiscano nelle proprietà CRM, e le soglie di volume dei click possano spingere in avanti gli stadi dei deal. Per lo stesso collegamento con un CRM diverso, il tracking dei link Salesforce copre il percorso basato su platform event.

L'impianto si appoggia a tre API HubSpot: la Timeline Events API per i record per singolo click, la Contacts API per le scritture di proprietà, e la Deals API per l'avanzamento di stadio. L'autenticazione è OAuth 2.0 con gli scope documentati in HubSpot OAuth scopes. Il connettore HubSpot è attivo per l'installazione OAuth, la rotazione dei refresh token e un'azione workflow Shorten. Il flusso timeline per singolo click è integrato nel connettore ma attende lo stream di eventi per singolo click di Elido, che è sulla roadmap, quindi considera il passaggio da click a timeline come in arrivo piuttosto che disponibile oggi. Il resto è configurazione.

In breve

• Collegati via OAuth con cinque scope: oauth, crm.objects.contacts.read, crm.objects.contacts.write, timeline, automation. Con meno di questi HubSpot rifiuterà l'installazione.
• Elido pubblica ogni click come un Timeline Event con eventTemplateId fornito al momento dell'installazione. I parametri UTM finiscono sul payload dell'evento e su tre proprietà di contatto personalizzate (elido_last_utm_source, _campaign, _medium).
• Le proprietà analytics di HubSpot come original_source_drill_down_1 sono solo first-touch. Usa proprietà personalizzate per l'attribuzione continua, non quelle integrate.
• Le regole a soglia di click (es. "50 click sul link di proposta fa avanzare il deal a Engaged") girano lato server in api-core. Impostale nelle Impostazioni Workspace, non nei workflow HubSpot.
• Gli errori 401 sull'integrazione quasi sempre significano una catena di refresh token rotta. Reinstalla dalla tile del marketplace, non incollare i token a mano.

Come i click raggiungono la timeline del contatto HubSpot

Un click su un link breve in Elido segue un percorso in cinque passaggi prima di comparire in HubSpot.

1. Il gestore del redirect all'edge (services/edge-redirect) legge il click, decide la destinazione, e scrive l'evento di click su Redpanda. Questo è l'hot path, p50 intorno ai 5ms; HubSpot non è mai sul percorso della richiesta.
2. click-ingester legge il topic Redpanda e persiste su ClickHouse per l'analytics.
3. Il connettore HubSpot, un servizio separato, si iscrive a un topic di fan-out. Per ogni click su un workspace con HubSpot collegato, costruisce un payload Timeline Event.
4. Il connettore risolve il contatto tramite email. Cerca un indirizzo nei metadati email del link, in utm_content, o in un parametro email= sull'URL di destinazione, poi cerca nei contatti HubSpot una corrispondenza esatta. Nessuna email o nessun contatto corrispondente significa nessuna scrittura timeline per quel click.
5. Il connettore invia una POST a /crm/v3/timeline/events con l'ID del template evento fornito all'installazione. La scrittura timeline è idempotente su eventId, quindi i retry sono sicuri.

Il payload dell'evento porta cinque tokens che l'interfaccia timeline di HubSpot renderizza: l'URL breve, l'URL di destinazione, la campagna UTM, la source UTM, e il timestamp del click.

La mappa da UTM a proprietà

Questa è la parte che complica la vita ai team che provano a collegarla da soli. HubSpot ha due classi di proprietà "source" e si comportano in modo diverso.

Proprietà analytics (solo first-touch). 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 ignorate silenziosamente. HubSpot non restituisce un errore, il valore semplicemente non cambia. Se ti sei mai chiesto perché il tuo valore "ultima campagna" sembra congelato al 2024, è per questo.

Proprietà personalizzate (lettura/scrittura). Qualsiasi cosa tu definisca da solo è liberamente scrivibile. Elido ne fornisce tre alla prima connessione: elido_last_utm_source, elido_last_utm_campaign, elido_last_utm_medium. Ogni click esegue un PATCH di queste 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 la mappatura che Elido applica per impostazione predefinita. Puoi sovrascrivere qualsiasi riga in Impostazioni Workspace, poi Integrazioni, HubSpot, Mappatura Campi. Per approfondire l'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 SaaS B2B prenota un webinar. L'email di follow-up contiene un link breve Elido verso un PDF di prezzi con UTM utm_source=webinar&utm_campaign=q2-pricing&utm_medium=email. Il destinatario clicca due volte in due giorni. In HubSpot:

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

L'account executive che guarda il deal vede ora un contatore di click salire prima ancora di chiamare. Il marketer che gestisce il webinar può estrarre un filtro lista HubSpot su elido_last_utm_campaign = q2-pricing e inviarlo a una sequenza di re-engagement. Stessi dati, due viste.

Collegare le soglie di click agli stadi del deal

La visibilità sulla timeline è la base. Le regole a soglia sono dove l'integrazione dimostra il suo valore, perché convertono il segnale di click in un'azione CRM senza che nessuno guardi una dashboard.

La forma di una regola:

trigger:
  link_tag: "sales-collateral" # tutti i link taggati così contano
  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 # solo deal che vale la pena far avanzare

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

Alcune note pratiche.

Usala per asset ad alta intenzione. Pagine di prezzi, PDF di proposte, replay di demo registrate. L'avanzamento guidato da soglia su un tag di link per outreach a freddo inquinerà la tua pipeline entro una settimana. Il modo più rapido per perdere la fiducia degli AE è far avanzare un deal perché qualcuno ha raschiato un link con curl.

Il blocco guard conta. Senza require_associated_contact, i click anonimi (qualcuno che inoltra il link a un amico) possono attivare la regola. Senza deal_amount_min, farai avanzare deal di prova da 400 dollari verso stadi riservati a trattative enterprise.

Le regole inverse non sono simmetriche. Elido non retrocede automaticamente gli stadi per inattività, perché il reporting di HubSpot tratta le retrocessioni di stadio come sospette. Se vuoi gestire i deal fermi, costruiscilo come workflow HubSpot su hs_lastmodifieddate, non come regola Elido.

Per i meccanismi di conversion-forwarding sotto il cofano, la guida al conversion-forwarding documenta lo schema dell'evento, la politica di retry, e la coda dead-letter. La pagina della funzionalità conversion tracking mostra lo stesso flusso per Meta CAPI, GA4 e Mixpanel; HubSpot è una destinazione tra le tante.

Scegliere tra regole basate su tag o su link

Hai due modi per delimitare una regola a soglia. Basata su tag copre un insieme di link che condividono un tag (ad esempio tutti i 12 link della tua sequenza nurture del secondo trimestre contano verso la stessa soglia). Basata su link si limita a un singolo link breve.

Usa le regole basate su tag quando il percorso del prospect attraversa più touchpoint (è 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 click dal terzo in poi significano che il deal è reale. Entrambi i tipi di regola coesistono; un account engineer di recente ha configurato un workspace con 8 regole basate su tag e 14 basate su link in esecuzione parallela senza conflitti.

Rotazione dei refresh token e il 401 che stai per vedere

HubSpot OAuth usa refresh token rotanti. Ogni chiamata a /oauth/v1/token con grant_type=refresh_token restituisce un nuovo refresh token e invalida quello precedente. Questo è ottimo per la sicurezza e terribile per chiunque provi a gestire i token a mano.

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

1. L'access token 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 refresh con il refresh token corrente.
3. HubSpot restituisce un nuovo access_token + nuovo refresh_token + nuovo expires_in.
4. Elido memorizza entrambi atomicamente nella tabella dei token. Il vecchio refresh token ora è morto.

I punti dove questo si rompe:

Ripristini del database. Se ripristini un backup più vecchio dell'ultimo refresh, il refresh token memorizzato è già stato invalidato a monte. La prima chiamata di refresh restituisce un 401 con BAD_REFRESH_TOKEN. Sintomi: ogni chiamata API HubSpot da Elido fallisce finché non reinstalli.

Copie di token tra ambienti. Uno sviluppatore copia i token HubSpot di un workspace da staging a locale. Entrambi gli ambienti ora provano a fare refresh contro lo stesso token. Chi esegue per primo vince; l'altro muore al tentativo successivo.

Modifiche manuali alla riga del token. Tentante durante il debug, mai una buona idea. La colonna token_version viene incrementata atomicamente con il refresh; le modifiche manuali rompono il controllo di concorrenza ottimistica e il refresh successivo fallisce.

Lunghi periodi di inattività. HubSpot non documenta una scadenza rigida sui refresh token, ma in pratica i token inutilizzati per 6+ 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 tile del marketplace HubSpot dalle Impostazioni Workspace, clicca Reinstalla, accetta gli scope. HubSpot emette un nuovo codice di autorizzazione, Elido lo scambia per una nuova coppia di token, e l'integrazione riprende. Nessun dato viene perso; gli eventi timeline in coda durante l'interruzione si svuotano entro un minuto. La documentazione OAuth di HubSpot descrive il flusso del codice di autorizzazione più in dettaglio, e le regole di rotazione sono collegate dalla sezione sui refresh token.

E le integrazioni con incolla-token?

Alcuni fornitori ti lasciano incollare un token di accesso Private App invece di fare OAuth. HubSpot lo supporta, e aggira del tutto il problema della rotazione - i token delle Private App non scadono e non ruotano. Elido non usa questo percorso per HubSpot perché le Private App sono legate a un singolo account HubSpot e non possono installarsi su più portali da un unico workspace Elido. Se hai un solo portale HubSpot e vuoi saltare l'installazione dal marketplace, contattaci via /contact; il connettore supporta entrambe le modalità, semplicemente non è esposta nell'interfaccia predefinita.

Monitorare la catena di refresh

Due segnali ti dicono se il refresh è sano.

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

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

Mettere tutto insieme

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

1. Installa da /integrations, accetta i cinque scope. Concedi 60 secondi affinché HubSpot fornisca il template dell'evento timeline.
2. Conferma il primo click. Inviati un link breve Elido la cui destinazione porta ?email=<tua_email_contatto_hubspot>, cliccalo da un dispositivo diverso, aggiorna la tua pagina contatto HubSpot. L'evento timeline dovrebbe comparire entro 30 secondi.
3. Aggiungi le tre proprietà personalizzate Elido alla tua vista contatto. Impostazioni Workspace, poi Contatti, poi Personalizza Sidebar. È qui che marketing e vendite vedono finalmente gli stessi valori UTM.
4. Aspetta due settimane prima di configurare le regole a soglia. Hai bisogno di dati di click reali per sapere come appare "alta intenzione" per il tuo mix di asset; le soglie arbitrarie impostate il giorno dell'installazione di solito sono sbagliate. La pagina della soluzione per marketer e il primer sull'analytics dei link aiutano a definire cosa misurare.
5. Configura la tua prima regola su un singolo asset ad alta intenzione (pagina prezzi, link di proposta). Osservala per una settimana. Perfeziona la soglia e la guard sull'importo del deal. Ripeti.

Il set completo di funzionalità è documentato nel catalogo integrazioni e il codice sorgente del connettore vive in services/hubspot-connector. Se stai valutando la piattaforma più ampia, i prezzi di Elido coprono il livello in cui l'integrazione HubSpot è inclusa (Pro e superiori), e la panoramica del conversion tracking lato server confronta HubSpot con le altre destinazioni CRM e analytics verso cui Elido inoltra.

Una regola pratica finale. Tratta gli eventi timeline come la fonte di verità per l'engagement; tratta le proprietà personalizzate come la fonte di verità per l'ultima campagna; non fidarti mai della famiglia hs_analytics_* per nulla oltre il first-touch. Questa tripletta copre il 95% di ciò su cui litigano marketing e vendite, e il modello dati di HubSpot finalmente inizia a sembrare onesto.