Quyền cấp Feature Flag

​

Những gì được cung cấp

• Khi purchase, Dodo Payments tạo grant trực tiếp ở Delivered. Grant không bao giờ chuyển sang Pending, không cần khách hàng thực hiện hành động nào và không có bước delivery nào có thể thất bại.
• Grant chứa payload feature có kiểu: { "feature_type": "boolean", "feature_id": "advanced_reports" }. Ứng dụng của bạn đọc feature_id để quyết định tính năng nào cần mở khóa.
• Khi hủy, refund hoặc revoke thủ công, grant được chuyển sang Revoked và flag biến mất khỏi các grant đã cung cấp cho khách hàng.

​

Tạo Feature Flag

1

Open Entitlements

Trong dashboard Dodo Payments, vào Entitlements và nhấp + để bắt đầu tạo entitlement mới, sau đó chọn Feature Flags.

2

Name the Flag

Nhập Display Name cho dashboard và reports của bạn, cùng Description để team biết flag kiểm soát điều gì. Feature ID là giá trị mà ứng dụng kiểm tra. Dashboard điền giá trị này từ display name (ví dụ, “API access” trở thành api_access), và bạn có thể chỉnh sửa. Giá trị này không được chứa khoảng trắng.

3

Add Metadata (Optional)

Bật Meta Data để đính kèm cấu hình key-value, chẳng hạn như giới hạn, tên tier hoặc quota, mà ứng dụng của bạn nhận được cùng với flag. Nhấp Add Entry cho từng cặp. Xem Đính kèm giới hạn bằng metadata.

4

Confirm

Nhấp vào Confirm. Flag sẽ xuất hiện trong danh sách entitlements, sẵn sàng để đính kèm vào các sản phẩm.

​

Đính kèm vào Product

​

Cấu hình bắt buộc

​

Tạo qua 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"),
    },
  ),
})

​

Đính kèm giới hạn bằng Metadata

• Việc chỉnh sửa metadata của entitlement sau đó chỉ ảnh hưởng đến các grant trong tương lai. Khách hàng vẫn giữ các giới hạn theo plan đã mua.
• Mỗi grant trả về snapshot trong field metadata, vì vậy một API call cung cấp cả flag và cấu hình của flag.

​

Kiểm tra các tính năng của khách hàng

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())
}

​

Vòng đời

​

Webhooks

• entitlement_grant.created xuất hiện khi đã ở trạng thái Delivered, cùng payload feature. Bật tính năng.
• entitlement_grant.delivered được phát khi một grant trước đó bị revoke được khôi phục. Bật lại tính năng.
• entitlement_grant.revoked cho biết quyền truy cập đã bị thu hồi. Tắt tính năng và kiểm tra revocation_reason để chọn nội dung messaging.

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

​

Ví dụ: Plan Pro mở khóa Advanced Reports

1. Tạo flag. Thiết lập feature_id: advanced_reports với metadata { "tier": "pro", "monthly_report_limit": 100 }.
2. Đính kèm flag vào product subscription Pro Plan.
3. Khách hàng đăng ký. Dodo Payments tạo grant Delivered và phát entitlement_grant.created. Webhook handler của bạn bật advanced_reports cho khách hàng với giới hạn 100.
4. Ứng dụng kiểm soát tính năng. Khi dashboard tải, kiểm tra feature set đã cache (hoặc gọi listEntitlementGrants) và chỉ render tab reports khi advanced_reports hiện diện.
5. Khách hàng hủy. Dodo Payments revoke grant và phát entitlement_grant.revoked, còn handler của bạn tắt tính năng. Nếu subscription sau đó khôi phục thông qua dunning, entitlement_grant.delivered sẽ khôi phục tính năng mà không cần thay đổi code.

​

Best Practices

• Sử dụng feature ID ổn định trong snake_case. Code của ứng dụng kiểm tra các string này, vì vậy việc đổi tên một string là breaking change ở cả hai phía.
• Sử dụng một flag cho mỗi capability. Ưu tiên advanced_reports và api_access dưới dạng hai entitlement thay vì một pro_bundle duy nhất, để việc revoke và kết hợp plan luôn rõ ràng.
• Điều khiển state từ webhooks và xác minh bằng API. Webhook giúp database của bạn luôn cập nhật. List endpoint là source of truth cho các job reconciliation và cache miss.
• Xử lý Revoked ngay lập tức. Flag đã revoke có nghĩa là khách hàng không còn trả tiền cho tính năng đó. Hãy kiểm soát từ request tiếp theo, không phải session tiếp theo.
• Đặt giới hạn trong metadata, không đặt trong code. Khi thay đổi quota, bạn chỉ cần chỉnh sửa entitlement. Khách hàng mới nhận giá trị mới, còn các grant hiện tại giữ snapshot đã mua.