Відстеження кліків по посиланнях у HubSpot: запис кліків у таймлайн угоди

Якщо ваш відділ продажів живе в HubSpot, а відстеження кампаній ведеться в інструменті для коротких посилань, у вас два таймлайни, які ніколи не перетинаються. Маркетолог бачить кліки; AE бачить етапи угод. Ніхто не бачить зв'язку між ними. Цей посібник пояснює, як з'єднати Elido з HubSpot так, щоб кожен клік по короткому посиланню відображався в таймлайні контакту, UTM-значення потрапляли до властивостей CRM, а пороги кліків могли просувати етапи угод вперед.

Механізм спирається на три API HubSpot: Timeline Events API для записів про кожен клік, Contacts API для запису властивостей і Deals API для просування етапів. Автентифікація - OAuth 2.0 з дозволами з документації HubSpot OAuth scopes. HubSpot працює в Elido з квітня 2026, і конектор бере на себе ротацію токенів оновлення, повторні спроби та ідемпотентні записи в таймлайн. Решта - налаштування.

TL;DR

• Підключення через OAuth з трьома дозволами: crm.objects.contacts.write, crm.objects.deals.read, timeline. Без усіх трьох HubSpot відхилить встановлення.
• Elido публікує кожен клік як Timeline Event з eventTemplateId, створеним під час встановлення. UTM-параметри потрапляють до payload події і в три користувацькі властивості контакту (elido_last_utm_source, _campaign, _medium).
• Аналітичні властивості HubSpot на кшталт original_source_drill_down_1 - лише для першого дотику. Для поточної атрибуції використовуйте користувацькі властивості, а не вбудовані.
• Правила порогу кліків (наприклад, "50 кліків по посиланню на комерційну пропозицію переводить угоду на етап Engaged") виконуються на сервері в api-core. Налаштовуйте їх у параметрах робочого простору, а не у робочих процесах HubSpot.
• Помилки 401 в інтеграції майже завжди означають порушений ланцюжок токенів оновлення. Перевстановіть через плитку маркетплейсу - не вставляйте токени вручну.

Як кліки потрапляють у таймлайн контакту HubSpot

Клік по короткому посиланню в Elido проходить п'ять кроків, перш ніж з'явитися в HubSpot.

1. Обробник переадресації на edge (services/edge-redirect) зчитує клік, визначає призначення і записує подію кліку в Redpanda. Це гарячий шлях, p50 близько 5 мс; HubSpot ніколи не знаходиться на шляху запиту.
2. click-ingester читає топік Redpanda і зберігає дані в ClickHouse для аналітики.
3. Конектор HubSpot всередині api-core (до консолідації - services/hubspot-connector) підписується на fan-out топік. Для кожного кліку в робочому просторі з підключеним HubSpot він формує payload Timeline Event.
4. Конектор визначає контакт: якщо клік містить contact_id Elido (заданий через параметр ?eid= або спільний доступ до дашборду від авторизованого користувача), він безпосередньо маппиться на контакт HubSpot. Якщо є лише fbclid або gclid, Elido намагається зіставити email з останнього заповнення форми за 14 днів; інакше подія потрапляє до черги очікування на 72 години.
5. Конектор робить POST на /crm/v3/timeline/events з ID шаблону події, створеного під час встановлення. Запис у таймлайн ідемпотентний за eventId, тому повторні спроби безпечні.

Payload події містить tokens для структурованих полів, які відображає HubSpot (слаг посилання, URL призначення, назва кампанії, країна, пристрій), і extraData для решти (повний набір UTM, реферер, фрагменти user-agent, необроблена часова мітка). Інтерфейс таймлайну HubSpot рендерить токени; extraData доступні через API, але приховані в стандартному вигляді.

Маппінг UTM на властивості

Саме тут ламаються команди, що намагаються зробити це самостійно. У HubSpot є два класи властивостей "джерела", і вони поводяться по-різному.

Аналітичні властивості (лише перший дотик). original_source_drill_down_1, hs_analytics_first_url, hs_analytics_first_referrer та решта родини hs_analytics_* встановлюються один раз - при першому створенні контакту. Подальші записи через Contacts API мовчки відкидаються. HubSpot не повертає помилку - значення просто не змінюється. Якщо вам здавалося, що значення "останньої кампанії" застрягло в 2024 році, ось чому.

Користувацькі властивості (читання/запис). Усе, що ви визначаєте самостійно, можна вільно перезаписувати. Elido створює три властивості при першому підключенні: elido_last_utm_source, elido_last_utm_campaign, elido_last_utm_medium. Кожен клік надсилає PATCH з цими властивостями на визначений контакт. Згортання на рівні угоди використовує найактуальніші значення через робочий процес HubSpot, що копіює з основного контакту.

