StarlightドキュメントサイトにおけるMicrosoft Clarityの統合ガイド

HagiCodeプロジェクトでは、ユーザーの行動を把握することの重要性を痛感してきました。コンテンツを提供しても、ユーザーがそれをどのように消費しているのか、どの部分でつまずいているのかを知る術がありませんでした。GitHubのスター数は遅延した指標であり、よりリアルタイムな洞察が必要でした。

Google Analyticsのような既存の分析ツールは高機能ですが、設定が複雑であり、GDPRなどのプライバシー規制への対応も必要です。そこで、Microsoft Clarityに注目しました。Clarityは無料のヒートマップ・セッションリプレイツールであり、直感的なインターフェースと、プライバシー規制への配慮がなされている点が、技術ドキュメントサイトに適していると考えました。

今回の目標は、HagiCodeのドキュメントサイトにClarityをシームレスに統合することです。全ページで動作させつつ、ユーザーがオプトアウトできる仕組み（プライバシーコンプライアンス）も確保します。

HagiCodeはAIを活用したコード支援ツールであり、開発プロセスにおいて多くの技術ドキュメントやブログ記事を管理しています。ユーザーのニーズをより深く理解するために、このデータ統合ソリューションを模索・実装しました。

技術選定と検討

当初、Astroのフックを利用して、ビルド時にClarityスクリプトを注入することを検討しました。これによりグローバルな適用は可能ですが、ユーザーのプライバシー設定に基づいてスクリプトのロード/アンロードを動的に制御する柔軟性がありませんでした。

ユーザーエクスペリエンスとプライバシー保護を考慮し、最終的にコンポーネントのオーバーライド方式を採用しました。Starlight（Astroベースのドキュメントフレームワーク）は、内部コンポーネントをオーバーライドできるため、<footer>や<head>のレンダリングロジックをカスタマイズし、Clarityのロードタイミングを細かく制御することにしました。

StarlightのルーティングメカニズムがカスタムStarlightWrapper.astroを自動的に呼び出さないという問題に直面しましたが、これはフレームワークのレンダリングフローを深く理解することの重要性を示唆しています。

コアソリューション: Footerコンポーネントのオーバーライド

Clarityスクリプトをすべてのドキュメントおよびブログページで読み込み、かつ既存のページ構造を壊さないようにするために、StarlightのFooterコンポーネントをオーバーライドすることを選択しました。

Footerを選択した理由

グローバル性: Footerはほとんどの標準ページに表示されます。
非侵襲性: スクリプトをFooter領域（実際にはbodyの末尾にレンダリング）に配置することで、ページの主要なレンダリングパス（LCP）をブロックせず、パフォーマンスへの影響を最小限に抑えます。
ロジック集中: コンポーネント内でCookie同意ロジックを一元管理できます。

実装手順

1. Clarityプロジェクトの準備

まず、Microsoft Clarityでアカウントを登録し、新しいプロジェクトを作成します。プロジェクトID（例: k8z2ab3xxx）を取得します。

2. 環境変数設定

IDをハードコーディングせず、環境変数に保存することを推奨します。

プロジェクトルートに.envファイルを作成します:

# Microsoft Clarity ID
PUBLIC_CLARITY_ID="あなたの_Clarity_ID"

3. オーバーライドコンポーネントの作成

src/components/ディレクトリにStarlightFooter.astroファイルを作成します。Starlightはこのファイルを認識し、デフォルトのFooterをオーバーライドします。

---
// src/components/StarlightFooter.astro
import DefaultFooter from '@astrojs/starlight/components/StarlightFooter.astro';

const clarityId = import.meta.env.PUBLIC_CLARITY_ID;

// シンプルなインラインスクリプト
const initScript = `
(function(c,l,a,r,i,t,y){
    c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
    t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
    y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
})(window, document, "clarity", "script", "${clarityId}");
`;
---

<DefaultFooter {...Astro.props} />

{/* 本番環境かつIDが存在する場合のみスクリプトを注入 */}
{import.meta.env.PROD && clarityId && (
  <script is:inline define:vars={{ clarityId }}>
    {initScript}
  </script>
)}

主なポイント:

is:inline: Astroにこの<script>タグ内のコンテンツを処理させず、そのままHTMLに出力させます。これはサードパーティの統計スクリプトに不可欠です。
define:vars: Astro 3+ の機能で、スコープ内で変数を安全に注入できます。
import.meta.env.PROD: ローカル開発時に不要な統計データを生成しないようにします。

高度な機能: プライバシーコンプライアンスとCookie制御

GDPRなどの規制を考慮すると、ユーザーの同意を得る仕組みが必要です。簡単なオプトアウト機能として、localStorageを利用できます。

// ユーザーが統計を拒否したかどうかのチェック（簡易例）
const consent = localStorage.getItem('clarity_consent');
if (consent !== 'denied') {
    // 上記のClarity初期化コードを実行
    window.clarity('start', clarityId);
}

経験からの学びと注意点

StarlightWrapper.astroの落とし穴: グローバルラッパーを作成してスクリプトを注入しようとしないでください。Starlightでは、特定のコンポーネント（StarlightFooter.astroやStarlightHead.astroなど）をオーバーライドするのが正解です。
スクリプト配置のパフォーマンス: Clarityはデータ精度のため<head>への配置を推奨していますが、ドキュメントサイトでは初期表示速度（LCP）がSEOとユーザー維持に直結します。Footer（bodyの末尾）への配置は、ごく一部の「即離脱」ユーザーのデータを犠牲にする代わりに、より高速なページロード体験を提供します。
開発環境のノイズ: import.meta.env.PRODの条件判断を必ず追加してください。開発モードでの頻繁なページリロードは、Clarityダッシュボードに不要なテストデータを蓄積させます。

効果検証

デプロイ後、Clarityコンソールでリアルタイムデータを確認できます。通常、数分以内にユーザーのヒートマップやセッションリプレイが表示されます。

HagiCodeでは、これらのデータから以下の洞察を得ました:

「クイックスタート」セクションの閲覧回数が多く、インストールガイドの直感性が向上する可能性があると判断しました。
「APIリファレンス」ページの滞在時間が最も長く、コアユーザー層のニーズが裏付けられました。

Microsoft Clarityの導入は、複雑なサーバーサイドの改造や重いSDKの導入を必要としません。Starlightのコンポーネントオーバーライド機能を利用することで、軽量なStarlightFooter.astroコンポーネントのみでグローバルなデータ統計を実現しました。この「マイクロインテグレーション」アプローチは、コードをクリーンに保ちつつ、ユーザー行動を把握する能力を提供します。

HagiCodeのようなドキュメント中心のプロジェクトを運営している場合、Clarityの導入を強くお勧めします。データは、ユーザーの本当のペインポイントがどこにあるかを教えてくれます。

タグ: Starlight Astro Microsoft Clarity Web Analytics Documentation Site

11月3日 09:49 投稿

異端開発室