JSON ペイロード

JSON ペイロードは、実験バリアントに動的な設定データを付加します。ペイロードを使用して、コードを再デプロイすることなく、アプリケーションの動作や外観をリモートで変更できます。

厳密に型付けされたペイロードを使用すると、Amplitudeが各ペイロードをアプリケーションに到達する前に検証できるように、スキーマを定義できます。

JSON ペイロードの仕組み

バリアントを作成する際、アプリケーションに渡したい変数を含むJSONペイロードを添付できます。

アプリケーションによる実験の評価時：

実験SDKはユーザーのためにバリアントを取得します。
SDKは、そのペイロードとともにバリアントを返します。
アプリケーションはペイロードを読み取り、体験を動的に設定します。

このパターンは単純なフラグや、ペイロードがレイアウト、機能オプション、コピー、または設定値を定義する複雑な実験に有効です。

ワークフローの概要

一般的なワークフローは次の手順に従います。

ペイロードを含むバリアントを作成する: その体験の設定を定義する JSON オブジェクトをバリアントに追加します。
フラグまたは実験を有効にする: 設定をユーザーにデプロイします。
アプリケーションで評価する: 実験SDK（ウェブ、モバイル、またはバックエンド）を使用して、各ユーザーのバリアントを取得します。
ペイロードを使用する: variant.payloadを読み取り、設定をUIまたはビジネスロジックに適用します。

ペイロードを使用してバリアントを作成する

Amplitude UIを通じて、またはManagement APIを通じてプログラムでバリアントにJSONペイロードを追加できます。

UIを通して

バリアントを作成または編集するときにペイロードを追加するには:

*「実験」>「フィーチャーフラグ」または「実験」*に移動します。
設定したいフラグまたは実験を選択します。
「バリアント」セクションで、バリアントを作成または編集します。
バリアント名、値、および説明を入力します。
Payload フィールドに、JSON 設定を追加します。
**[適用] **を選択し、変更内容を保存します。

ペイロードの例 – ブログのレイアウトの設定

json

{
  "layout": "cards",
  "titlePosition": "above",
  "gradient": false,
  "showDescription": true,
  "cardCount": 3
}

UI でバリアントを作成する方法の詳細については、「バリアントを作成する」を参照してください。

Management API経由

実験管理APIを使用してペイロードを持つバリアントを作成します。リクエストボディにpayloadフィールドを含めてください。

APIリクエストの例

bash

curl --request POST \
  --url 'https://experiment.amplitude.com/api/1/flags/{id}/variants' \
  --header 'Authorization: Bearer <management-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "key": "cards-layout",
    "name": "Cards Layout",
    "description": "Blog posts displayed in card format",
    "payload": {
      "layout": "cards",
      "titlePosition": "above",
      "gradient": false,
      "showDescription": true,
      "cardCount": 3
    },
    "rolloutWeight": 1
  }'

以下の詳細なAPIドキュメントを参照してください。

フラグのバリアントを作成します。
実験用のバリアントを作成します。

アプリケーション内のペイロードにアクセスする

ペイロードを含むバリアントを作成した後、アプリケーションは次のことを行う必要があります。

実験SDKを初期化します。
ユーザーのバリアントを取得します。
アクセスvariant.payload。
適切なデフォルト設定を使用して設定を適用してください。

正確な構文はSDKによって異なりますが、パターンは一貫しています。

JavaScript/TypeScript（ブラウザ）

javascript

import { Experiment } from '@amplitude/experiment-js-client';
// Initialize the Experiment client
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
  // Optional configuration
});
// Fetch variants for the current user
await experiment.fetch({
  user_id: 'user123',
  device_id: 'device456',
});
// Get the variant for a specific flag
const variant = experiment.variant('blog-layout-flag');
// Access the payload with defaults
if (variant && variant.payload) {
  const layout = variant.payload.layout || 'list';
  const titlePosition = variant.payload.titlePosition || 'below';
  const showDescription = variant.payload.showDescription !== false;
  const cardCount = variant.payload.cardCount || 5;
  configureBlogLayout({
    layout,
    titlePosition,
    showDescription,
    cardCount,
  });
}

React の例

javascript

import { useEffect, useState } from 'react';
import { Experiment } from '@amplitude/experiment-js-client';
function BlogComponent() {
  const [layoutConfig, setLayoutConfig] = useState({
    layout: 'list',        // defaults
    titlePosition: 'below',
    showDescription: true,
    cardCount: 5,
  });
  useEffect(() => {
    async function fetchExperiment() {
      const experiment = Experiment.initialize('<DEPLOYMENT_KEY>');
      await experiment.fetch({ user_id: 'user123' });
      const variant = experiment.variant('blog-layout-flag');
      if (variant && variant.payload) {
        setLayoutConfig({
          layout: variant.payload.layout || 'list',
          titlePosition: variant.payload.titlePosition || 'below',
          showDescription: variant.payload.showDescription !== false,
          cardCount: variant.payload.cardCount || 5,
        });
      }
    }
    fetchExperiment();
  }, []);
  return (
    <BlogLayout
      layout={layoutConfig.layout}
      titlePosition={layoutConfig.titlePosition}
      showDescription={layoutConfig.showDescription}
      cardCount={layoutConfig.cardCount}
    />
  );
}

