Śledzenie kliknięć linków HubSpot: zapisywanie kliknięć w osi czasu dealu

Jeśli twój zespół sprzedaży żyje w HubSpot, a śledzenie kampanii odbywa się w narzędziu do skracania linków, masz dwie osie czasu, które nigdy ze sobą nie rozmawiają. Marketer widzi kliknięcia; AE widzi etapy dealu. Nikt nie widzi połączenia między nimi. Ten przewodnik przeprowadzi cię przez podłączenie Elido do HubSpot tak, żeby każde kliknięcie skróconego linku pojawiało się na osi czasu kontaktu, wartości UTM trafiały do właściwości CRM, a progi wolumenu kliknięć mogły przesuwać etapy dealów naprzód.

Podstawę stanowią trzy API HubSpot: Timeline Events API dla rekordów poszczególnych kliknięć, Contacts API do zapisywania właściwości oraz Deals API do przesuwania etapów. Uwierzytelnianie odbywa się przez OAuth 2.0 ze zakresami opisanymi w HubSpot OAuth scopes. HubSpot działa na Elido od kwietnia 2026, a konektor obsługuje rotację tokenów odświeżania, ponowne próby i idempotentne zapisy osi czasu. Reszta to konfiguracja.

TL;DR

• Połącz przez OAuth z trzema zakresami: crm.objects.contacts.write, crm.objects.deals.read, timeline. Bez wszystkich trzech HubSpot odrzuci instalację.
• Elido publikuje każde kliknięcie jako Timeline Event z eventTemplateId nadanym przy instalacji. Parametry UTM trafiają do payloadu zdarzenia i do trzech niestandardowych właściwości kontaktu (elido_last_utm_source, _campaign, _medium).
• Właściwości analityczne HubSpot takie jak original_source_drill_down_1 działają tylko dla pierwszego kontaktu. Do bieżącej atrybucji używaj niestandardowych właściwości, nie wbudowanych.
• Reguły progu kliknięć (np. "50 kliknięć na link propozycji przesuwa deal do etapu Zaangażowany") działają po stronie serwera w api-core. Konfiguruj je w Ustawieniach Workspace, a nie w workflowach HubSpot.
• Błędy 401 na integracji prawie zawsze oznaczają zerwany łańcuch tokenów odświeżania. Zainstaluj ponownie z kafelka marketplace - nie wklejaj tokenów ręcznie.

Jak kliknięcia trafiają do osi czasu kontaktu HubSpot

Kliknięcie skróconego linku w Elido przechodzi pięć kroków, zanim pojawi się w HubSpot.

1. Handler przekierowania na edge'u (services/edge-redirect) odczytuje kliknięcie, decyduje o miejscu docelowym i zapisuje zdarzenie kliknięcia do Redpandy. To hot-path, p50 około 5 ms; HubSpot nigdy nie jest na ścieżce żądania.
2. click-ingester odczytuje temat Redpandy i utrwala dane w ClickHouse na potrzeby analityki.
3. Konektor HubSpot wewnątrz api-core (dawniej services/hubspot-connector przed konsolidacją) subskrybuje temat fan-out. Dla każdego kliknięcia w workspace z podłączonym HubSpot konstruuje payload Timeline Event.
4. Konektor rozwiązuje kontakt: jeśli kliknięcie zawiera contact_id Elido (ustawiony przez parametr ?eid= lub przez udostępnienie dashboardu z zalogowanym użytkownikiem), jest on mapowany bezpośrednio na kontakt HubSpot. Jeśli obecne jest tylko fbclid lub gclid, Elido próbuje dopasowania e-mail do ostatniego wypełnienia formularza w ciągu 14 dni; w przeciwnym razie zdarzenie trafia do kolejki oczekujących na 72 godziny.
5. Konektor wysyła POST do /crm/v3/timeline/events z ID szablonu zdarzenia nadanym przy instalacji. Zapis osi czasu jest idempotentny względem eventId, więc ponowne próby są bezpieczne.

Payload zdarzenia zawiera tokens dla pól strukturalnych wyświetlanych przez HubSpot (slug linku, docelowy URL, nazwa kampanii, kraj, urządzenie) oraz extraData dla wszystkiego pozostałego (pełny zestaw UTM, referrer, fragmenty user-agenta, surowy timestamp). Interfejs osi czasu HubSpot renderuje tokeny; extraData są dostępne przez API, ale ukryte w domyślnym widoku.

