Intlayer Analytics ドキュメント

@intlayer/analyticsはオプションのコンパニオンパッケージであり、実際にどのコンテンツが訪問者に表示されたか（どのページで、どのロケールで、翻訳されたコンテンツのどの特定の部分か）を把握できるようにします。これにより、オーディエンスを理解し、コンテンツ上でA/Bテストを実行することができます。

目次

トラッキング対象

@intlayer/analyticsは、3種類の匿名イベントをバッチ処理します：

イベントはメモリに収集され、約20秒に1回のバッチリクエストとして送信されます。キー入力やレンダリングごとに送信されることはないため、アナリティクスが初回レンダリング時間に影響を与えたり、インタラクションごとにリクエストを追加したりすることはありません。

コンテンツA/Bテストをどのように強化するか

Intlayerでは、すでにコンテンツのバリアント (Variants)を宣言できます（例：controlとblack_fridayバリアントを持つhero-banner辞書など）。@intlayer/analyticsは、そのサイクルを完結させます：

1. getVariant(experimentKey, variants)は、各匿名セッションを決定論的にバリアントに割り当てます。これはセッションIDと実験キーの純粋関数であるため、割り当てはセッション全体で安定しており、初回レンダリング前のサーバーラウンドトリップを必要としません（ちらつきやレイアウトのずれが発生しません）。
2. すべてのcontent_exposureイベントには、表示されたvariantが含まれます。
3. useConversion()を使用すると、そのバリアントに目標（例："cta_click"）を紐付けることができます。
4. ダッシュボードの実験結果エンドポイントでは、統計的有意性（Z検定）を含むバリアントごとのコンバージョン率を比較します。

インストール

@intlayer/analyticsはピア（peer）、オプションの依存関係です。フレームワークパッケージによって自動的にインストールされることはありません。intlayerと一緒に追加してください：

npm install @intlayer/analytics

インストールしない場合、すべての統合ポイントはNo-Op（何もしない処理）として解決されます — 以下の未インストール時のゼロコストを参照してください。

設定

Analyticsは既存のeditor設定ブロックを再利用します。入力する個別のanalytics設定スキーマはありません：

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    backendURL: "https://back.intlayer.org", // アナリティクスデータ収集エンドポイントとしても使用されます
    clientId: "your-client-id", // アナリティクスプロジェクトキーとしても使用されます
    clientSecret: "your-client-secret",
  },
};

export default config;

• editor.backendURL — アナリティクスイベントが送信されるベースURL（POST {backendURL}/api/analytics/events）。
• editor.clientId — 収集されたすべてのイベントに紐付けられる公開プロジェクトキー。これは有効化スイッチとしても機能します：clientIdが設定されるまで、アナリティクスは完全に無効化されます（後述のようにツリーシェイキングで削除されます）。

Intlayerをセルフホスト（self-host）している場合、editor.backendURLを共有しているため、アナリティクスは自動的にご自身のインスタンスを指します。

フレームワークのサポート

Analyticsはreact-intlayerからの共有IntlayerProviderに組み込まれているため、そのプロバイダが使用されている場所であればどこでも今日から利用できます：

使用方法

自動プロバイダレベルのトラッキング

コードの変更は必要ありません。@intlayer/analyticsがインストールされ、editor.clientIdが設定されると、IntlayerProviderは自動的に以下を実行します：

• マウント時にアナリティクスクライアントを初期化します。
• 初回ロード時にpage_viewを記録します。
• ロケールが変更されるたびにpage_viewを記録します。
• 約20秒間のフラッシュ（送信）ループを開始し、アンマウント時またはタブを閉じた時に残りのイベントを送信します（navigator.sendBeacon経由、fetch(..., { keepalive: true })にフォールバック）。

自動ノードレベルのトラッキング

useIntlayerが表示用のコンテンツを解決するたびに、インタープリタは正確なdictionaryKey + キーパス + ロケールに対してcontent_exposureイベントを報告します。これについてもコードの変更は必要ありません。送信ウィンドウ内で同じノードが繰り返し表示された場合は、count付きの単一のイベントとしてまとめられるため、50回再レンダリングされるリストが50のイベントを送信することはありません。

A/Bテストのコンバージョントラッキング

useConversion()を使用して、セッションが表示されたバリアントに目標を紐付けます：

クライアント側でのバリアント解決

プライバシーとパフォーマンス

• 設計上の匿名性: セッションは回転するIDによって識別されます。バックエンドはそのIDのSHA-256ハッシュのみを保存し、生のIDやIPアドレスは決して保存しません。
• 大まかな位置情報: CDNのジオロケーションヘッダー（cf-ipcountry、x-vercel-ip-countryなど）から派生した国コードのみであり、IPが読み取られたり保存されたりすることはありません。
• デフォルトで検索パラメータを除外するURL: そのため、クエリ文字列（query strings）がキャプチャされることはありません。
• サンプリング: sampleRateを使用すると、トラフィックの多いアプリでコンテンツ露出イベントの一部のみを保持できます。
• バッチ処理: 約20秒ごと（flushInterval）、またはバッファがいっぱいになった場合（maxBufferSize）はそれより早く、1回のリクエストを送信します。イベントごとにリクエストを送信することはありません。

未インストール時のゼロコスト

@intlayer/analyticsは、@intlayer/editorとまったく同じオプション依存関係パターンに従っています：

• 各統合ポイントは、try/catchでラップされた動的import()を介してパッケージをロードします。@intlayer/analyticsをインストールしないアプリでは、バンドルサイズやランタイムコストが発生することはなく、エラーが表示されることもありません。
• コンパイル時の環境変数（INTLAYER_ANALYTICS_ENABLED）は、editor.clientIdが設定されていない場合に@intlayer/configによって自動的に'false'に設定されます。これにより、バンドラーが統合全体をデッドコードとして削除（dead-code-eliminate）できるようになります。
• Intlayerエディタ/CMSプレビューのiframe内ではアナリティクスが無効になっているため、エディタセッションが実際のトラフィックとしてカウントされることはありません。

ダッシュボード：アナリティクスページ

プロジェクトがイベントを収集すると、IntlayerダッシュボードのAnalyticsページ（プロジェクトを選択するとサイドバーに表示されます）に以下が表示されます：

• アクティブユーザー — 選択したローリングウィンドウ（7日 / 30日 / 90日）内のユニーク訪問者数。
• 今日のユーザー および 過去7日間のユーザー。
• 選択したウィンドウ内のページビュー。
• 日次ユニーク訪問者の推移グラフ。
• オーディエンスをロケールおよび国別にランク付けするロケールおよびロケーションの詳細タブ。

バックエンドAPIリファレンス

すべての読み取りエンドポイントには認証が必要です。データの取り込み（ingestion）は公開されており、ボディのclientIdによって属性付けされます。

CMS SDKを使用して、これらをプログラムで呼び出すこともできます：

import { createIntlayerCMS } from "@intlayer/api";import { analyticsEndpoint } from "@intlayer/api/analytics";const cms = createIntlayerCMS();const { data: audience } = await analyticsEndpoint(cms).getAudience(30);

便利なリンク

• ダイナミック辞書 - コレクションとバリアント
• Intlayer CMS - CMS SDK
• Intlayer ビジュアルエディタ
• 設定リファレンス
• セルフホスティングガイド