Отслеживание кликов по ссылкам в HubSpot: клики на таймлайн сделки

Если ваша команда продаж живет в HubSpot, а отслеживание кампаний живет в инструменте коротких ссылок, у вас два таймлайна, которые никогда не разговаривают друг с другом. Маркетолог видит клики, менеджер по продажам видит стадию сделки. Границу между ними не видит никто. Это руководство разбирает подключение Elido к HubSpot так, чтобы каждый клик по короткой ссылке появлялся на таймлайне контакта, значения UTM попадали в свойства CRM, а пороговые значения объема кликов могли подталкивать стадии сделки вперед. Для той же связки с другой CRM смотрите отслеживание ссылок в Salesforce, где описан путь через platform events.

Основа держится на трех API HubSpot: Timeline Events API для записей по каждому клику, Contacts API для записи свойств и Deals API для продвижения стадий. Авторизация - OAuth 2.0 со scope, описанными в OAuth scope HubSpot. Коннектор HubSpot работает для установки через OAuth, ротации refresh-токенов и действия workflow Shorten. Поток таймлайна по каждому клику встроен в коннектор, но зависит от потока событий кликов Elido по каждому клику, который пока в дорожной карте, так что воспринимайте связку «клик - таймлайн» как будущую функцию, а не доступную сегодня. Остальное - вопрос настройки.

Коротко

• Подключайтесь через OAuth с пятью scope: 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, а не в workflow HubSpot.
• Ошибки 401 в интеграции почти всегда означают сломанную цепочку refresh-токена. Переустановите приложение через плитку маркетплейса, не вставляйте токены вручную.

Как клики попадают на таймлайн контакта HubSpot

Клик по короткой ссылке в Elido проходит пять шагов, прежде чем оказаться в HubSpot.

1. Обработчик редиректа на edge (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. Сводка на уровне сделки использует самые свежие значения через workflow 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:

• На контакте появляются два новых события таймлайна, оба с заголовком «Клик: 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 через workflow 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 воспринимает откат стадии как подозрительный. Если нужна обработка застоявшихся сделок, стройте ее как workflow HubSpot на hs_lastmodifieddate, а не как правило Elido.

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

Выбор между правилами по тегу и по ссылке

Есть два способа задать область действия порогового правила. По тегу оно покрывает набор ссылок с общим тегом (например, все 12 ссылок в вашей последовательности взращивания за Q2 считаются к одному порогу). По ссылке область ограничена одной короткой ссылкой.

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

Ротация refresh-токенов и ошибка 401, с которой вы столкнетесь

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

Коннектор Elido обрабатывает ротацию правильно. Последовательность:

1. Access-токен истекает каждые 30 минут (значение по умолчанию у HubSpot; это подтверждает значение expires_in в ответе токена).
2. Примерно за 90 секунд до истечения коннектор вызывает endpoint обновления с текущим refresh-токеном.
3. HubSpot возвращает новый access_token + новый refresh_token + новый expires_in.
4. Elido атомарно сохраняет оба значения в таблице токенов. Старый refresh-токен теперь недействителен.

Места, где это ломается:

Восстановление базы данных. Если вы восстанавливаете бэкап старше последнего обновления, сохраненный refresh-токен уже был признан недействительным выше по цепочке. Первый вызов обновления возвращает 401 с BAD_REFRESH_TOKEN. Симптомы: каждый вызов API HubSpot из Elido падает, пока вы не переустановите приложение.

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

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

Долгие простои. HubSpot не документирует жесткий срок истечения refresh-токенов, но на практике токены, неиспользуемые 6+ месяцев, иногда возвращают 401. Если у вас есть рабочее пространство, простаивающее с прошлого лета, готовьтесь к переустановке.

Исправление во всех четырех случаях одно и то же: откройте плитку маркетплейса HubSpot в Workspace Settings, нажмите Reinstall, примите scope. HubSpot выдает новый код авторизации, Elido обменивает его на новую пару токенов, и интеграция возобновляет работу. Данные не теряются; события таймлайна, накопившиеся во время простоя, доставляются в течение минуты. Документация HubSpot по OAuth подробнее описывает поток авторизационного кода, а правила ротации указаны в разделе про refresh-токен.

А как насчет интеграций через вставку токена?

Некоторые сервисы позволяют вставить токен доступа приватного приложения вместо OAuth. HubSpot это поддерживает, и это полностью обходит проблему ротации - токены приватных приложений не истекают и не ротируются. Elido не использует этот путь для HubSpot, потому что приватные приложения привязаны к одному аккаунту HubSpot и не могут устанавливаться на несколько порталов из одного рабочего пространства Elido. Если у вас только один портал HubSpot и вы хотите пропустить установку через маркетплейс, свяжитесь с нами через /contact; коннектор поддерживает оба режима, просто это не вынесено в интерфейс по умолчанию.

Мониторинг цепочки обновления

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

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

Страница Integrations в Workspace Settings показывает время последнего успешного обновления для каждой интеграции. Если у HubSpot написано «Обновлено: 6 дней назад», пока у всего остального - минуты, значит начинать разбор стоит с этого рабочего пространства.

Собираем все вместе

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

1. Установите из /integrations, примите пять scope. Дайте 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 наконец начинает казаться честной.