Mapowanie UTM na właściwości

To jest właśnie ten fragment, na którym potykają się zespoły próbujące podłączyć to samodzielnie. HubSpot ma dwie klasy właściwości "źródłowych" i zachowują się inaczej.

Właściwości analityczne (tylko pierwszy kontakt). original_source_drill_down_1, hs_analytics_first_url, hs_analytics_first_referrer i reszta rodziny hs_analytics_* są ustawiane raz, gdy kontakt jest tworzony po raz pierwszy. Kolejne zapisy przez Contacts API są cicho odrzucane. HubSpot nie zwraca błędu - wartość po prostu się nie zmienia. Jeśli zastanawiałeś się kiedyś, dlaczego twoja wartość "ostatniej kampanii" wydaje się zamrożona w 2024 roku, to właśnie dlatego.

Właściwości niestandardowe (odczyt/zapis). Wszystko, co definiujesz samodzielnie, jest swobodnie zapisywalne. Elido tworzy trzy przy pierwszym połączeniu: elido_last_utm_source, elido_last_utm_campaign, elido_last_utm_medium. Każde kliknięcie wysyła PATCH na te właściwości rozwiązanego kontaktu. Rollup na poziomie dealu używa najnowszych wartości przez workflow HubSpot kopiujący z kontaktu głównego.

Rysunek 2 poniżej podsumowuje mapowanie, które Elido stosuje domyślnie. Możesz nadpisać dowolny wiersz w Ustawieniach Workspace, następnie Integracje, HubSpot, Mapowanie pól. Aby zagłębić się w higienę UTM, samouczek UTM end-to-end obejmuje konwencje nazewnictwa, a przewodnik po szablonach UTM wyjaśnia, jak je egzekwować przy tworzeniu linku.

Prawdziwy przykład

Konto B2B SaaS rezerwuje webinar. E-mail z follow-upem zawiera skrócony link Elido do PDF z cennikiem z UTM utm_source=webinar&utm_campaign=q2-pricing&utm_medium=email. Odbiorca klika dwa razy przez dwa dni. W HubSpot:

• Na kontakcie pojawiają się dwa nowe zdarzenia osi czasu, oba zatytułowane "Kliknięcie: PDF z cennikiem Q2 (s.elido.me/abc123)".
• elido_last_utm_source = webinar, elido_last_utm_campaign = q2-pricing, elido_last_utm_medium = email.
• Istniejąca właściwość original_source_drill_down_1 kontaktu (ustawiona w zeszłym wrześniu, gdy pobrał e-booka) nie zmienia się. To prawidłowe zachowanie pierwszego kontaktu, nie błąd.
• Właściwość elido_recent_link_clicks powiązanego dealu zwiększa się o 2 przez workflow HubSpot nasłuchujący właściwości kontaktu.

AE patrzący na deal widzi teraz rosnący licznik kliknięć przed telefonem. Marketer prowadzący webinar może zastosować filtr listy HubSpot na elido_last_utm_campaign = q2-pricing i wysłać go do sekwencji re-engagement. Te same dane, dwa spojrzenia.

Łączenie progów kliknięć z etapami dealu

Widoczność osi czasu to poziom podstawowy. Reguły progowe to miejsce, gdzie integracja pokazuje swoją prawdziwą wartość, bo przekształcają sygnał kliknięć w działanie CRM bez konieczności obserwowania dashboardu.

Struktura reguły:

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

Reguły żyją w api-core i działają na tym samym temacie fan-out, który zasila zapisy osi czasu. Każde kliknięcie przelicza licznik krocząco dla (contact_id, link_tag). Gdy licznik przekroczy próg, a kontakt jest powiązany z dealem w from_stage, konektor wysyła PATCH do /crm/v3/objects/deals/{dealId} z properties.dealstage = qualifiedtobuy.

Kilka praktycznych uwag.

Używaj dla zasobów o wysokiej intencji. Strony z cenami, PDF z propozycjami, powtórki nagranych demo. Przesuwanie etapów na podstawie progu dla tagu linku zimnego zasięgu zatruje twój pipeline w ciągu tygodnia. Najszybszy sposób na utratę zaufania AE to przesunięcie dealu, bo ktoś zescrapował link curlem.

