HubSpotリンククリック計測: クリックを商談タイムラインに書き込む

営業チームはHubSpotで動いているのに、キャンペーン計測は別の短縮リンクツールで動いている場合、互いに会話しない2本のタイムラインを抱えることになります。マーケターにはクリックが見え、AE(アカウントエグゼクティブ)には商談ステージが見えますが、その間をつなぐ線は誰にも見えません。このガイドでは、ElidoをHubSpotに接続し、すべての短縮リンクのクリックを連絡先タイムラインに表示させ、UTM値をCRMプロパティに反映させ、クリック数の閾値で商談ステージを前進させる方法を解説します。別のCRMに対する同様の配線については、Salesforceリンク計測でプラットフォームイベント経由の方法を扱っています。

この仕組みは3つのHubSpot APIの上に成り立っています。クリック単位の記録にはTimeline Events API、プロパティの書き込みにはContacts API、ステージの前進にはDeals APIです。認証はHubSpot OAuth scopesに記載されているスコープを使ったOAuth 2.0です。HubSpotコネクタは、OAuthインストール、リフレッシュトークンのローテーション、Shortenワークフローアクションについてはすでに稼働しています。クリック単位のタイムラインフィードはコネクタに組み込まれていますが、ロードマップ段階にあるElidoのクリック単位イベントストリームを待っている状態です。そのため、クリックからタイムラインへの反映は「現在利用可能」ではなく「今後提供予定」として扱ってください。それ以外は設定だけの話です。

まとめ

• 5つのスコープでOAuth接続します: oauth、crm.objects.contacts.read、crm.objects.contacts.write、timeline、automation。これより少ないとHubSpotはインストールを拒否します。
• Elidoは各クリックを、インストール時に用意されたeventTemplateIdを持つTimeline Eventとして投稿します。UTMパラメータはイベントのペイロードと、3つのカスタム連絡先プロパティ(elido_last_utm_source、_campaign、_medium)の両方に反映されます。
• original_source_drill_down_1のようなHubSpotの分析プロパティはファーストタッチ専用です。継続的な計測には、組み込みのプロパティではなくカスタムプロパティを使ってください。
• クリック閾値ルール(例: 「提案書リンクで50クリックすると商談をEngagedに進める」)は、HubSpotのワークフローではなくapi-core内でサーバーサイドに実行されます。Workspace Settingsで設定してください。
• インテグレーションでの401エラーは、ほぼ常にリフレッシュトークンの連鎖が壊れたことを意味します。手でトークンを貼り付けるのではなく、マーケットプレイスのタイルから再インストールしてください。

クリックがHubSpotの連絡先タイムラインに届くまで

Elidoでの短縮リンクのクリックは、HubSpotに表示されるまでに5つのステップをたどります。

1. エッジのリダイレクトハンドラー(services/edge-redirect)がクリックを読み取り、遷移先を決定し、クリックイベントをRedpandaに書き込みます。これはホットパスであり、p50は約5ミリ秒です。HubSpotがリクエストパス上に存在することはありません。
2. click-ingesterがRedpandaのトピックを読み取り、分析用にClickHouseへ永続化します。
3. 独立したサービスであるHubSpotコネクタが、ファンアウトトピックを購読します。HubSpotが接続されているワークスペース上のすべてのクリックについて、Timeline Eventのペイロードを構築します。
4. コネクタはメールアドレスで連絡先を解決します。リンクのemailメタデータ、utm_content、または遷移先URLのemail=パラメータからアドレスを探し、HubSpotの連絡先の中から完全一致を検索します。メールアドレスがない、または一致する連絡先がない場合、そのクリックについてタイムラインへの書き込みは行われません。
5. コネクタは、インストール時に用意されたイベントテンプレートIDを使って/crm/v3/timeline/eventsにPOSTします。タイムラインへの書き込みはeventIdに対して冪等であるため、再試行しても安全です。

イベントペイロードには、HubSpotのタイムラインUIが描画する5つのtokensが含まれます。短縮URL、遷移先URL、UTMキャンペーン、UTMソース、クリックのタイムスタンプです。

UTMとプロパティの対応表

ここが、自力で配線しようとしたチームがつまずく部分です。HubSpotには2種類の「ソース」プロパティがあり、それぞれ挙動が異なります。

分析プロパティ(ファーストタッチのみ)。 original_source_drill_down_1、hs_analytics_first_url、hs_analytics_first_referrer、そのほかのhs_analytics_*系プロパティは、連絡先が最初に作成されたときに一度だけ設定されます。それ以降のContacts API経由の書き込みは、黙って破棄されます。HubSpotはエラーを返さず、値が変わらないだけです。「直近のキャンペーン」の値が2024年で止まっているように見える理由は、これです。

カスタムプロパティ(読み書き可能)。 自分で定義したものは自由に書き込めます。Elidoは初回接続時に3つのプロパティを用意します。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企業のアカウントがウェビナーを予約したとします。フォローアップメールには、料金表PDFへのElido短縮リンクが含まれており、UTMはutm_source=webinar&utm_campaign=q2-pricing&utm_medium=emailです。受信者は2日間で2回クリックします。HubSpot上では次のようになります。

