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 và không có khả năng phân phối 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 nội dung cần mở khóa.
• Khi hủy, hoàn tiền hoặc thu hồi thủ công, grant 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 khi đến nơi, cùng payload feature. Bật feature.
• entitlement_grant.delivered — được phát khi một grant trước đó đã bị thu hồi được khôi phục. Bật lại feature.
• entitlement_grant.revoked — quyền truy cập bị rút. Tắt feature 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. Đính kèm flag vào sản phẩm 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 feature. Khi tải dashboard, kiểm tra tập hợp feature đã cache (hoặc gọi listEntitlementGrants) và chỉ hiển thị tab báo cáo khi có advanced_reports.
5. Khách hàng hủy. Dodo Payments thu hồi grant và phát entitlement_grant.revoked; handler của bạn tắt feature. Nếu sau đó khách hàng khôi phục subscription qua dunning, entitlement_grant.delivered sẽ khôi phục feature — không cần thay đổi code.

​

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

• 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 chuỗi là thay đổi breaking ở cả hai phía.
• Mỗi capability dùng một flag. Ưu tiên advanced_reports + api_access dưới dạng hai entitlement thay vì một pro_bundle duy nhất — việc thu hồi và kết hợp các plan sẽ rõ ràng hơn.
• Điều khiển trạng thái từ webhooks, xác minh bằng API. Webhooks giữ cho cơ sở dữ liệu luôn được cập nhật; endpoint list là nguồn dữ liệu chính xác để reconciliation job và xử lý cache miss.
• Xử lý revoked ngay lập tức. Flag bị thu hồi nghĩa là khách hàng không còn trả tiền cho feature. Hãy kiểm soá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 sẽ tự động nhận giới hạn mới, trong khi các grant hiện tại giữ nguyên ảnh chụp đã mua.