HubSpotのリンククリックトラッキング：クリックをディールタイムラインに書き込む

営業チームはHubSpotで動き、キャンペーントラッキングはショートリンクツールに存在する - そうなると、二つのタイムラインは永遠に会話しません。マーケターはクリックを見る。AEはディールステージを見る。その間の繋がりを見ている人は誰もいない。このガイドでは、ElidoとHubSpotを接続して、すべてのショートリンククリックが連絡先のタイムラインに表示され、UTM値がCRMプロパティに入り、クリック量の閾値がディールステージを前進させられるようにする方法を解説します。

この仕組みは3つのHubSpot APIで成り立っています：クリックごとのレコードのためのTimeline Events API、プロパティ書き込みのためのContacts API、ステージ進行のためのDeals APIです。認証はHubSpot OAuth scopesに記載されたスコープでOAuth 2.0を使用します。HubSpotはElido上で2026年4月から本番稼働しており、コネクターがリフレッシュトークンのローテーション、リトライ、冪等なタイムライン書き込みを処理します。残りは設定だけです。

TL;DR

• 3つのスコープでOAuth接続する：crm.objects.contacts.write、crm.objects.deals.read、timeline。これが揃わないとHubSpotはインストールを拒否します。
• Elidoはクリックごとに、インストール時にプロビジョンされたeventTemplateIdを使ってTimeline Eventを送信します。UTMパラメータはイベントペイロードと3つのカスタム連絡先プロパティ（elido_last_utm_source、_campaign、_medium）に記録されます。
• original_source_drill_down_1のようなHubSpotの分析プロパティはファーストタッチのみです。継続的なアトリビューションにはカスタムプロパティを使いましょう。
• クリック閾値ルール（例：「提案リンクへの50クリックでディールをEngagedに進める」）はapi-coreでサーバーサイドで動作します。ワークスペース設定で構成し、HubSpotワークフローではありません。
• 統合における401エラーはほぼ常にリフレッシュトークンチェーンの破損を意味します。マーケットプレイスのタイルから再インストールしてください。手動でトークンを貼り付けないこと。

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

Elidoのショートリンクのクリックは、HubSpotに表示されるまで5つのステップを経ます。

1. エッジのリダイレクトハンドラー（services/edge-redirect）がクリックを読み取り、転送先を決定し、クリックイベントをRedpandaに書き込みます。これはホットパスであり、p50は約5ms - HubSpotはリクエストパス上に存在しません。
2. click-ingesterがRedpandaのトピックを読み取り、分析用にClickHouseに永続化します。
3. api-core内のHubSpotコネクター（崩壊以前はservices/hubspot-connector）がファンアウトトピックをサブスクライブします。HubSpotが接続されたワークスペースでのクリックごとに、Timeline Eventのペイロードを構築します。
4. コネクターが連絡先を解決します：クリックにElidoのcontact_id（?eid=パラメーターやログイン済みダッシュボード共有で設定される）が含まれていれば、直接HubSpotの連絡先にマッピングされます。fbclidやgclidしかない場合は、過去14日以内のフォーム送信でのメールマッチを試みます。それでも解決できない場合、イベントは72時間保留キューに入ります。
5. コネクターがインストール時にプロビジョンされたイベントテンプレートIDを使って/crm/v3/timeline/eventsにPOSTします。タイムライン書き込みはeventIdで冪等なので、リトライは安全です。

イベントペイロードには、HubSpotが表示する構造化フィールド（リンクスラッグ、転送先URL、キャンペーン名、国、デバイス）のtokensと、それ以外のすべて（完全なUTMセット、リファラー、ユーザーエージェントの断片、生のタイムスタンプ）のextraDataが含まれます。HubSpotのタイムラインUIはtokenをレンダリングします。extraDataはAPIで取得できますが、デフォルトビューでは非表示です。

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がデフォルトで適用するマッピングをまとめています。ワークスペース設定 - 統合 - HubSpot - フィールドマッピングで各行を上書きできます。UTMの衛生管理についてより深く知りたい場合は、エンドツーエンドUTMチュートリアルが命名規則を、UTMテンプレートガイドがリンク作成時の適用方法を説明しています。