サーバー側の例（Node.js）

javascript

import { Experiment } from '@amplitude/experiment-node-server';
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>');
async function getExperimentConfig(userId: string) {
  const user = { user_id: userId };
  const variants = await experiment.fetch(user);
  const variant = variants['blog-layout-flag'];
  if (variant && variant.payload) {
    return {
      layout: variant.payload.layout || 'list',
      titlePosition: variant.payload.titlePosition || 'below',
      showDescription: variant.payload.showDescription !== false,
      cardCount: variant.payload.cardCount || 5,
    };
  }
  // Fallback config
  return {
    layout: 'list',
    titlePosition: 'below',
    showDescription: true,
    cardCount: 5,
  };
}
// Example usage in a route
app.get('/api/blog-config', async (req, res) => {
  const config = await getExperimentConfig(req.user.id);
  res.json(config);
});

厳密に型付けされた JSON ペイロード（詳細）

JSON ペイロードはデフォルトで柔軟です：有効な JSON を任意のバリアントに添付し、 variant.payload から読み込みます。より多くの制御を行うには、バリアントペイロードに期待されるタイプを定義することで、Amplitudeは各ペイロードがアプリケーションに到達する前に検証を行います。

厳密に型付けされたペイロードを使用すると、次のことが可能になります。

期待されるタイプは、フラグまたは実験ごとに一度設定してください。
Amplitudeの各バリアントペイロードをそのタイプと照合して検証します。
タイプが間違っている場合や必須フィールドが不足している場合など、構成上の問題を本番環境に到達する前に検出できます。

JSON ペイロードモデル

厳密に型付けされたペイロードは、このページで説明する JSON ペイロードモデルと SDK に基づいて構築されます。コード内のvariant.payloadアクセス方法は変更されません。ペイロードの形状についてより強力な保証を得ることができます。

厳密に型付けされたペイロードの使用例

厳密な型付けは次の場合に役立ちます：

複数のチームがプロダクト、エンジニアリング、ソリューションなど、同じ構成に依存しています。
ペイロードは複雑で、ネストされたオブジェクト、配列、複数のキーが含まれています。
フラグはリモート設定として、または多くの実験で共有されるレイヤーとして使用できます。
実行時エラーを減らし、構成をより安全にすることができます。

バリアントペイロードの想定されるタイプを定義する

UIで、**[ペイロードタイプを設定] **を選択して、フラグまたは実験のペイロードタイプを選択します。このタイプはすべてのバリアントに適用されます。

ペイロードタイプのオプション：

なし：タイプ強制はありません。有効なJSONをペイロードとして使用してください。
文字列: variant.payloadは文字列です。
数値：variant.payloadは数値です。
オブジェクト: variant.payloadは固定キーや型を持たないオブジェクトです。
Array: variant.payloadは配列です。
カスタムスキーマ: 特定のキーとタイプを使用してオブジェクト形状を定義します。各フィールドのタイプ (文字列、数値、論理値、配列など) を選択し、任意のフィールドを必須としてマークします。Amplitude は構造を JSON スキーマとして表現し、そのスキーマに対してすべてのバリアントペイロードを検証します。

バリアントペイロードが選択したタイプと一致しない場合:

UI にはバリアントに関するエラーが表示され、必須フィールドの欠落やタイプの誤りなど、問題が示されています。
ペイロードが有効になるまで変更を保存することはできません。
Amplitudeを使用すると、壊れた設定をデプロイすることができません。

型強制は、アプリケーションコードの検証を置き換えるのではなく、それを補完するものです:

Amplitude は、ペイロードを編集するときにペイロードタイプを強制します。
アプリケーションは、必要に応じて実行時にタイプを検証したり、タイプを絞り込むことができます。

例：カスタムスキーマ

headerText を必要とするペイロードが欲しいと仮定します:

json

{
  "buttonColor": "#4A90D9",
  "headerText": "Welcome back!",
  "maxRetries": 3,
  "features": ["dark_mode", "analytics"],
  "showBanner": true
}

Custom Schemaを選択してこれらのキーとタイプを定義すると、Amplitudeは以下と同等のJSONスキーマを使用します：

json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "buttonColor": {
      "type": "string"
    },
    "headerText": {
      "type": "string"
    },
    "maxRetries": {
      "type": "integer"
    },
    "features": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "showBanner": {
      "type": "boolean"
    }
  },
  "required": [
    "features",
    "buttonColor",
    "headerText",
    "maxRetries",
    "showBanner"
  ]
}

カスタムスキーマ内の任意のフィールドを必須としてマークします。必須フィールドを省略したり、キーに間違ったタイプを使用したりするペイロードは検証に失敗し、修正するまで保存をブロックします。

コードで強く型付けされたペイロードを使用する

強力な型設定を有効にしても、SDKの操作は同じままです。つまり、コードからペイロードを読み取りvariant.payload、独自の型を適用できます。

