Śledzenie kliknięć linków HubSpot: zapisuj kliknięcia na osi czasu transakcji

Jeśli Twój zespół sprzedaży żyje w HubSpot, a śledzenie kampanii żyje w narzędziu do krótkich linków, masz dwie osie czasu, które nigdy ze sobą nie rozmawiają. Marketer widzi kliknięcia; account executive widzi etap transakcji. Nikt nie widzi łącznika między nimi. Ten przewodnik pokazuje, jak podłączyć Elido do HubSpot, żeby każde kliknięcie krótkiego linku pojawiało się na osi czasu kontaktu, wartości UTM lądowały we właściwościach CRM, a progi liczby kliknięć mogły popychać etapy transakcji do przodu. Dla tej samej instalacji na innym CRM zobacz śledzenie linków Salesforce, które opisuje ścieżkę przez zdarzenia platformowe.

Instalacja opiera się na trzech API HubSpot: Timeline Events API do zapisów per kliknięcie, Contacts API do zapisów właściwości i Deals API do przesuwania etapów. Uwierzytelnianie to OAuth 2.0 z uprawnieniami opisanymi w dokumentacji uprawnień OAuth HubSpot. Konektor HubSpot działa na żywo dla instalacji OAuth, rotacji tokenów odświeżania i akcji workflow Shorten. Strumień osi czasu per kliknięcie jest wbudowany w konektor, ale czeka na strumień zdarzeń kliknięć Elido, który jest dopiero w planach, więc traktuj przejście od kliknięcia do osi czasu jako coś nadchodzącego, a nie dostępnego dziś. Reszta to konfiguracja.

W skrócie

• Połącz się przez OAuth z pięcioma uprawnieniami: oauth, crm.objects.contacts.read, crm.objects.contacts.write, timeline, automation. Mniej i HubSpot odrzuci instalację.
• Elido publikuje każde kliknięcie jako zdarzenie Timeline z eventTemplateId utworzonym przy instalacji. Parametry UTM lądują w payloadzie zdarzenia i w trzech niestandardowych właściwościach kontaktu (elido_last_utm_source, _campaign, _medium).
• Właściwości analityczne HubSpot, jak original_source_drill_down_1, są tylko dla pierwszego dotknięcia. Do bieżącej atrybucji używaj właściwości niestandardowych, nie wbudowanych.
• Reguły progowe kliknięć (np. "50 kliknięć na linku do oferty przesuwa transakcję do etapu Zaangażowany") działają po stronie serwera w api-core. Ustawiasz je w Ustawieniach workspace'u, nie w workflow HubSpot.
• Błędy 401 w integracji niemal zawsze oznaczają zerwany łańcuch tokena odświeżania. Zainstaluj ponownie z kafelka marketplace, nie wklejaj tokenów ręcznie.

Jak kliknięcia docierają na oś czasu kontaktu HubSpot

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

1. Handler przekierowania na brzegu sieci (services/edge-redirect) odczytuje kliknięcie, decyduje o celu podróży i zapisuje zdarzenie kliknięcia do Redpanda. To hot path, p50 około 5 ms; HubSpot nigdy nie jest na ścieżce żądania.
2. click-ingester odczytuje topic Redpanda i zapisuje do ClickHouse na potrzeby analityki.
3. Konektor HubSpot, osobny serwis, subskrybuje topic typu fan-out. Dla każdego kliknięcia w workspace'ie podłączonym do HubSpot buduje payload zdarzenia Timeline.
4. Konektor rozwiązuje kontakt po e-mailu. Szuka adresu w metadanych email linku, w utm_content albo w parametrze email= na docelowym adresie URL, a potem szuka w kontaktach HubSpot dokładnego dopasowania. Brak e-maila albo brak pasującego kontaktu oznacza brak zapisu na osi czasu dla tego kliknięcia.
5. Konektor wysyła POST do /crm/v3/timeline/events z identyfikatorem szablonu zdarzenia utworzonym przy instalacji. Zapis na osi czasu jest idempotentny po eventId, więc ponowienia są bezpieczne.

Payload zdarzenia niesie pięć tokens, które renderuje interfejs osi czasu HubSpot: krótki URL, docelowy URL, kampanię UTM, źródło UTM i znacznik czasu kliknięcia.

Mapa UTM na właściwości

To ta część, która gryzie zespoły próbujące podłączyć to samodzielnie. HubSpot ma dwie klasy właściwości "źródła" i zachowują się one inaczej.

Właściwości analityczne (tylko pierwsze dotknięcie). original_source_drill_down_1, hs_analytics_first_url, hs_analytics_first_referrer i reszta rodziny hs_analytics_* są ustawiane raz, przy pierwszym utworzeniu kontaktu. Kolejne zapisy przez Contacts API są po cichu odrzucane. HubSpot nie zwraca błędu, wartość po prostu się nie zmienia. Jeśli kiedykolwiek zastanawiałeś się, dlaczego Twoja wartość "ostatniej kampanii" wydaje się zamrożona od 2024 roku, to właśnie dlatego.

