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

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

Основа тримається на трьох API HubSpot: Timeline Events API для записів кожного кліку, Contacts API для запису властивостей і Deals API для просування етапу. Авторизація - OAuth 2.0 зі скоупами, задокументованими в скоупах OAuth HubSpot. Конектор HubSpot реалізований для встановлення OAuth, ротації токена оновлення і дії робочого процесу Shorten. Потік таймлайну для кожного кліку вбудований у конектор, але очікує на потік клікових подій Elido, який в дорожній карті, тож сприймайте зв'язок клік-таймлайн як «скоро», а не «доступно сьогодні». Решта - це конфігурація.

Коротко

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

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

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

1. Обробник редиректу на межі мережі (services/edge-redirect) читає клік, визначає ціль і записує подію кліку в Redpanda. Це гарячий шлях, p50 близько 5 мс; HubSpot ніколи не перебуває на шляху запиту.
2. click-ingester читає топік Redpanda і зберігає дані в ClickHouse для аналітики.
3. Конектор HubSpot, окремий сервіс, підписується на fan-out-топік. Для кожного кліку в робочому просторі з підключеним HubSpot він будує payload Timeline Event.
4. Конектор визначає контакт за email. Він шукає адресу в метаданих email посилання, в utm_content чи в параметрі email= цільової URL-адреси, а потім шукає точний збіг серед контактів HubSpot. Відсутність email чи відповідного контакту означає, що для цього кліку запис у таймлайн не робиться.
5. Конектор надсилає POST на /crm/v3/timeline/events з ID шаблону події, створеним під час встановлення. Запис у таймлайн ідемпотентний за eventId, тож повторні спроби безпечні.

Payload події несе п'ять tokens, які рендерить інтерфейс таймлайну HubSpot: коротка URL-адреса, цільова URL-адреса, кампанія UTM, джерело UTM і мітка часу кліку.

Зіставлення 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 застосовує за замовчуванням. Ви можете перевизначити будь-який рядок у Workspace Settings, потім Integrations, HubSpot, Field Mapping. Для глибшого занурення в гігієну UTM наскрізний туторіал з UTM розглядає конвенції іменування, а гайд з UTM-шаблонів пояснює, як застосовувати їх у момент створення посилання.

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

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

• На контакті з'являються дві нові події таймлайну, обидві з назвою «Clicked: Q2 pricing PDF (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, що слухає властивість контакту.

Акаунт-менеджер, що дивиться на угоду, тепер бачить, як лічильник кліків росте ще до дзвінка. Маркетолог, що веде вебінар, може витягнути фільтр списку 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 з пропозиціями, записи демо. Просування на основі порогу для тегу холодних розсилок забрудить вашу воронку за тиждень. Найшвидший спосіб втратити довіру акаунт-менеджерів - просунути угоду, бо хтось проскрейпив посилання через curl.

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

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

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

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

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

Використовуйте варіант на основі тегів, коли шлях потенційного клієнта проходить через кілька точок дотику (це більшість B2B). Використовуйте варіант на основі посилання, коли сам актив і є сигналом - одне посилання з пропозицією, де кліки 3+ означають, що угода реальна. Обидва типи правил можуть співіснувати; нещодавно інженер з роботи з акаунтами налаштував робочий простір з 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 робочого простору зі staging на локальну машину. Обидва середовища тепер намагаються оновити той самий токен. Хто перший встигне - той і виграє; інший провалюється на наступній спробі.

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

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

Виправлення в усіх чотирьох випадках однакове: відкрийте плитку маркетплейсу HubSpot у Workspace Settings, натисніть Reinstall, прийміть скоупи. HubSpot видає новий код авторизації, Elido обмінює його на нову пару токенів, і інтеграція відновлюється. Жодні дані не втрачаються; події таймлайну, поставлені в чергу під час простою, скидаються протягом хвилини. Документація OAuth HubSpot детальніше описує потік коду авторизації, а правила ротації посилаються з розділу про токен оновлення.

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

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

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

Два сигнали показують, чи здорове оновлення.

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

Сторінка Integrations у Workspace Settings показує мітку часу останнього успішного оновлення для кожної інтеграції. Якщо HubSpot показує «Last refreshed: 6 days ago», тоді як усе інше показує хвилини, саме цей робочий простір варто перевірити першим.

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

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

1. Встановіть з /integrations, прийміть п'ять скоупів. Дайте HubSpot 60 секунд на створення шаблону події таймлайну.
2. Підтвердіть перший клік. Надішліть собі коротке посилання Elido, ціль якого несе ?email=<ваш_email_контакту_hubspot>, клікніть по ньому з іншого пристрою, оновіть сторінку контакту в HubSpot. Подія таймлайну має з'явитися протягом 30 секунд.
3. Додайте три власні властивості Elido до вигляду контакту. Workspace Settings, потім Contacts, потім Customize Sidebar. Саме тут маркетинг і продажі нарешті бачать однакові значення UTM.
4. Зачекайте два тижні перед налаштуванням правил порогу. Вам потрібні реальні дані кліків, щоб знати, як виглядає «високий намір» для вашого набору активів; довільні пороги, встановлені в день встановлення, зазвичай неправильні. Сторінка рішення для маркетологів і основи аналітики посилань допоможуть визначити, що вимірювати.
5. Налаштуйте перше правило на одному активі з високим наміром (сторінка цін, посилання з пропозицією). Спостерігайте за ним тиждень. Налаштуйте поріг і захист за сумою угоди. Повторіть.

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

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