Blok guard ma znaczenie. Bez require_associated_contact anonimowe kliknięcia (ktoś przesyłający link znajomemu) mogą wyzwolić regułę. Bez deal_amount_min będziesz przesuwał deale próbne za 400 USD do etapów zarezerwowanych dla enterprise.

Reguły odwrotne nie są symetryczne. Elido nie obniża automatycznie etapów przy braku aktywności, bo raporty HubSpot traktują cofanie etapów jako podejrzane. Jeśli chcesz obsługiwać nieaktywne deale, zbuduj to jako workflow HubSpot na hs_lastmodifieddate, a nie jako regułę Elido.

Szczegóły mechanizmu przekazywania konwersji są opisane w przewodniku po przekazywaniu konwersji - schemat zdarzeń, polityka ponownych prób i kolejka martwych listów. Strona funkcji śledzenia konwersji pokazuje ten sam przepływ dla Meta CAPI, GA4 i Mixpanel; HubSpot jest jednym z kilku miejsc docelowych.

Wybór między regułami opartymi na tagach a regułami opartymi na linkach

Masz dwa sposoby na określenie zakresu reguły progowej. Oparta na tagach obejmuje zestaw linków współdzielących tag (np. wszystkie 12 linków w sekwencji nurturingu Q2 liczy się do tego samego progu). Oparta na linku ogranicza się do jednego skróconego linku.

Używaj opartych na tagach, gdy ścieżka potencjalnego klienta przebiega przez wiele punktów kontaktu (to większość B2B). Używaj opartych na linku, gdy sam zasób jest sygnałem - pojedynczy link propozycji, gdzie kliknięcia od 3. w górę oznaczają, że deal jest prawdziwy. Oba typy reguł współistnieją; inżynier konta niedawno skonfigurował workspace z 8 regułami opartymi na tagach i 14 opartymi na linkach działającymi równolegle bez konfliktów.

Rotacja tokenów odświeżania i błąd 401, który zaraz zobaczysz

HubSpot OAuth używa rotujących tokenów odświeżania. Każde wywołanie /oauth/v1/token z grant_type=refresh_token zwraca nowy token odświeżania i unieważnia poprzedni. To dobre dla bezpieczeństwa i fatalne dla każdego, kto próbuje zarządzać tokenami ręcznie.

Konektor Elido obsługuje rotację poprawnie. Przepływ:

1. Token dostępu wygasa co 30 minut (domyślna wartość HubSpot; wartość expires_in w odpowiedzi tokenowej to potwierdza).
2. Około 90 sekund przed wygaśnięciem konektor wywołuje endpoint odświeżania z bieżącym tokenem odświeżania.
3. HubSpot zwraca nowy access_token + nowy refresh_token + nowe expires_in.
4. Elido zapisuje oba atomowo w tabeli tokenów. Stary token odświeżania jest teraz martwy.

Sytuacje, w których to się psuje:

Przywracanie bazy danych. Jeśli przywrócisz kopię zapasową starszą niż ostatnie odświeżenie, zapisany token odświeżania jest już unieważniony po stronie HubSpot. Pierwsze wywołanie odświeżania zwraca 401 z BAD_REFRESH_TOKEN. Objaw: wszystkie wywołania API HubSpot z Elido kończą się błędem, dopóki nie zainstalujesz ponownie.

Kopiowanie tokenów między środowiskami. Deweloper kopiuje tokeny HubSpot workspace'u ze stagingu na lokalne. Oba środowiska próbują teraz odświeżać ten sam token. To, które uruchomi się pierwsze, wygrywa; drugie ginie przy następnej próbie.

Ręczne edycje wiersza tokenu. Kuszące podczas debugowania, nigdy dobry pomysł. Kolumna token_version jest inkrementowana atomowo przy odświeżaniu; ręczne edycje łamią sprawdzanie optymistycznej współbieżności i następne odświeżanie się nie udaje.

Długie przestoje. HubSpot nie dokumentuje twardego wygaśnięcia tokenów odświeżania, ale w praktyce tokeny nieużywane przez 6 miesięcy i dłużej czasem zwracają 401. Jeśli masz workspace nieaktywny od zeszłego lata, spodziewaj się konieczności reinstalacji.

