Quyền cấp Feature Flag

​

Nội dung được cung cấp

• Khi mua hàng, grant được tạo và chuyển thẳng sang Delivered. Không có giai đoạn Pending, không cần khách hàng thực hiện thao tác nào và cũng không có khả năng delivery thất bại.
• Grant chứa payload có kiểu feature: { "feature_type": "boolean", "feature_id": "advanced_reports" }. Ứng dụng của bạn đọc feature_id để quyết định cần mở khóa tính năng nào.
• Khi hủy, hoàn tiền hoặc revoke thủ công, grant được chuyển sang Revoked và ứng dụng của bạn nhận thấy flag biến mất.

​

Tạo feature flag

1

Open Entitlements

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

2

Name the flag

Đặt Display Name cho flag để hiển thị trong dashboard, một Feature ID để ứng dụng kiểm tra (dashboard sẽ đề xuất ID dựa trên tên) và một Description để đội ngũ của bạn biết flag kiểm soát điều gì.

3

Optionally add metadata

Bật Meta Data để đính kèm cấu hình key-value — giới hạn, tên tier, quota — được cung cấp cho ứng dụng của bạn cùng với flag. 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 sản phẩm

​

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

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

​

Đí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 đã mua.
• Ảnh chụp được trả về trên mỗi grant dưới dạng trường metadata, nên một lần gọi API cung cấp cả flag và cấu hình của flag.

​

Kiểm tra các feature 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",
)

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

​

Vòng đời

​

Webhooks

• entitlement_grant.created — đã ở trạng thái Delivered và đi kèm payload feature. Bật tính năng.
• entitlement_grant.delivered — được kích hoạ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 — quyền truy cập bị thu hồi. Tắt tính năng và kiểm tra revocation_reason để quyết định nội dung thông báo.

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

​

Ví dụ: plan Pro mở khóa báo cáo nâng cao

1. Tạo flag. feature_id: advanced_reports với metadata { "tier": "pro", "monthly_report_limit": 100 }.
2. Gắn flag vào sản phẩm subscription Pro Plan.
3. Khách hàng đăng ký subscription. Dodo Payments tạo grant Delivered và kích hoạ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 là 100.
4. Ứng dụng kiểm soát quyền truy cập tính năng. Khi tải dashboard, kiểm tra tập tính năng đã lưu trong cache (hoặc gọi listEntitlementGrants) và chỉ render tab báo cáo khi advanced_reports hiện diện.
5. Khách hàng hủy subscription. Dodo Payments revoke grant và kích hoạt entitlement_grant.revoked; handler của bạn tắt tính năng. Nếu sau đó khách hàng khôi phục subscription thông qua dunning, entitlement_grant.delivered sẽ khôi phục tính năng — không cần thay đổi code.

​

Thực hành tốt nhất

• Sử dụng feature id ổn định, theo snake_case. Code ứng dụng của bạn kiểm tra các chuỗi này; việc đổi tên một feature id là breaking change ở cả hai phía.
• Mỗi capability một flag. Nên dùng advanced_reports + api_access làm hai entitlement thay vì một pro_bundle duy nhất — việc revoke và kết hợp các plan sẽ rõ ràng hơn.
• Điều khiển state từ webhook, xác minh bằng API. Webhook giúp database của bạn luôn cập nhật; endpoint list là nguồn dữ liệu chính xác để các job reconciliation và xử lý cache miss sử dụng.
• Xử lý Revoked ngay lập tức. Một flag đã bị revoke nghĩa là khách hàng không còn trả phí cho tính năng đó. Kiểm soát quyền truy cập ở 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 sẽ tự động nhận giá trị này, trong khi các grant hiện có vẫn giữ snapshot đã mua.