기능 플래그 권한

​

전달 내용

• 구매 시, 권한이 생성되어 즉시 delivered로 이동합니다. pending 단계가 없으며, 고객 행동도 없고 전달 실패 위험이 없습니다.
• 권한은 유형화된 feature 페이로드를 가집니다: { "feature_type": "boolean", "feature_id": "advanced_reports" }. 애플리케이션은 feature_id를 읽어 어떤 기능을 해제할지 결정합니다.
• 취소, 환불 또는 수동 해지는 권한을 revoked로 이동시키며, 애플리케이션에서 플래그가 사라지는 것을 봅니다.

​

기능 플래그 생성

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을 확인하여 메시지를 결정합니다.

app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;

  if (event.type.startsWith('entitlement_grant.') && event.data.feature) {
    const { customer_id, feature } = event.data;
    const enabled = event.type !== 'entitlement_grant.revoked';

    await db.customerFeatures.upsert({
      customerId: customer_id,
      featureId: feature.feature_id,
      enabled,
      config: event.data.metadata ?? {},
    });
  }

  res.sendStatus(200);
});

​

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

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가 이를 복원합니다 — 코드 변경 필요 없음.

​

모범 사례

• 안정적인 snake_case 기능 ID를 사용하세요. 애플리케이션 코드가 이 문자열을 확인합니다; 이름 변경은 양쪽에 걸쳐 파괴적인 변경입니다.
• 기능당 하나의 플래그. 단일 pro_bundle보다는 advanced_reports + api_access을 두 개의 권한으로 사용하는 것이 좋습니다 — 해지 및 계획 혼합이 깨끗하게 유지됩니다.
• 상태를 웹훅에서 구동하고 API로 확인하세요. 웹훅은 데이터베이스를 최신 상태로 유지하고, 목록 엔드포인트는 조정 작업 및 캐시 누락에 대한 진실의 출처입니다.
• revoked를 즉시 처리합니다. 해지된 플래그는 고객이 더 이상 기능에 비용을 지불하지 않음을 의미합니다. 다음 세션이 아닌 다음 요청에서 제한하십시오.
• 제한을 코드가 아닌 메타데이터에 넣습니다. 할당량을 변경하는 것은 권한을 편집하는 것만 필요합니다 — 새로운 고객은 자동으로 이를 수용하고 기존 권한은 구매한 스냅샷을 유지합니다.
• Use stable, snake_case feature ids. Your application code checks these strings; renaming one is a breaking change on both sides.
• One flag per capability. Prefer advanced_reports + api_access as two entitlements over a single pro_bundle — revocation and plan mixes stay clean.
• Drive state from webhooks, verify with the API. Webhooks keep your database current; the list endpoint is the source of truth for reconciliation jobs and cache misses.
• Treat revoked as immediate. A revoked flag means the customer is no longer paying for the feature. Gate on the next request, not the next session.
• Put limits in metadata, not in code. Changing a quota then only requires editing the entitlement — new customers pick it up automatically while existing grants keep their purchased snapshot.