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 は各フレームワークパッケージ（react-intlayer、next-intlayer、vue-intlayer など）のオプショナル依存関係であるため、ほとんどのプロジェクトにはすでに含まれています。オプショナル依存関係をスキップする構成（npm install --no-optional など）の場合は、明示的にインストールしてください:

npm install @intlayer/analytics

アナリティクスを有効にするにはパッケージをインストールするだけで十分です。analytics.enabled のデフォルトは true で、パッケージがプロジェクト内に見つからない場合は @intlayer/config が false に解決します。インストールしない場合、すべての統合ポイントはNo-Op（何もしない処理）として解決されます — 以下の未インストール時のゼロコストを参照してください。

設定

アナリティクスは設定なしで動作します。デフォルトで有効であり、送信先とプロジェクトキーには既存の editor 設定ブロックをそのまま再利用します。

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 ブロックで収集を調整、または停止できます:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  analytics: {
    enabled: false, // デフォルト: true — 統合全体をバンドルから除外します
    flushInterval: 20_000, // 2 回のバッチ送信の間隔（ミリ秒）
    sampleRate: 1, // 記録するセッションの割合。0（なし）から 1（すべて）
  },
};

export default config;

@intlayer/analytics をアンインストールすることは enabled: false と同じ効果があります。全フィールドの一覧は設定リファレンスを参照してください。

使用方法

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

コードの変更は必要ありません。@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()を使用して、セッションが表示されたバリアントに目標を紐付けます：

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

</Tab> </Tabs>

Weights はオプションです — スプリットを調整するために、バリアントごとに 1 つ渡します。例えば、useExperiment("homepage-hero", ["default", "black_friday"], [9, 1]) のようにします。

子は、一致する辞書のVariantを読みます：

import { useIntlayer } from "react-intlayer";

export const HeroBanner = ({ variant }: { variant: string }) => {
  const { headline, cta } = useIntlayer("hero-banner", { variant });

  return (
    <section>
      <h1>{headline}</h1>
      <a>{cta}</a>
    </section>
  );
};

子コンポーネントでバリアントを読み込むことが、React の外でも機能する理由です。Vue、Svelte、Solid、Angular では、useIntlayer に渡されるセレクタはコンポーネントがセットアップされるときにキャプチャされるため、読み込みはバリアントが既知の後にのみマウントされるコンポーネント内で発生する必要があります。

実験が単一の辞書ではなくページ全体をカバーする場合は、variant をプロバイダーにホイストしてください — Ambient variant を参照してください。以下のすべての useIntlayer は、呼び出しサイトの変更なしでそれに対して解決されます。

コンポーネント外で生の割り当てが必要な場合は、クライアントに直接アクセスしてください：

getVariant は割り当てるだけで、exposure を記録しません。useExperiment() を使用することをお勧めします。そうしないと、コンバージョン率の分母がありません。

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

• 設計上の匿名性: セッションは回転する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）は、パッケージがインストールされていない場合、analytics.enabled が false の場合、または 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);

サーバーサイドのみ。 createIntlayerCMS() は clientId + clientSecret で認証され、シークレットはブラウザで利用できません — このスニペットがそこで実行されると、認証されていないリクエストが発行されます。ルートハンドラー、サーバーアクション、またはスクリプトに保つようにしてください。

便利なリンク

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