Właściwości niestandardowe (odczyt/zapis). Wszystko, co zdefiniujesz sam, jest swobodnie zapisywalne. Elido przy pierwszym połączeniu tworzy trzy: elido_last_utm_source, elido_last_utm_campaign, elido_last_utm_medium. Każde kliknięcie wykonuje PATCH na tych polach dla rozwiązanego kontaktu. Zbiorcze wartości na poziomie transakcji korzystają z najnowszych wartości przez workflow HubSpot, który kopiuje je z kontaktu podstawowego.

Rysunek 2 poniżej podsumowuje mapowanie, które Elido stosuje domyślnie. Każdy wiersz możesz nadpisać w Ustawieniach workspace'u, potem Integracje, HubSpot, Mapowanie pól. Dla postów, które potrzebują głębszego zanurzenia w higienę UTM, samouczek UTM od początku do końca opisuje konwencje nazewnictwa, a przewodnik po szablonach UTM wyjaśnia, jak je wymuszać już przy tworzeniu linku.

Prawdziwy przykład

Konto B2B SaaS rezerwuje miejsce na webinarze. E-mail przypominający zawiera krótki link Elido do PDF-a z cennikiem z UTM utm_source=webinar&utm_campaign=q2-pricing&utm_medium=email. Odbiorca klika dwukrotnie w ciągu dwóch dni. W HubSpot:

• Na koncie pojawiają się dwa nowe zdarzenia osi czasu, oba zatytułowane "Kliknięto: PDF cennika Q2 (s.elido.me/abc123)".
• elido_last_utm_source = webinar, elido_last_utm_campaign = q2-pricing, elido_last_utm_medium = email.
• Istniejąca wartość original_source_drill_down_1 kontaktu (ustawiona we wrześniu ubiegłego roku, gdy pobrał e-booka) się nie zmienia. To poprawne zachowanie pierwszego dotknięcia, nie błąd.
• Właściwość elido_recent_link_clicks powiązanej transakcji rośnie o 2 przez workflow HubSpot nasłuchujący właściwości kontaktu.

Account executive patrzący na transakcję widzi teraz rosnący licznik kliknięć, zanim zadzwoni. Marketer prowadzący webinar może wyciągnąć filtr listy HubSpot na elido_last_utm_campaign = q2-pricing i wysłać go do sekwencji re-engagement. Te same dane, dwa widoki.

Podłączanie progów kliknięć do etapów transakcji

Widoczność na osi czasu to minimum. Reguły progowe to miejsce, gdzie integracja naprawdę się opłaca, bo zamieniają sygnał kliknięć w akcję CRM bez nikogo patrzącego na dashboard.

Kształt reguły:

trigger:
  link_tag: "sales-collateral" # wszystkie linki z tym tagiem się liczą
  contact_window: 30d # kroczące
  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 # tylko transakcje warte przesuwania

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

Kilka praktycznych uwag.

Używaj tego dla zasobów o wysokiej intencji. Strony z cennikiem, PDF-y z ofertami, powtórki nagrań demo. Przesuwanie oparte na progu na tagu linku zimnego outreachu zaśmieci Twój pipeline w tydzień. Najszybszy sposób, by stracić zaufanie account executive, to przesunąć transakcję, bo ktoś zeskrobał link curl-em.

Blok guard ma znaczenie. Bez require_associated_contact anonimowe kliknięcia (ktoś przesyła link znajomemu) mogą wyzwolić regułę. Bez deal_amount_min przesuniesz transakcje próbne za 400 dolarów do etapów zarezerwowanych dla klientów enterprise.

Reguły odwrotne nie są symetryczne. Elido automatycznie nie cofa etapów przy braku aktywności, bo raportowanie HubSpot traktuje cofnięcia etapów jako podejrzane. Jeśli chcesz obsłużyć przestarzałe transakcje, zbuduj to jako workflow HubSpot na hs_lastmodifieddate, nie jako regułę Elido.

Mechanikę przekazywania konwersji pod maską opisuje przewodnik po przekazywaniu konwersji, zawierający schemat zdarzenia, politykę ponowień i kolejkę dead-letter. Strona funkcji śledzenia konwersji pokazuje ten sam przepływ dla Meta CAPI, GA4 i Mixpanel; HubSpot to jeden cel spośród kilku.

Wybór reguł opartych na tagach kontra na linkach

Masz dwa sposoby na zakres reguły progowej. Reguły oparte na tagach obejmują zestaw linków dzielących tag (np. wszystkie 12 linków w Twojej sekwencji nurtującej Q2 liczy się do tego samego progu). Reguły oparte na linku dotyczą pojedynczego krótkiego linku.

Używaj reguł opartych na tagach, gdy ścieżka prospekta przechodzi przez wiele punktów styku (to większość B2B). Używaj reguł opartych na linku, gdy sam zasób jest sygnałem - pojedynczy link do oferty, gdzie kliknięcia 3+ oznaczają, że transakcja jest realna. Oba typy reguł mogą współistnieć; inżynier ds. kont niedawno skonfigurował workspace z 8 regułami opartymi na tagach i 14 opartymi na linkach działającymi równolegle bez konfliktu.

