이 페이지에서

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

JSON 페이로드

JSON 페이로드는 실험 변형에 동적 구성 데이터를 첨부합니다. 페이로드를 사용하여 코드를 재배포하지 않고도 애플리케이션의 동작이나 모양을 원격으로 변경할 수 있습니다.

강력하게 유형화된 페이로드를 사용하면 스키마를 정의할 수 있으므로 Amplitude는 각 페이로드가 애플리케이션에 도달하기 전에 이를 검증합니다.

JSON 페이로드의 작동 방식

변형을 생성할 때 애플리케이션에 전달하려는 전체 변수를 포함하는 JSON 페이로드를 첨부할 수 있습니다.

응용 프로그램이 실험을 평가할 때:

  • 실험 SDK는 사용자를 위해 변형을 가져옵니다.
  • SDK는 해당 페이로드와 함께 변형을 반환합니다.
  • 애플리케이션은 페이로드를 읽고 경험을 동적으로 구성합니다.

이 패턴은 단순한 플래그와 페이로드가 레이아웃, 기능 옵션, 문구 또는 구성 값을 정의하는 복잡한 실험에 적합합니다.

워크플로 요약

일반적인 워크플로우는 다음 단계를 따릅니다.

  1. 페이로드를 포함한 변형 생성하기: 해당 경험의 구성을 정의하는 변형에 JSON 객체를 추가하세요.
  2. 플래그 활성화 또는 실험: 사용자에게 구성을 배포하십시오.
  3. 애플리케이션에서 평가하기: 실험 SDK(웹, 모바일 또는 백엔드)를 사용하여 각 사용자의 변형을 가져옵니다.
  4. 페이로드 사용: 구성을 읽고 UI 또는 비즈니스 로직에 적용합니다.variant.payload

페이로드를 사용하여 변형 생성

Amplitude UI를 통해 또는 실험 API 관리를 통해 프로그래밍 방식으로 JSON 페이로드를 변형에 추가하세요.

UI를 통해

변형을 생성하거나 편집할 때 페이로드를 추가하려면 다음과 같이 하십시오.

  1. 실험 > 기능 플래그 또는 실험으로 이동합니다.
  2. 구성하려는 플래그 또는 실험을 선택합니다.
  3. [변형] 섹션에서 변형을 생성하거나 편집합니다.
  4. 변형 이름, 값 및 설명을 입력합니다.
  5. 페이로드 필드에 JSON 구성을 추가하세요.
  6. 적용을 선택한 다음 변경 사항을 저장합니다.

페이로드 예제 – 블로그 레이아웃에 대한 구성

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 문서를 참조하십시오.

애플리케이션의 페이로드에 액세스

페이로드가 있는 변형을 생성한 후 애플리케이션은 다음을 수행해야 합니다.

  1. 실험 SDK를 초기화합니다.
  2. 사용자를 위한 변형을 가져옵니다.
  3. 액세스 variant.payload.
  4. 합리적인 기본값을 사용하여 구성을 적용하십시오.

정확한 구문은 SDK에 따라 다르지만 패턴은 일관적으로 유지됩니다.

자바스크립트/타입스크립트(브라우저)

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
}

사용자 지정 스키마를 선택하고 이러한 키와 유형을 정의할 때, 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 또는 평가 API에서 변형에 액세스할 때 value및 payload 속성을 사용할 수 있습니다.

  • value: 변형의 값입니다. 예를 들어 "켜기", "끄기", "제어", "처리"등입니다.
  • payload: 첨부한 JSON 구성입니다.

Management API 및 Amplitude UI는 name및 description과 같은 다른 변형 속성을 제공합니다.

변형 데이터 모델에 대한 자세한 내용은 변형으로 이동하십시오.

이 내용이 도움이 되었나요?