プロキシウェブ実験

ベンダーがホストするドメインから直接サードパーティ製の実験用スクリプトをロードしたくない場合や、クライアント側の実験評価を実行したい場合などがあります。一般的な理由としては、セキュリティポリシー、プライバシー管理、インフラストラクチャの所有権の強化などがあります。

プロキシベースの実験アーキテクチャにより、チームは一元化された実験プラットフォームを使用しながら、スクリプトの配信、評価、および露出追跡を完全に制御できます。

このドキュメントでは、一般的なプロキシパターンと、それらをサポートする実装の詳細について説明します。

スクリプト配信プロキシ

お客様は、実験用の JavaScript SDK へのリクエストをプロキシする軽量エンドポイントをホストしています。エンドユーザーは、サードパーティのドメインではなく、お客様が所有するドメインからスクリプトをロードします。

このパターンを使用すると、次のことができます。

サードパーティ製スクリプトの露出を減らします。
社内のセキュリティ要件やコンプライアンス要件に合わせることができます。

CDNの設定

オリジン：https://cdn.amplitude.com
パスの書き換え：/script/{API_KEY}.experiment.js → /script/{API_KEY}.experiment.js
キャッシュTTL：1～5分（鮮度とパフォーマンスのバランスを保ちます）
キャッシュキー：API_KEYを含む完全なURL

前（Amplitudeに直接アクセス）：

html

<script src="https://cdn.amplitude.com/script/abc123def456.experiment.js"></script>

その後（プロキシ経由で）：

html

<script src="https://experiments.acme.com/script/abc123def456.experiment.js"></script>

リモート評価プロキシ

ウェブ実験スクリプトは、リモート評価のために単一のエンドポイントを呼び出します。実験では、ターゲット設定ルールがクライアント上でローカルで使用できないプロパティを少なくとも1つ参照している場合、リモート評価が必要です。

このパターンを使用すると、次のことができます。

評価ロジックを一元的に管理できます。
サーバー側のコンテキストでリクエストを強化します。

プロキシ評価エンドポイントを公開する

Web Experiment SDKがリモート評価のために呼び出すHTTPSエンドポイントを作成して公開します。

URL の例：

フルパス：https://experiments.acme.com/sdk/v2/flags?delivery_method=web
ベースURL：https://experiments.acme.com/

SDKはすべての評価リクエストにこのベース URLを使用します。

Web実験スクリプトを設定する

AmplitudeがホストするURLの代わりに新しいエンドポイントを呼び出すようにウェブ実験スクリプトまたはSDKを設定します（flag.lab.amplitude.comまたはflag.lab.eu.amplitude.com）。Web実験スクリプトの上に次のコードを追加します。

html

<script>
  window.experimentConfig = {
    flagsServerUrl: "https://experiments.acme.com/",
  };
</script>

プロキシロジックを実装する

受信するブラウザ要求ごとに、プロキシは次のことを行わなければなりません。

リクエストを承認

**メソッド：**GET。
クエリパラメータ：delivery_method=web。

Amplitudeへ転送

米国のプロジェクトhttps://flag.lab.amplitude.com/sdk/v2/flags?delivery_method=web。
EUのプロジェクトhttps://flag.lab.eu.amplitude.com/sdk/v2/flags?delivery_method=web。

ヘッダーを挿入する

ヘッダー名	値	メモ
認証	`Api-Key <AMPLITUDE_PROJECT_API_KEY>`	サーバ上でのみ保存および管理できます。決してブラウザに公開しないでください。
X-Amp-Exp-User	`<base64-encoded user object>`	ブラウザからそのまま転送します。 `{"user_id": "...", "device_id": "..."}`を含む

返されるレスポンス： AmplitudeのJSON応答を変更せずにブラウザに返します。

リクエストフローの例

ブラウザからプロキシへ：

plaintext

GET https://experiments.acme.com/sdk/v2/flags?delivery_method=web
X-Amp-Exp-User: eyJ1c2VyX2lkIjoidXNlciIsImRldmljZV9pZCI6ImRldmljZSJ9

プロキシからAmplitudeへ：