実際の例

B2B SaaSアカウントがウェビナーを予約します。フォローアップメールには、UTM utm_source=webinar&utm_campaign=q2-pricing&utm_medium=email付きの価格PDFへのElidoショートリンクが含まれています。受信者は2日間にわたって2回クリックします。HubSpotでは：

• 連絡先に2つの新しいタイムラインイベントが表示されます。どちらも「クリック：Q2価格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週間でパイプラインが汚染されます。誰かがcurlでリンクをスクレイプしたことでディールが進んでしまい、AEの信頼を失う最速の方法です。

guardブロックが重要。 require_associated_contactなしでは、匿名クリック（誰かが友人にリンクを転送する）がルールを発動させる可能性があります。deal_amount_minなしでは、エンタープライズ案件向けのステージに400ドルのトライアルディールが進んでしまいます。

逆ルールは対称ではない。 Elidoは非アクティブ時に自動でステージを降格しません。HubSpotのレポートがステージの逆転を疑わしいものとして扱うためです。停滞したディールを処理したい場合は、Elidoのルールではなくhs_lastmodifieddateを使ったHubSpotワークフローとして構築してください。

内部のコンバージョン転送の仕組みについては、コンバージョン転送ガイドでイベントスキーマ、リトライポリシー、デッドレターキューを説明しています。コンバージョントラッキング機能ページではMeta CAPI、GA4、Mixpanelに対して同じフローを示しています - HubSpotは複数の転送先の1つです。

タグベースとリンクベースのルールを選ぶ

閾値ルールのスコープを定める方法は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つのケースすべてで解決策は同じです：ワークスペース設定からHubSpotマーケットプレイスのタイルを開き、再インストールをクリックして、スコープを承認します。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%を超えるエラー率が持続する場合が早期警告です。ほとんどのワークスペースは数週間にわたってエラーゼロを示します。オブザーバビリティガイドでこれをアラートに接続する方法を説明しています。

ワークスペース設定の統合ページには、統合ごとの最後の正常なリフレッシュのタイムスタンプが表示されます。HubSpotが「最終更新：6日前」と表示しているのに他のすべてが数分を示している場合、そのワークスペースを最初に確認してください。

すべてをまとめる

統合を導入するチームへの合理的なロールアウトシーケンス：

1. /integrationsからインストールし、3つのスコープを承認します。HubSpotがタイムラインイベントテンプレートをプロビジョンするまで60秒待ちます。
2. 最初のクリックを確認します。?eid=<your_hubspot_contact_id>付きのElidoショートリンクを自分に送り、別のデバイスからクリックして、HubSpotの連絡先ページをリロードします。タイムラインイベントが30秒以内に表示されるはずです。
3. 3つのElidoカスタムプロパティを連絡先ビューに追加します。ワークスペース設定 - 連絡先 - サイドバーをカスタマイズ。ここでマーケティングと営業がついに同じUTM値を見ることができます。
4. 閾値ルールを設定する前に2週間待ちます。アセットミックスで「高いインテント」が何を意味するかを知るには実際のクリックデータが必要です。インストール日に設定した任意の閾値はたいてい間違っています。マーケターソリューションページとリンクアナリティクス入門が何を測定するかを考えるのに役立ちます。
5. 単一の高いインテントのアセット（価格ページ、提案リンク）に最初のルールを設定します。1週間観察します。閾値とディール金額ガードを調整します。繰り返します。

完全な機能セットは統合カタログに文書化されており、コネクターのソースコードはservices/api-coreのhubspotパッケージにあります。プラットフォーム全体を評価している場合は、Elido pricingでHubSpot統合が含まれるティア（Pro以上）を確認でき、サーバーサイドコンバージョントラッキング概要でElidoが転送する他のCRMと分析先との比較ができます。

最後の経験則として：タイムラインイベントをエンゲージメントの真実の情報源として扱う。カスタムプロパティを最新キャンペーンの真実の情報源として扱う。hs_analytics_*ファミリーをファーストタッチ以外には絶対に信頼しない。この3点セットがマーケティングと営業が議論する内容の95%をカバーし、HubSpotのデータモデルがようやく正直に感じられるようになります。