TypeScript では、一致する型を定義できます：

typescript

type BlogLayoutPayload = {
  layout: 'list' | 'cards' | 'grid';
  titlePosition: 'above' | 'below';
  gradient?: boolean;
  showDescription: boolean;
  cardCount: number;
};

次にキャストして使用します：

typescript

const variant = experiment.variant('blog-layout-flag');
if (variant && variant.payload) {
  const payload = variant.payload as BlogLayoutPayload;
  configureBlogLayout({
    layout: payload.layout,
    titlePosition: payload.titlePosition,
    showDescription: payload.showDescription,
    cardCount: payload.cardCount,
  });
}

Amplitude の JSON スキーマは、ペイロードを作成または編集するときにこの規約を適用します。アプリケーションは、型またはランタイムチェックを通じて同じ規約を適用します。

ベストプラクティス

これらのベストプラクティスに従って、ペイロードを堅牢かつ保守しやすい状態に保ちましょう。

1. 常にデフォルト値を提供

ペイロードのプロパティにアクセスする際には、適切なデフォルト値を提供してください。デフォルト設定により、アプリケーションは次の場合に正しく動作します。

ユーザーがバリアントを受信しない場合。
ペイロードに期待されるプロパティがありません。
実験を中止します。

例：

javascript

const layout = variant?.payload?.layout || 'list';
const cardCount = variant?.payload?.cardCount || 5;
const showDescription = variant?.payload?.showDescription !== false;

2. ペイロード構造の検証

強力に型付けされたペイロードを使用する場合でも、アプリケーション内のペイロードを検証してください：

javascript

function validateLayoutPayload(payload: any): boolean {
  const validLayouts = ['list', 'cards', 'grid'];
  if (!validLayouts.includes(payload.layout)) {
    console.error('Invalid layout in payload:', payload.layout);
    return false;
  }
  if (typeof payload.cardCount !== 'number' || payload.cardCount < 1) {
    console.error('Invalid cardCount in payload:', payload.cardCount);
    return false;
  }
  return true;
}
const variant = experiment.variant('blog-layout-flag');
if (variant?.payload && validateLayoutPayload(variant.payload)) {
  applyLayoutConfig(variant.payload);
}

AmplitudeでJSONスキーマを使用する場合は、アプリケーション側の検証をそのスキーマと一致させるようにしてください。

3. ペイロードをシンプルに保つ

ペイロード構造は構成に焦点を当ててください:

大きなペイロードを避けてください。 10KB未満を目指してください。
深く入れ子になったり、高度に結合した構造物は避けてください。
機密データを避けてください。ペイロードはネットワークトラフィックとログに表示されます。

4. ペイロードスキーマを文書化する

ペイロードの予想される構造を文書化してください。特に、複数のチームが同じフラグを操作したり実験したりする場合です。

JSDoc形式のドキュメントの例：

javascript

/**
 * Blog Layout Flag Payload Schema
 * @typedef {Object} BlogLayoutPayload
 * @property {('list'|'cards'|'grid')} layout         - The layout style
 * @property {('above'|'below')}       titlePosition  - Title position relative to content
 * @property {boolean}                 gradient       - Whether to show gradient backgrounds
 * @property {boolean}                 showDescription- Whether to show post descriptions
 * @property {number}                  cardCount      - Number of cards to display (1-10)
 */

Amplitudeで強く型付けされたペイロードを使用している場合は、JSONスキーマとコードドキュメントまたは型を同期させてください。全員が同じ契約を共有しています。

一般的なユースケース

JSONペイロードは、強力なタイピングの有無にかかわらず、幅広いユースケースをサポートします。

リモート設定

ペイロードを使用して、コードをデプロイすることなくリモートで機能を設定できます。

json

{
  "apiEndpoint": "https://api.v2.example.com",
  "timeout": 5000,
  "retries": 3,
  "enableCache": true
}

UIのカスタマイズ

色、レイアウト、テキストなどの UI 要素を設定します。

json

{
  "primaryColor": "#007AFF",
  "buttonText": "Get Started",
  "showBanner": true,
  "bannerMessage": "Limited time offer!"
}

機能のロールアウトレベル

設定フラグを使用して機能を徐々に公開します。

json

{
  "enableAdvancedSearch": true,
  "enableFilters": true,
  "maxResults": 50,
  "showRecommendations": true
}

コンテンツのバリエーション

さまざまなコンテンツアプローチをテスト：

json

{
  "headline": "Transform Your Workflow",
  "subheadline": "Get started in minutes, not hours",
  "ctaText": "Start Free Trial",
  "showTestimonials": true
}

ペイロードの可用性

SDK または Evaluation API からバリアントにアクセスする場合、value および payload プロパティを使用できます。

value: バリアントの値（"on"、"off"、"control"、"treatment" など）。
payload: 添付したJSON設定。

管理 API と Amplitude UI は、name や description といった他のバリアントプロパティを提供します。

バリアントデータモデルの詳細については、「バリアント」を参照してください。

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