기능 플래그 권한

​

전달 내용

• 구매 시 grant가 생성되고 즉시 Delivered로 이동합니다. Pending 단계가 없으며, 고객 작업도 필요하지 않고 delivery가 실패할 수도 없습니다.
• grant에는 타입이 지정된 feature payload가 포함됩니다: { "feature_type": "boolean", "feature_id": "advanced_reports" }. 애플리케이션은 feature_id을 읽어 어떤 기능을 잠금 해제할지 결정합니다.
• 취소, 환불 또는 수동 revoke가 발생하면 grant는 Revoked로 이동하며, 애플리케이션에서는 해당 flag가 사라진 것을 확인할 수 있습니다.

​

기능 플래그 생성

1

Open Entitlements

Dodo Payments 대시보드에서 권한으로 이동하여 **+**를 클릭하여 새 권한을 시작한 다음, 기능 플래그를 선택합니다.

2

Name the flag

대시보드에 표시될 표시 이름, 애플리케이션이 확인할 기능 ID(이름에서 하나를 제안함), 팀이 제어하는 내용을 알 수 있는 설명을 플래그에 입력하세요.

3

Optionally add metadata

메타 데이터를 전환하여 플래그와 함께 애플리케이션에 전달될 키 값 구성을 첨부하세요 — 제한, 등급 이름, 할당량 등. Attach limits with metadata를 참조하세요.

4

Confirm

확인을 클릭합니다. 플래그는 제품에 붙이기 위해 권한 목록에 나타납니다.

​

제품에 첨부

​

필수 구성

​

API를 통한 생성

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
  environment: 'test_mode',
});

const entitlement = await client.entitlements.create({
  name: 'Advanced Reports',
  integration_type: 'feature_flag',
  integration_config: {
    feature_type: 'boolean',
    feature_id: 'advanced_reports',
  },
  metadata: {
    tier: 'pro',
    monthly_report_limit: 100,
  },
});

client.entitlements.create(
    name="Advanced Reports",
    integration_type="feature_flag",
    integration_config={
        "feature_type": "boolean",
        "feature_id": "advanced_reports",
    },
    metadata={
        "tier": "pro",
        "monthly_report_limit": 100,
    },
)

client.Entitlements.New(ctx, dodopayments.EntitlementNewParams{
  Name:            dodopayments.F("Advanced Reports"),
  IntegrationType: dodopayments.F(dodopayments.EntitlementIntegrationTypeFeatureFlag),
  IntegrationConfig: dodopayments.F[dodopayments.IntegrationConfigUnionParam](
    dodopayments.IntegrationConfigFeatureFlagConfigParam{
      FeatureType: dodopayments.F(dodopayments.FeatureTypeBoolean),
      FeatureID:   dodopayments.F("advanced_reports"),
    },
  ),
})

​

메타데이터로 제한 부착

• 나중에 권한 메타데이터를 수정해도 미래 권한에만 영향을 미칩니다. 고객은 구매한 한도치를 유지합니다.
• 스냅샷은 권한의 metadata 필드로 반환됩니다. 따라서 하나의 API 호출은 플래그 및 그 구성을 모두 제공합니다.

​

고객의 기능 확인

const features = new Map<string, Record<string, unknown>>();

for await (const grant of client.customers.listEntitlementGrants('cus_abc123', {
  integration_type: 'feature_flag',
  status: 'Delivered',
})) {
  if (grant.feature) {
    features.set(grant.feature.feature_id, grant.metadata ?? {});
  }
}

if (features.has('advanced_reports')) {
  const limit = features.get('advanced_reports')?.monthly_report_limit;
  // unlock the dashboard, enforce the limit
}

page = client.customers.list_entitlement_grants(
    customer_id="cus_abc123",
    integration_type="feature_flag",
    status="Delivered",
)

features = {
    grant.feature.feature_id: grant.metadata
    for grant in page.items
    if grant.feature
}

if "advanced_reports" in features:
    limit = features["advanced_reports"].get("monthly_report_limit")

page, _ := client.Customers.ListEntitlementGrants(
  ctx, "cus_abc123",
  dodopayments.CustomerListEntitlementGrantsParams{
    IntegrationType: dodopayments.F("feature_flag"),
    Status:          dodopayments.F("Delivered"),
  },
)

features := map[string]bool{}
for _, grant := range page.Items {
  if grant.Feature.FeatureID != "" {
    features[grant.Feature.FeatureID] = true
  }
}

​

라이프사이클

​

웹훅