plaintext

GET https://flag.lab.amplitude.com/sdk/v2/flags?delivery_method=web
Authorization: Api-Key <PROJECT_API_KEY>
X-Amp-Exp-User: eyJ1c2VyX2lkIjoidXNlciIsImRldmljZV9pZCI6ImRldmljZSJ9

プロキシからブラウザへ： Amplitudeの評価応答を返します。

応答形式

エンドポイントは、ユーザーに対して事前に評価された実験フラグオブジェクトのJSON配列を返します。

フラグオブジェクトスキーマ：

フィールド	概要
キー	実験を識別する固有のフラグキー。
セグメント	ターゲティングとバケット設定のルールは、ユーザーのプロパティに基づいて事前に評価されています。 Amplitudeには真の条件が含まれ、その他の条件は削除されます。
バリアント	キー、メタデータ、ウェブ実験アクション（ミューテーション、カスタムコード、URLリダイレクト）などの利用可能なバリアント。
メタデータ	実験のメタデータ: バージョン、デプロイメントステータス、再実行指標。

レスポンス例

json

[
  {
    "key": "example",
    "metadata": {
      "deliveryMethod": "web",
      "deployed": true,
      "evaluationMode": "local",
      "experimentKey": "exp-1",
      "exposureEvent": "$impression",
      "flagType": "experiment",
      "flagVersion": 5
    },
    "segments": [
      {
        "bucket": {
          "allocations": [
            {
              "distributions": [
                { "range": [0, 21474837], "variant": "control" },
                { "range": [21474836, 42949673], "variant": "treatment" }
              ],
              "range": [0, 100]
            }
          ],
          "salt": "G0U0BTSK",
          "selector": ["context", "user", "web_exp_id"]
        },
        "conditions": [
          [
            {
              "op": "is",
              "selector": ["context", "user", "device_category"],
              "values": ["desktop"]
            }
          ]
        ],
        "metadata": { "segmentName": "Segment 1" },
        "variant": "off"
      },
      {
        "metadata": { "segmentName": "All Other Users" },
        "variant": "off"
      }
    ],
    "variants": {
      "control": {
        "key": "control",
        "payload": [{ "action": "mutate", "data": { "mutations": [] } }],
        "value": "control"
      },
      "off": { "key": "off", "metadata": { "default": true } },
      "treatment": {
        "key": "treatment",
        "payload": [
          {
            "action": "mutate",
            "data": {
              "mutations": [
                {
                  "action": "set",
                  "attribute": "html",
                  "metadata": {
                    "scope": ["89e01141-6e35-4bc0-bb66-0e1bc0fd4823"],
                    "type": "text"
                  },
                  "selector": ".md\\:max-w-max:nth-child(1)",
                  "value": "updated text"
                }
              ]
            }
          }
        ],
        "value": "treatment"
      }
    }
  }
]

インプレッション（露出）イベントの転送

顧客が管理するバックエンドシステムは、インプレッション（露出）イベントをブラウザが直接送信するのではなく、実験プラットフォームに送信します。

このパターンを使用すると、次のことができます。

イベントパイプラインを統合します。
データガバナンスポリシーへのコンプライアンスをシンプル化します。

AmplitudeのAnalytics SDKをすでに使用している場合は、serverUrlからブラウザSDKのトラッキングエンドポイントを更新してください。

Amplitudeのアナリティクス SDKを使用していない場合は、Web 実験スクリプトの上に次のインプレッションイベント転送スクリプトを追加してください。

html

<script>
  // TODO: Replace this object with your tracker implementation.
  const customTracker = {
    track: (eventType, eventProperties) => {
      // TODO: Send eventType and eventProperties to your analytics tool.
      console.log({ eventType, eventProperties });
    },
  };
  window.experimentIntegration = {
    getUser: () => {
      // TODO: Return user.
      return {
        user_id: "user",
        device_id: "device",
      };
    },
    track: (e) => {
      // TODO: Track event
      customTracker.track(e.eventType, e.eventProperties);
      return true;
    },
  };
</script>

これは役に立ちましたか？