Rotacja tokena odświeżania i 401, które 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 okropne 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ślnie w HubSpot; potwierdza to wartość expires_in w odpowiedzi tokena).
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 + nowy expires_in.
4. Elido zapisuje oba atomowo w tabeli tokenów. Stary token odświeżania jest teraz martwy.

Miejsca, gdzie to się psuje:

Przywrócenia bazy danych. Jeśli przywrócisz kopię zapasową starszą niż Twoje ostatnie odświeżenie, zapisany token odświeżania jest już unieważniony po stronie HubSpot. Pierwsze wywołanie odświeżenia zwraca 401 z BAD_REFRESH_TOKEN. Objawy: każde wywołanie API HubSpot z Elido zawodzi, dopóki nie zainstalujesz ponownie.

Kopiowanie tokenów między środowiskami. Deweloper kopiuje tokeny HubSpot workspace'u ze staging na lokalne. Oba środowiska próbują teraz odświeżać ten sam token. Które zdąży pierwsze, wygrywa; drugie umiera przy następnej próbie.

Ręczne edycje wiersza tokena. Kuszące podczas debugowania, nigdy nie jest dobrym pomysłem. Kolumna token_version jest zwiększana atomowo razem z odświeżeniem; ręczne edycje psują sprawdzenie optymistycznej współbieżności i następne odświeżenie zawodzi.

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

Naprawa we wszystkich czterech przypadkach jest taka sama: otwórz kafelek marketplace HubSpot z Ustawień workspace'u, kliknij Zainstaluj ponownie, zaakceptuj uprawnienia. HubSpot wydaje świeży kod autoryzacji, Elido wymienia go na nową parę tokenów, a integracja wraca do działania. Żadne dane nie giną; zdarzenia osi czasu zakolejkowane podczas przerwy spływają w ciągu minuty. Dokumentacja OAuth HubSpot opisuje przepływ kodu autoryzacji szczegółowo, a zasady rotacji są linkowane z sekcji o tokenie odświeżania.

A co z integracjami przez wklejenie tokena?

Niektórzy dostawcy pozwalają wkleić token dostępu aplikacji prywatnej zamiast robić OAuth. HubSpot to obsługuje i całkowicie omija problem rotacji - tokeny aplikacji prywatnej nie wygasają i nie rotują. Elido nie używa tej ścieżki dla HubSpot, bo aplikacje prywatne są związane z jednym kontem HubSpot i nie mogą instalować się w 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 wystawione w domyślnym interfejsie.

Monitorowanie łańcucha odświeżania

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

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

Strona Integracje w Ustawieniach workspace'u pokazuje znacznik czasu ostatniego udanego odświeżenia dla każdej integracji. Jeśli HubSpot pokazuje "Ostatnio odświeżone: 6 dni temu", podczas gdy wszystko inne pokazuje minuty, to workspace, na który warto spojrzeć jako pierwszy.

Składanie tego w całość

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

1. Zainstaluj z /integrations, zaakceptuj pięć uprawnień. Daj 60 sekund, żeby HubSpot utworzył szablon zdarzenia osi czasu.
2. Potwierdź pierwsze kliknięcie. Wyślij sobie krótki link Elido, którego cel podróży niesie ?email=<twój_email_kontaktu_hubspot>, kliknij go z innego urządzenia, odśwież stronę kontaktu w 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'u, potem Kontakty, potem Dostosuj pasek boczny. Tutaj marketing i sprzedaż w końcu 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; dowolne progi ustawione w dniu instalacji zwykle są błędne. Strona rozwiązania dla marketerów i podstawy analityki linków pomagają ustalić, co mierzyć.
5. Skonfiguruj pierwszą regułę na jednym zasobie o wysokiej intencji (strona cennika, link do oferty). Obserwuj przez tydzień. Dostrój próg i zabezpieczenie kwoty transakcji. Powtórz.

Pełny zestaw funkcji jest udokumentowany w katalogu integracji, a źródło konektora żyje w services/hubspot-connector. Jeśli oceniasz szerszą platformę, cennik Elido pokazuje plan, w którym integracja HubSpot jest zawarta (Pro i wyżej), a przegląd śledzenia konwersji po stronie serwera porównuje HubSpot z innymi celami CRM i analitycznymi, do których Elido przekazuje dane.

Jedna zasada na koniec. Traktuj zdarzenia osi czasu jako źródło prawdy dla zaangażowania; traktuj właściwości niestandardowe jako źródło prawdy dla najnowszej kampanii; nigdy nie ufaj rodzinie hs_analytics_* w niczym poza pierwszym dotknięciem. Ta trójka pokrywa 95% tego, o co spierają się marketing i sprzedaż, a model danych HubSpot w końcu zaczyna wyglądać uczciwie.