• 連絡先に新しいタイムラインイベントが2件表示され、どちらも「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(昨年9月にebookをダウンロードした際に設定されたもの)は変わりません。これはバグではなく、正しいファーストタッチの挙動です。
• 関連する商談のelido_recent_link_clicksプロパティが、連絡先プロパティを監視するHubSpotワークフロー経由で2増加します。

商談を見ているAEは、電話をかける前にクリックカウンターが上昇しているのを目にすることになります。ウェビナーを担当するマーケターは、elido_last_utm_campaign = q2-pricingでHubSpotのリストフィルターを作成し、再エンゲージメントのシーケンスに送ることができます。同じデータの、2つの見え方です。

クリック閾値を商談ステージに結びつける

タイムラインの可視化は最低限の話です。閾値ルールこそが、このインテグレーションの真価を発揮する部分です。誰もダッシュボードを見ていなくても、クリックのシグナルを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内で動作し、タイムラインへの書き込みを支えているのと同じファンアウトトピック上で実行されます。クリックが発生するたびに、(contact_id, link_tag)単位のローリングカウントが再計算されます。カウントが閾値を超え、その連絡先がfrom_stageにある商談に紐づいている場合、コネクタは/crm/v3/objects/deals/{dealId}にproperties.dealstage = qualifiedtobuyでPATCHを送ります。

実務上の注意点をいくつか挙げます。

購買意欲の高いアセットで使うこと。 料金ページ、提案書PDF、デモ録画のリプレイなどです。コールドアウトリーチ用のリンクタグで閾値駆動の前進を設定すると、1週間でパイプラインが汚染されます。AEの信頼を最速で失う方法は、誰かがcurlでリンクをスクレイピングしただけで商談が進んでしまうことです。

guardブロックが重要です。 require_associated_contactがないと、匿名のクリック(誰かがリンクを友人に転送した場合など)がルールを発動させてしまいます。deal_amount_minがないと、400ドルのトライアル案件がエンタープライズ向けに予約されたステージまで進んでしまいます。

逆方向のルールは対称ではありません。 Elidoは非アクティブを理由にステージを自動的に後退させることはしません。HubSpotのレポートは、ステージの後退を不審な動きとして扱うためです。停滞した商談の扱いが必要であれば、Elidoのルールとしてではなく、hs_lastmodifieddateに基づくHubSpotワークフローとして構築してください。

内部で使われているコンバージョン転送の仕組みについては、コンバージョン転送ガイドがイベントスキーマ、再試行ポリシー、デッドレターキューを文書化しています。コンバージョン計測機能ページでは、Meta CAPI、GA4、Mixpanelに対する同じフローを紹介しており、HubSpotはその中のひとつの転送先です。

タグベースとリンクベース、どちらのルールを選ぶか

閾値ルールのスコープには2つの方法があります。タグベースは、あるタグを共有するリンクの集合をカバーします(たとえば、Q2ナーチャリングシーケンスの12本のリンクすべてが同じ閾値にカウントされます)。リンクベースは、単一の短縮リンクにスコープします。

見込み客の旅が複数のタッチポイントをまたぐ場合(B2Bの大半がこれに該当します)はタグベースを使ってください。アセットそのものがシグナルである場合、たとえば単一の提案書リンクで3回目以降のクリックが商談の本気度を示す場合はリンクベースを使ってください。両方のルールタイプは共存でき、あるアカウントエンジニアは最近、8つのタグベースと14のリンクベースのルールを競合なく並行して動かすワークスペースを構築しました。

リフレッシュトークンのローテーションと、いずれ遭遇する401

HubSpotのOAuthはリフレッシュトークンをローテーションします。grant_type=refresh_tokenを付けて/oauth/v1/tokenを呼ぶたびに、新しいリフレッシュトークンが返され、それまでのトークンは無効化されます。これはセキュリティ上は望ましい一方で、トークンを手動管理しようとする人にとっては厄介です。

Elidoのコネクタはローテーションを正しく処理します。流れは次の通りです。

1. アクセストークンは30分ごとに失効します(HubSpotのデフォルトで、トークンレスポンス内のexpires_inの値でも確認できます)。
2. 失効の約90秒前に、コネクタは現在のリフレッシュトークンを使ってリフレッシュエンドポイントを呼び出します。
3. HubSpotは新しいaccess_token、新しいrefresh_token、新しいexpires_inを返します。
4. Elidoは両方をトークンテーブルにアトミックに保存します。古いリフレッシュトークンはこの時点で無効になります。

この仕組みが壊れる場面は次の通りです。

データベースの復元。 直近のリフレッシュより古いバックアップを復元すると、保存されているリフレッシュトークンはすでに上流で無効化されています。最初のリフレッシュ呼び出しはBAD_REFRESH_TOKENとともに401を返します。症状としては、再インストールするまでElidoからのすべてのHubSpot API呼び出しが失敗します。