Рисунок 2 нижче узагальнює маппінг, який Elido застосовує за замовчуванням. Будь-який рядок можна замінити в параметрах робочого простору - Інтеграції - HubSpot - Маппінг полів. Для детального розгляду UTM-гігієни наскрізне керівництво з UTM охоплює угоди про іменування, а посібник з шаблонів UTM пояснює, як застосовувати їх при створенні посилань.

Реальний приклад

B2B SaaS-акаунт реєструється на вебінар. У листі з додатковими матеріалами - коротке посилання Elido на PDF з цінами з UTM utm_source=webinar&utm_campaign=q2-pricing&utm_medium=email. Отримувач клікає двічі за два дні. У HubSpot:

• На контакті з'являються дві нові події таймлайну із заголовком "Клік: PDF з цінами Q2 (s.elido.me/abc123)".
• elido_last_utm_source = webinar, elido_last_utm_campaign = q2-pricing, elido_last_utm_medium = email.
• Наявне original_source_drill_down_1 контакту (встановлене в вересні, коли він завантажив електронну книгу) не змінюється. Це коректна поведінка першого дотику, а не помилка.
• Властивість elido_recent_link_clicks пов'язаної угоди збільшується на 2 через робочий процес HubSpot, що відстежує властивості контакту.

AE, який дивиться на угоду, бачить зростаючий лічильник кліків до того, як зателефонує. Маркетолог, що веде вебінар, може застосувати фільтр списку HubSpot за elido_last_utm_campaign = q2-pricing і відправити його в послідовність повторного залучення. Одні дані, два кути зору.

Прив'язка порогів кліків до етапів угод

Видимість у таймлайні - це базовий рівень. Правила порогів - це місце, де інтеграція показує справжню цінність: вони перетворюють сигнал кліків на дію CRM без необхідності комусь стежити за дашбордом.

Структура правила:

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

Правила живуть в api-core і виконуються на тому ж fan-out топіку, що забезпечує записи в таймлайн. Кожен клік перераховує ковзний лічильник для (contact_id, link_tag). Коли лічильник перевищує поріг і контакт пов'язаний з угодою в from_stage, конектор надсилає PATCH на /crm/v3/objects/deals/{dealId} з properties.dealstage = qualifiedtobuy.

Кілька практичних зауважень.

Використовуйте тільки для активів із високим наміром. Сторінки з цінами, PDF з комерційними пропозиціями, записи демонстрацій. Просування етапів за порогом для тега посилань холодного охоплення забруднить воронку за тиждень. Найшвидший спосіб втратити довіру AE - просунути угоду через те, що хтось спарсив посилання за допомогою curl.

Блок guard має значення. Без require_associated_contact анонімні кліки (хтось переслав посилання другу) можуть активувати правило. Без deal_amount_min ви просуватимете пробні угоди за 5000 гривень в етапи, призначені для корпоративних клієнтів.

Зворотні правила не симетричні. Elido не знижує етапи автоматично при неактивності, тому що звіти HubSpot розглядають відкати етапів як підозрілі. Якщо потрібна обробка застиглих угод, створіть робочий процес HubSpot на основі hs_lastmodifieddate, а не правило Elido.

Деталі механізму пересилання конверсій - у посібнику з пересилання конверсій: схема подій, політика повторних спроб і черга "мертвих листів". Сторінка функцій відстеження конверсій показує той самий потік для Meta CAPI, GA4 і Mixpanel; HubSpot - один із кількох напрямків.

Вибір між правилами на основі тегів і на основі посилань

Є два способи обмежити область дії правила порогу. На основі тегів охоплює набір посилань з одним тегом (наприклад, усі 12 посилань у нурчурінговій послідовності Q2 рахуються до одного порогу). На основі посилання - лише одне коротке посилання.

Використовуйте на основі тегів, коли шлях потенційного клієнта охоплює кілька точок дотику (у B2B так майже завжди). Використовуйте на основі посилання, коли сам актив є сигналом - єдине посилання на комерційну пропозицію, де клік з третього разу означає, що угода реальна. Обидва типи правил співіснують; один account engineer нещодавно налаштував робочий простір з 8 правилами на основі тегів і 14 на основі посилань, що працюють паралельно без конфліктів.

Ротація токенів оновлення і помилка 401, яку ви ось-ось побачите

OAuth HubSpot використовує токени оновлення, що ротуються. Кожен виклик /oauth/v1/token з grant_type=refresh_token повертає новий токен оновлення і анулює попередній. Це добре для безпеки і жахливо для тих, хто намагається керувати токенами вручну.

Конектор Elido правильно обробляє ротацію. Потік:

1. Токен доступу закінчується кожні 30 хвилин (налаштування HubSpot за замовчуванням; значення expires_in у відповіді токена це підтверджує).
2. Приблизно за 90 секунд до закінчення конектор звертається до ендпоінту оновлення з поточним токеном оновлення.
3. HubSpot повертає новий access_token + новий refresh_token + нове expires_in.
4. Elido атомарно зберігає обидва в таблиці токенів. Старий токен оновлення тепер недійсний.

Ситуації, в яких це ламається:

