기능 플래그 권한

​

제공되는 항목

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

​

Feature Flag 생성

1

Open Entitlements

Dodo Payments dashboard에서 Entitlements로 이동하고 **+**를 클릭하여 새 entitlement 생성을 시작한 다음 Feature Flags를 선택합니다.

2

Name the Flag

dashboard와 reports에 표시할 Display Name을 입력하고, 팀에서 flag가 제어하는 항목을 알 수 있도록 Description을 입력합니다. Feature ID는 애플리케이션에서 확인하는 값입니다. dashboard는 display name에서 값을 채웁니다(예: “API access”는 api_access가 됨). 이 값을 편집할 수도 있습니다. 공백은 포함할 수 없습니다.

3

Add Metadata (Optional)

Meta Data를 켜면 애플리케이션이 flag와 함께 받는 key-value configuration을 연결할 수 있습니다. 예를 들면 limits, tier names 또는 quotas가 있습니다. 각 쌍마다 Add Entry를 클릭합니다. 메타데이터로 limits 연결을 참조하세요.

4

Confirm

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

​

Product에 연결

​

필수 Configuration

​

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,
  },
});

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)

entitlement = 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 is a *dodopayments.Client, for example from
// dodopayments.NewClient(option.WithEnvironmentTestMode()); ctx is a context.Context.
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로 Limits 연결

• 이후 entitlement의 metadata를 편집해도 future grants에만 영향을 줍니다. 고객은 구매 당시의 limits를 그대로 유지합니다.
• 각 grant는 metadata field에 snapshot을 반환하므로 API call 한 번으로 flag와 configuration을 모두 가져올 수 있습니다.

​

Customer의 Features 확인

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",
)

# Iterating the page fetches every page of results.
features = {
    grant.feature.feature_id: grant.metadata
    for grant in page
    if grant.feature
}

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

iter := client.Customers.ListEntitlementGrantsAutoPaging(
  ctx, "cus_abc123",
  dodopayments.CustomerListEntitlementGrantsParams{
    IntegrationType: dodopayments.F(dodopayments.CustomerListEntitlementGrantsParamsIntegrationTypeFeatureFlag),
    Status:          dodopayments.F(dodopayments.CustomerListEntitlementGrantsParamsStatusDelivered),
  },
)

features := map[string]bool{}
for iter.Next() {
  grant := iter.Current()
  if grant.Feature.FeatureID != "" {
    features[grant.Feature.FeatureID] = true
  }
}
if err := iter.Err(); err != nil {
  panic(err.Error())
}

​

라이프사이클

​

웹훅

• entitlement_grant.created는 이미 Delivered 상태로 도착하며 feature payload를 포함합니다. feature를 활성화합니다.
• entitlement_grant.delivered는 이전에 revoked된 grant가 복원될 때 발생합니다. feature를 다시 활성화합니다.
• entitlement_grant.revoked는 access가 철회되었음을 의미합니다. feature를 비활성화하고 revocation_reason를 확인하여 사용자에게 표시할 메시지를 선택합니다.

import express from 'express';
import DodoPayments from 'dodopayments';

// Reads DODO_PAYMENTS_API_KEY and DODO_PAYMENTS_WEBHOOK_KEY from the environment.
const client = new DodoPayments({ environment: 'test_mode' });
const app = express();

app.post('/webhooks/dodo', express.raw({ type: 'application/json' }), async (req, res) => {
  let event: DodoPayments.UnwrapWebhookEvent;
  try {
    event = client.webhooks.unwrap(req.body.toString(), {
      headers: req.headers as Record<string, string>,
    });
  } catch {
    res.sendStatus(400); // invalid signature
    return;
  }

  const grant = 'feature' in event.data ? event.data : null;

  if (event.type.startsWith('entitlement_grant.') && grant?.feature) {
    const enabled = event.type !== 'entitlement_grant.revoked';

    // db is your application's database client.
    await db.customerFeatures.upsert({
      customerId: grant.customer_id,
      featureId: grant.feature.feature_id,
      enabled,
      config: grant.metadata ?? {},
    });
  }

  res.sendStatus(200);
});

​

예제: Pro Plan으로 Advanced Reports 잠금 해제

1. flag를 생성합니다. feature_id: advanced_reports를 설정하고 metadata { "tier": "pro", "monthly_report_limit": 100 }를 추가합니다.
2. 연결합니다. Pro Plan subscription product에 flag를 연결합니다.
3. 고객이 subscription을 시작합니다. Dodo Payments가 Delivered grant를 생성하고 entitlement_grant.created를 발생시킵니다. webhook handler는 고객에 대해 advanced_reports를 활성화하고 limit를 100으로 설정합니다.
4. 앱이 feature를 gate합니다. dashboard를 로드할 때 cached feature set을 확인하거나(또는 listEntitlementGrants를 호출하여) advanced_reports가 있을 때만 reports tab을 렌더링합니다.
5. 고객이 취소합니다. Dodo Payments가 grant를 revoke하고 entitlement_grant.revoked를 발생시키면 handler가 feature를 비활성화합니다. 이후 subscription이 dunning을 통해 복구되면 entitlement_grant.delivered가 code 변경 없이 feature를 복원합니다.

​

모범 사례

• snake_case에서 stable feature IDs를 사용하세요. 애플리케이션 code가 이 strings를 확인하므로 하나의 이름을 변경하면 양쪽 모두에서 breaking change가 발생합니다.
• capability당 하나의 flag를 사용하세요. 단일 pro_bundle보다 advanced_reports와 api_access를 두 개의 entitlements로 사용하는 편이 좋습니다. 그래야 revoke와 plan combinations를 깔끔하게 유지할 수 있습니다.
• webhooks로 state를 구동하고 API로 확인하세요. Webhooks는 database를 최신 상태로 유지합니다. list endpoint는 reconciliation jobs와 cache misses를 위한 source of truth입니다.
• Revoked를 즉시 적용되는 것으로 처리하세요. revoked flag는 고객이 더 이상 해당 feature에 대해 payment하지 않음을 의미합니다. 다음 session이 아니라 다음 request에서 gate하세요.
• limits는 code가 아닌 metadata에 넣으세요. quota를 변경할 때 entitlement만 편집하면 됩니다. 신규 고객은 새 값을 받고 기존 grants는 구매 당시의 snapshot을 유지합니다.