環境間でのトークンのコピー。 開発者がステージング環境からローカル環境へワークスペースのHubSpotトークンをコピーしたとします。両方の環境が同じトークンに対してリフレッシュを試みることになり、先に実行した方が勝ち、もう一方は次の試行で失敗します。

トークン行の手動編集。 デバッグ中はやりたくなりますが、決して良い考えではありません。token_versionカラムはリフレッシュとアトミックにインクリメントされるため、手動編集は楽観的並行性チェックを壊し、次のリフレッシュが失敗します。

長期間の停止。 HubSpotはリフレッシュトークンの厳密な有効期限を文書化していませんが、実際には6か月以上使われていないトークンが401を返すことがあります。昨年の夏から休眠しているワークスペースがあれば、再インストールが必要になると想定してください。

これら4つのケースすべてに対する修正方法は同じです。Workspace SettingsからHubSpotのマーケットプレイスタイルを開き、Reinstallをクリックし、スコープを承認します。HubSpotは新しい認可コードを発行し、Elidoはそれを新しいトークンペアと交換し、インテグレーションは再開します。データが失われることはなく、停止中にキューに溜まったタイムラインイベントは1分以内に反映されます。認可コードフローの詳細はHubSpot OAuthドキュメントに、ローテーションのルールはリフレッシュトークンのセクションからリンクされています。

トークン貼り付け型のインテグレーションはどうか

一部のベンダーは、OAuthの代わりにPrivate Appのアクセストークンを貼り付ける方式を提供しています。HubSpotもこれに対応しており、ローテーションの問題を完全に回避できます。Private Appのトークンは失効せず、ローテーションもされません。ElidoがHubSpotにこの方式を使わないのは、Private Appが単一のHubSpotアカウントに紐づいており、単一のElidoワークスペースから複数のポータルにまたがってインストールできないためです。HubSpotポータルが1つしかなく、マーケットプレイス経由のインストールを省略したい場合は、/contactから連絡してください。コネクタは両方のモードに対応していますが、デフォルトのUIには公開されていません。

リフレッシュチェーンの監視

リフレッシュが正常かどうかは、2つのシグナルでわかります。

hubspot_refresh_attempts_total{result="ok|error"}というPrometheusカウンターがapi-coreにあります。あるワークスペースでエラー率が1%を超える状態が続くのは早期警告です。ほとんどのワークスペースでは、何週間もエラーがゼロのまま推移します。これをアラートに組み込む方法は可観測性ガイドで解説しています。

Workspace SettingsのIntegrationsページには、インテグレーションごとに直近のリフレッシュ成功日時が表示されます。ほかがすべて「数分前」と表示されているのに、HubSpotだけ「最終リフレッシュ: 6日前」と表示されている場合、まずそのワークスペースを確認すべきです。

まとめて実践する

このインテグレーションを導入するチームにとって、妥当な展開手順は次の通りです。

1. /integrationsからインストールし、5つのスコープを承認します。HubSpotがタイムラインイベントテンプレートを用意するまで60秒ほど待ちます。
2. 最初のクリックを確認します。遷移先に?email=<your_hubspot_contact_email>を含むElido短縮リンクを自分宛てに送り、別のデバイスからクリックし、HubSpotの連絡先ページを更新します。タイムラインイベントは30秒以内に表示されるはずです。
3. 3つのElidoカスタムプロパティを連絡先ビューに追加します。Workspace Settingsの後、Contacts、Customize Sidebarの順です。ここでようやく、マーケティングと営業が同じUTM値を見ることになります。
4. 閾値ルールを設定するまで2週間待ちます。自社のアセット構成における「購買意欲が高い」とはどういう状態かを知るには、実際のクリックデータが必要です。インストール当日に決めた任意の閾値は、たいてい間違っています。マーケター向けソリューションページとリンク分析入門が、何を計測すべきかを整理する助けになります。
5. 最初のルールは、購買意欲の高いアセット(料金ページや提案書リンク)ひとつに設定します。1週間様子を見ます。閾値と商談金額のガードを調整します。これを繰り返します。

全機能はインテグレーションカタログに文書化されており、コネクタのソースはservices/hubspot-connectorにあります。より広くプラットフォームを検討している場合は、Elidoの料金ページでHubSpotインテグレーションが含まれるプラン(Pro以上)を確認でき、サーバーサイドコンバージョン計測の概要ではHubSpotとElidoが転送しているほかのCRM・分析先を比較しています。

最後にひとつ、経験則を挙げておきます。エンゲージメントの正とするデータはタイムラインイベント、最新キャンペーンの正とするデータはカスタムプロパティとし、hs_analytics_*系プロパティはファーストタッチ以外の用途では決して信用しないことです。この3つを守れば、マーケティングと営業が言い争う内容の95パーセントはカバーでき、HubSpotのデータモデルがようやく信頼できるものに感じられるようになります。