Відновлення бази даних. Якщо відновити резервну копію старішу за останнє оновлення, збережений токен вже анульований на боці HubSpot. Перший виклик оновлення поверне 401 з BAD_REFRESH_TOKEN. Симптом: усі виклики API HubSpot з Elido падають до перевстановлення.

Копіювання токенів між середовищами. Розробник копіює токени HubSpot робочого простору зі стейджингу на локальну машину. Обидва середовища тепер намагаються оновитись за одним токеном. Хто встигне першим - перемагає; друге гине при наступній спробі.

Ручне редагування рядка токена. Спокусливо при налагодженні, ніколи не є доброю ідеєю. Стовпець token_version інкрементується атомарно при оновленні; ручне редагування порушує перевірку оптимістичного паралелізму, і наступне оновлення провалиться.

Тривалі простої. HubSpot не документує жорстке закінчення токенів оновлення, але на практиці токени, що не використовувалися 6 і більше місяців, іноді повертають 401. Якщо робочий простір простоював з минулого літа, чекайте на перевстановлення.

Рішення у всіх чотирьох випадках однакове: відкрийте плитку маркетплейсу HubSpot у параметрах робочого простору, натисніть "Перевстановити", прийміть дозволи. HubSpot видасть новий код авторизації, Elido обміняє його на нову пару токенів, і інтеграція відновиться. Дані не губляться; події таймлайну, що стояли в черзі під час збою, вивантажуються за хвилину. У документації HubSpot OAuth потік коду авторизації описаний детальніше.

А як щодо інтеграцій через вставку токенів?

Деякі постачальники дозволяють вставити токен доступу Private App замість OAuth. HubSpot це підтримує, і це повністю обходить проблему ротації - токени Private App не закінчуються і не ротуються. Elido не використовує цей шлях для HubSpot, тому що Private Apps прив'язані до одного акаунту HubSpot і не можуть встановлюватися на кілька порталів з одного робочого простору Elido. Якщо у вас тільки один портал HubSpot і хочеться пропустити встановлення через маркетплейс, напишіть через /contact; конектор підтримує обидва режими, просто другий не відображається в стандартному інтерфейсі.

Моніторинг ланцюжка оновлення

Два сигнали говорять про те, що оновлення працює нормально.

Лічильник Prometheus hubspot_refresh_attempts_total{result="ok|error"} знаходиться в api-core. Стійкий відсоток помилок вище 1% по робочому простору - це ранній попереджувальний сигнал. Більшість робочих просторів показують нуль помилок тижнями. Посібник з можливості спостереження пояснює, як підключити це до алертів.

Сторінка "Інтеграції" в параметрах робочого простору показує часову мітку останнього успішного оновлення для кожної інтеграції. Якщо HubSpot каже "Останнє оновлення: 6 днів тому", а у решти - хвилини, саме цей робочий простір потрібно перевірити першим.

Збираємо все разом

Розумна послідовність впровадження для команди, що приймає інтеграцію:

1. Встановіть з /integrations, прийміть три дозволи. Зачекайте 60 секунд, щоб HubSpot створив шаблон події таймлайну.
2. Підтвердіть перший клік. Відправте собі коротке посилання Elido з ?eid=<ваш_hubspot_contact_id>, клікніть по ньому з іншого пристрою, оновіть сторінку контакту в HubSpot. Подія таймлайну має з'явитися протягом 30 секунд.
3. Додайте три користувацькі властивості Elido до представлення контакту. Параметри робочого простору - Контакти - Налаштувати бічну панель. Тут маркетинг і продажі нарешті бачать однакові UTM-значення.
4. Зачекайте два тижні, перш ніж налаштовувати правила порогів. Потрібні реальні дані кліків, щоб зрозуміти, що означає "високий намір" для вашого набору активів; довільні пороги в день встановлення майже завжди хибні. Сторінка рішень для маркетологів і вступ до аналітики посилань допоможуть визначити, що вимірювати.
5. Налаштуйте перше правило для одного активу з високим наміром (сторінка з цінами, посилання на комерційну пропозицію). Спостерігайте тиждень. Скоригуйте поріг і обмеження за сумою угоди. Повторюйте.

Повний набір функцій задокументований у каталозі інтеграцій, а вихідний код конектора знаходиться в пакеті hubspot у services/api-core. Якщо ви оцінюєте платформу загалом, Elido pricing показує тариф, у який включена інтеграція з HubSpot (Pro і вище), а огляд серверного відстеження конверсій порівнює HubSpot з іншими CRM і аналітичними напрямками, куди Elido пересилає дані.

Фінальне практичне правило: вважайте події таймлайну джерелом правди про активність; користувацькі властивості - джерелом правди про останню кампанію; ніколи не довіряйте родині hs_analytics_* ні для чого, крім першого дотику. Цей триплет закриває 95% того, через що сперечаються маркетинг і продажі, і модель даних HubSpot нарешті починає відчуватися чесною.