クライアント分析イベントのファンアウトファサード

定義

ボタンクリック・決済開始・ログイン成功などの プロダクト意図 を分析ツールに送るとき、画面コードが Google タグマネージャー（GTM）・PostHog などの ベンダー SDK を直接呼ばず、useTelemetry().track(...) のような 単一 API だけを使う設計である。

ファサード（facade） は、複雑な配管の前に置く単純な窓口である。ファンアウト（fan-out） は、1 回の track 呼び出しが複数の シンク（sink） — データを受け取るシステム — に複製されることである。

なぜ必要か

コールサイトごとに posthog.capture と dataLayer.push を混在させると、(1) 片方のシンクにだけイベントが行き、(2) シンクを差し替えるときにアプリ全体を直す必要があり、(3) SDK 例外が決済・ログインフローを壊す可能性がある。ファサードは 消費側は意図だけを伝え、init・ルーティング・マスキングは Provider が所有 する。

動作原理

1. TelemetryProvider がシンクを初期化し、コンテキストでアクションを提供する。
2. track({ event, ...props }) → 1 次シンク（例: dataLayer）へ push → ルールに合うイベントだけ 2 次シンク（例: PostHog）へルーティング。
3. identify(userId, traits) / reset() でログイン・ログアウト境界を揃える。
4. シンクごとに 独立した env ゲート（キーがなければそのシンクだけ no-op）。
5. すべてのシンク呼び出しは try/catch best-effort — 分析失敗がビジネスロジックを止めない。

function useCheckoutButton() {
  const { track } = useTelemetry();
  return () => {
    track({ event: "checkout_started", plan: "pro" });
    openCheckout();
  };
}

実務での適用

• 新規イベントはフック経由のみとするよう、コードレビュー・lint（ベンダー SDK import 禁止リスト）。
• autocapture を切り、明示的 track だけを使うとノイズ・上限を制御しやすい。
• セッションリプレイを使う場合、入力・画像など マスキングのデフォルト を init に置く。
• export だけされて消費側が 0 のヘルパーは デッドパス — 文書に Non-goal として書き、移植時に蘇生させない。

トレードオフ

使うべきでない場合

• サーバー監査ログ・決済台帳のように 欠損が許されない 記録（クライアント分析層に任せないこと）。
• 個人情報を props に載せて複数シンクへ無差別複製する場合（スキーマ・マスキングを先に）。

よくある失敗

• capturePostHog と track を混用 → GTM 未到達。
• ログアウトで reset を抜き、前ユーザーのセッションが続く。
• テストで分析 mock が throw するのに try/catch がなく決済テストが赤になる。

関連概念

• react-context-render-granularity — Provider でアクションを注入するときのレンダー範囲