Rozwiązanie we wszystkich czterech przypadkach jest takie samo: otwórz kafelek marketplace HubSpot w Ustawieniach Workspace, kliknij Zainstaluj ponownie, zaakceptuj zakresy. HubSpot wystawia świeży kod autoryzacyjny, Elido wymienia go na nową parę tokenów i integracja wznawia działanie. Żadne dane nie są tracone; zdarzenia osi czasu zakolejkowane podczas przerwy są opróżniane w ciągu minuty. Dokumentacja HubSpot OAuth opisuje przepływ kodu autoryzacyjnego bardziej szczegółowo.

A co z integracjami przez wklejanie tokenów?

Niektórzy dostawcy pozwalają wkleić token dostępu Private App zamiast wykonywać OAuth. HubSpot to obsługuje i całkowicie omija problem rotacji - tokeny Private App nie wygasają i nie rotują. Elido nie używa tej ścieżki dla HubSpot, ponieważ Private Apps są przywiązane do pojedynczego konta HubSpot i nie mogą być instalowane na wielu portalach z jednego workspace'u Elido. Jeśli masz tylko jeden portal HubSpot i chcesz pominąć instalację z marketplace, skontaktuj się przez /contact; konektor obsługuje oba tryby, po prostu nie jest to widoczne w domyślnym UI.

Monitorowanie łańcucha odświeżania

Dwa sygnały mówią ci, czy odświeżanie jest zdrowe.

Licznik Prometheus hubspot_refresh_attempts_total{result="ok|error"} żyje w api-core. Utrzymujący się wskaźnik błędów powyżej 1% w workspace to wczesne ostrzeżenie. Większość workspace'ów pokazuje zero błędów przez tygodnie. Przewodnik po obserwowalności opisuje, jak podłączyć to do alertów.

Strona Integracje w Ustawieniach Workspace pokazuje timestamp ostatniego udanego odświeżenia dla każdej integracji. Jeśli HubSpot mówi "Ostatnio odświeżono: 6 dni temu", podczas gdy wszystko inne pokazuje minuty, to jest workspace, który należy sprawdzić w pierwszej kolejności.

Składanie całości

Rozsądna sekwencja wdrożenia dla zespołu adoptującego integrację:

1. Zainstaluj z /integrations, zaakceptuj trzy zakresy. Poczekaj 60 sekund, aż HubSpot zaprovisjonuje szablon zdarzenia osi czasu.
2. Potwierdź pierwsze kliknięcie. Wyślij sobie skrócony link Elido z ?eid=<twoje_hubspot_contact_id>, kliknij go z innego urządzenia, odśwież stronę kontaktu HubSpot. Zdarzenie osi czasu powinno pojawić się w ciągu 30 sekund.
3. Dodaj trzy niestandardowe właściwości Elido do widoku kontaktu. Ustawienia Workspace, następnie Kontakty, następnie Dostosuj pasek boczny. Tu marketing i sprzedaż wreszcie widzą te same wartości UTM.
4. Poczekaj dwa tygodnie przed konfigurowaniem reguł progowych. Potrzebujesz prawdziwych danych o kliknięciach, żeby wiedzieć, jak wygląda "wysoka intencja" dla twojego zestawu zasobów; arbitralne progi ustawione w dniu instalacji są zazwyczaj błędne. Strona rozwiązań dla marketerów i wstęp do analityki linków pomagają określić, co mierzyć.
5. Ustaw pierwszą regułę dla jednego zasobu o wysokiej intencji (strona z cenami, link propozycji). Obserwuj przez tydzień. Dostosuj próg i guard kwoty dealu. Powtarzaj.

Pełny zestaw funkcji jest udokumentowany w katalogu integracji, a kod źródłowy konektora znajduje się w pakiecie hubspot w services/api-core. Jeśli oceniasz szerszą platformę, Elido pricing pokazuje tier, w którym integracja z HubSpot jest zawarta (Pro i wyżej), a przegląd śledzenia konwersji po stronie serwera porównuje HubSpot z innymi miejscami docelowymi CRM i analityki, do których Elido przekazuje dane.

Końcowa zasada ogólna: traktuj zdarzenia osi czasu jako źródło prawdy dla zaangażowania; niestandardowe właściwości jako źródło prawdy dla najnowszej kampanii; nigdy nie ufaj rodzinie hs_analytics_* w niczym poza pierwszym kontaktem. Ten zestaw trzech zasad obejmuje 95% tego, o co marketing i sprzedaż się spierają, a model danych HubSpot zaczyna wreszcie wydawać się uczciwy.