• entitlement_grant.created — 이미 delivered 상태로 feature 페이로드와 함께 도착합니다. 기능을 활성화합니다.
• entitlement_grant.delivered — 이전에 해지된 권한이 복구될 때 실행됩니다. 기능을 다시 활성화합니다.
• entitlement_grant.revoked — 접근이 철회되었습니다. 기능을 비활성화하고 revocation_reason을 확인하여 메시지를 결정합니다.
• entitlement_grant.created — 이미 Delivered 상태이며 feature payload가 포함된 채 도착합니다. 기능을 활성화합니다.
• entitlement_grant.delivered — 이전에 revoke된 grant가 복원될 때 발생합니다. 기능을 다시 활성화합니다.
• entitlement_grant.revoked — 액세스가 철회되었습니다. 기능을 비활성화하고 revocation_reason을 확인하여 사용자에게 표시할 메시지를 결정합니다.

​

예제: 프로 플랜이 고급 보고서 해제

1. 플래그 생성. feature_id: advanced_reports과 메타데이터 { "tier": "pro", "monthly_report_limit": 100 }.
2. 프로 플랜 구독 제품에 첨부합니다.
3. 고객이 구독합니다. Dodo Payments가 delivered 권한을 생성하고 entitlement_grant.created를 실행합니다. 웹훅 핸들러는 100의 한도로 고객을 위해 advanced_reports을 활성화합니다.
4. 앱이 기능을 제어합니다. 대시보드가 로드될 때 캐시된 기능 세트를 확인하고(listEntitlementGrants 호출) advanced_reports가 있을 때만 보고서 탭을 렌더링합니다.
5. 고객이 취소합니다. Dodo Payments가 권한을 해지하고 entitlement_grant.revoked를 실행하여 핸들러가 기능을 비활성화합니다. 나중에 고객이 비용 추심을 통해 복구되면, entitlement_grant.delivered가 이를 복원합니다 — 코드 변경 필요 없음.
6. Flag를 생성합니다. feature_id: advanced_reports에 metadata { "tier": "pro", "monthly_report_limit": 100 }를 추가합니다.
7. Flag를 Pro Plan subscription product에 연결합니다.
8. 고객이 구독합니다. Dodo Payments가 Delivered grant를 생성하고 entitlement_grant.created를 발생시킵니다. webhook handler는 고객에게 advanced_reports을 100개 한도로 활성화합니다.
9. 앱에서 기능 접근을 제어합니다. Dashboard를 로드할 때 캐시된 feature set을 확인하거나 listEntitlementGrants을 호출하고, advanced_reports이 있는 경우에만 reports tab을 렌더링합니다.
10. 고객이 취소합니다. Dodo Payments가 grant를 revoke하고 entitlement_grant.revoked를 발생시킵니다. handler는 기능을 비활성화합니다. 이후 고객이 dunning을 통해 복구되면 entitlement_grant.delivered가 기능을 복원하므로 코드를 변경할 필요가 없습니다.

​

모범 사례

• 안정적인 snake_case 기능 ID를 사용하세요. 애플리케이션 코드가 이 문자열을 확인합니다; 이름 변경은 양쪽에 걸쳐 파괴적인 변경입니다.
• 기능당 하나의 플래그. 단일 pro_bundle보다는 advanced_reports + api_access을 두 개의 권한으로 사용하는 것이 좋습니다 — 해지 및 계획 혼합이 깨끗하게 유지됩니다.
• 상태를 웹훅에서 구동하고 API로 확인하세요. 웹훅은 데이터베이스를 최신 상태로 유지하고, 목록 엔드포인트는 조정 작업 및 캐시 누락에 대한 진실의 출처입니다.
• revoked를 즉시 처리합니다. 해지된 플래그는 고객이 더 이상 기능에 비용을 지불하지 않음을 의미합니다. 다음 세션이 아닌 다음 요청에서 제한하십시오.
• 제한을 코드가 아닌 메타데이터에 넣습니다. 할당량을 변경하는 것은 권한을 편집하는 것만 필요합니다 — 새로운 고객은 자동으로 이를 수용하고 기존 권한은 구매한 스냅샷을 유지합니다.
• 안정적인 snake_case feature id를 사용합니다. 애플리케이션 코드는 이러한 문자열을 확인하므로 하나의 이름을 변경하면 양쪽 모두에서 breaking change가 발생합니다.
• 기능 하나당 flag 하나를 사용합니다. 단일 pro_bundle보다 advanced_reports + api_access를 두 개의 entitlement로 사용하는 방식을 권장합니다. 이렇게 하면 revoke와 plan 조합을 깔끔하게 유지할 수 있습니다.
• Webhook으로 상태를 관리하고 API로 검증합니다. Webhook은 database를 최신 상태로 유지하며, list endpoint는 reconciliation job과 cache miss를 처리할 때 source of truth 역할을 합니다.
• Revoked를 즉시 처리합니다. revoke된 flag는 고객이 더 이상 해당 기능에 비용을 지불하지 않는다는 의미입니다. 다음 session이 아니라 다음 request에서 접근을 제어합니다.
• Limit은 코드가 아니라 metadata에 저장합니다. Quota를 변경할 때 entitlement만 편집하면 되므로, 신규 고객은 자동으로 변경 사항을 적용받고 기존 grant는 구매 당시의 snapshot을 유지합니다.