Hak Fitur Bendera

​

Apa yang Dikirimkan

• Saat pembelian, Dodo Payments membuat grant langsung di Delivered. Grant tidak pernah masuk ke Pending, tidak memerlukan tindakan pelanggan, dan tidak memiliki langkah pengiriman yang dapat gagal.
• Grant membawa payload feature bertipe: { "feature_type": "boolean", "feature_id": "advanced_reports" }. Aplikasi Anda membaca feature_id untuk menentukan fitur yang akan dibuka.
• Pembatalan, pengembalian dana, atau pencabutan manual memindahkan grant ke Revoked, dan flag tersebut menghilang dari grant yang dikirimkan kepada pelanggan.

​

Membuat Feature Flag

1

Open Entitlements

Di dashboard Dodo Payments, buka Entitlements dan klik + untuk memulai entitlement baru, lalu pilih Feature Flags.

2

Name the Flag

Masukkan Display Name untuk dashboard dan laporan Anda, serta Description agar tim Anda mengetahui fungsi flag tersebut. Feature ID adalah nilai yang diperiksa aplikasi Anda. Dashboard mengisinya berdasarkan nama tampilan (misalnya, “API access” menjadi api_access), dan Anda dapat mengeditnya. Nilai ini tidak boleh berisi spasi.

3

Add Metadata (Optional)

Aktifkan Meta Data untuk melampirkan konfigurasi key-value, seperti batas, nama tingkatan, atau kuota, yang diterima aplikasi Anda bersama flag. Klik Add Entry untuk setiap pasangan. Lihat Melampirkan batas dengan metadata.

4

Confirm

Klik Confirm. Bendera muncul di daftar hak Anda, siap dilampirkan ke produk.

​

Melampirkan ke Produk

​

Konfigurasi yang Diperlukan

​

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

​

Melampirkan Batas dengan Metadata

• Mengedit metadata entitlement setelahnya hanya memengaruhi grant di masa mendatang. Pelanggan tetap menggunakan batas yang mereka beli.
• Setiap grant mengembalikan snapshot-nya di field metadata, sehingga satu panggilan API memberi Anda flag beserta konfigurasinya.

​

Memeriksa Fitur Pelanggan

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

​

Siklus hidup

​

Webhooks

• entitlement_grant.created tiba dalam keadaan sudah Delivered, dengan payload feature. Aktifkan fitur tersebut.
• entitlement_grant.delivered dipicu saat grant yang sebelumnya dicabut dipulihkan. Aktifkan kembali fitur tersebut.
• entitlement_grant.revoked berarti akses telah ditarik. Nonaktifkan fitur tersebut, dan periksa revocation_reason untuk menentukan pesan Anda.

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

​

Contoh: Paket Pro Membuka Laporan Lanjutan

1. Buat flag. Tetapkan feature_id: advanced_reports dengan metadata { "tier": "pro", "monthly_report_limit": 100 }.
2. Lampirkan flag tersebut ke produk subscription Pro Plan Anda.
3. Pelanggan berlangganan. Dodo Payments membuat grant Delivered dan memicu entitlement_grant.created. Handler webhook Anda mengaktifkan advanced_reports untuk pelanggan dengan batas 100.
4. Aplikasi Anda membatasi fitur tersebut. Saat dashboard dimuat, periksa kumpulan fitur yang di-cache (atau panggil listEntitlementGrants) dan tampilkan tab laporan hanya ketika advanced_reports tersedia.
5. Pelanggan membatalkan subscription. Dodo Payments mencabut grant dan memicu entitlement_grant.revoked, lalu handler Anda menonaktifkan fitur tersebut. Jika subscription kemudian pulih melalui dunning, entitlement_grant.delivered memulihkan fitur tanpa perubahan kode.

​

Praktik Terbaik

• Gunakan ID fitur yang stabil di snake_case. Kode aplikasi Anda memeriksa string ini, sehingga mengganti namanya merupakan perubahan yang merusak di kedua sisi.
• Gunakan satu flag per kapabilitas. Pilih advanced_reports dan api_access sebagai dua entitlement daripada satu pro_bundle, agar pencabutan dan kombinasi paket tetap rapi.
• Dorong status dari webhook, lalu verifikasi dengan API. Webhook menjaga database Anda tetap terkini. Endpoint daftar merupakan sumber kebenaran untuk pekerjaan rekonsiliasi dan cache miss.
• Perlakukan Revoked sebagai tindakan segera. Flag yang dicabut berarti pelanggan tidak lagi membayar fitur tersebut. Terapkan pembatasan pada request berikutnya, bukan sesi berikutnya.
• Tempatkan batas di metadata, bukan di kode. Mengubah kuota kemudian hanya memerlukan pengeditan entitlement. Pelanggan baru mendapatkan nilai baru, dan grant yang sudah ada tetap menyimpan snapshot yang mereka beli.