Feature-Flag-Berechtigung

​

Was geliefert wird

• Beim Kauf wird der Grant erstellt und wechselt direkt zu Delivered. Es gibt keine Phase Pending, keine Aktion des Kunden und keine Möglichkeit, dass die Bereitstellung fehlschlägt.
• Der Grant enthält eine typisierte feature-Payload: { "feature_type": "boolean", "feature_id": "advanced_reports" }. Ihre Anwendung liest feature_id, um zu entscheiden, was freigeschaltet werden soll.
• Durch eine Stornierung, Rückerstattung oder manuelle Aufhebung wechselt der Grant zu Revoked, und Ihre Anwendung erkennt, dass das Flag nicht mehr vorhanden ist.

​

Erstellen eines Feature-Flags

1

Open Entitlements

Gehen Sie in Ihrem Dodo Payments-Dashboard zu Berechtigungen und klicken Sie auf +, um eine neue Berechtigung zu starten, und wählen Sie dann Feature Flags.

2

Name the flag

Geben Sie dem Flag einen Anzeigenamen für Ihr Dashboard, eine Feature-ID, die Ihre Anwendung überprüfen wird (das Dashboard schlägt eine basierend auf dem Namen vor), und eine Beschreibung, damit Ihr Team weiß, was es steuert.

3

Optionally add metadata

Schalten Sie Meta-Daten ein, um Schlüssel-Wert-Konfigurationen — Limits, Tiernamen, Quoten — zu verknüpfen, die Ihrer Anwendung zusammen mit dem Flag geliefert werden. Siehe Limits mit Metadaten anhängen.

4

Confirm

Klicken Sie auf Bestätigen. Das Flag erscheint in Ihrer Berechtigungsliste, bereit, mit Produkten verknüpft zu werden.

​

An ein Produkt anhängen

​

Erforderliche Konfiguration

​

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

​

Limits mit Metadaten anhängen

• Das spätere Bearbeiten der Metadaten der Berechtigung betrifft nur zukünftige Berechtigungen. Kunden behalten die Limits, unter denen sie erworben haben.
• Der Schnappschuss wird bei jeder Berechtigung als sein Feld metadata zurückgegeben, sodass ein API-Aufruf sowohl das Flag als auch die Konfiguration liefert.

​

Features eines Kunden überprüfen

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

​

Lebenszyklus

​

Webhooks

• entitlement_grant.created — kommt bereits als Delivered mit der feature-Payload an. Aktivieren Sie das Feature.
• entitlement_grant.delivered — wird ausgelöst, wenn ein zuvor aufgehobener Grant wiederhergestellt wird. Aktivieren Sie das Feature erneut.
• entitlement_grant.revoked — Zugriff entzogen. Deaktivieren Sie das Feature und prüfen Sie revocation_reason, um Ihre Kommunikation festzulegen.

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

​

Beispiel: Pro-Plan schaltet erweiterte Berichte frei

1. Erstellen Sie das Flag. feature_id: advanced_reports mit den Metadaten { "tier": "pro", "monthly_report_limit": 100 }.
2. Verknüpfen Sie es mit Ihrem Abonnementprodukt Pro Plan.
3. Ein Kunde abonniert. Dodo Payments erstellt einen Delivered-Grant und löst entitlement_grant.created aus; Ihr Webhook-Handler aktiviert advanced_reports für den Kunden mit einem Limit von 100.
4. Ihre Anwendung steuert den Feature-Zugriff. Prüfen Sie beim Laden des Dashboards das zwischengespeicherte Feature-Set (oder rufen Sie listEntitlementGrants auf) und rendern Sie den Berichte-Tab nur, wenn advanced_reports vorhanden ist.
5. Der Kunde kündigt. Dodo Payments hebt den Grant auf und löst entitlement_grant.revoked aus; Ihr Handler deaktiviert das Feature. Wenn der Kunde später durch Dunning wiederhergestellt wird, aktiviert entitlement_grant.delivered es erneut – es sind keine Codeänderungen erforderlich.

​

Best Practices

• Verwenden Sie stabile Feature-IDs im snake_case-Format. Ihr Anwendungscode prüft diese Zeichenfolgen; die Umbenennung einer ID ist auf beiden Seiten eine Breaking Change.
• Ein Flag pro Funktion. Bevorzugen Sie advanced_reports + api_access als zwei Entitlements gegenüber einem einzelnen pro_bundle – Aufhebungen und Kombinationen von Plänen bleiben übersichtlich.
• Steuern Sie den Status über Webhooks und verifizieren Sie ihn mit der API. Webhooks halten Ihre Datenbank aktuell; der Listen-Endpunkt ist die maßgebliche Quelle für Abgleich-Jobs und Cache-Misses.
• Behandeln Sie Revoked als sofort wirksam. Ein aufgehobenes Flag bedeutet, dass der Kunde nicht mehr für das Feature bezahlt. Steuern Sie den Zugriff bei der nächsten Anfrage, nicht erst bei der nächsten Sitzung.
• Legen Sie Limits in den Metadaten statt im Code fest. Wenn Sie ein Kontingent ändern, müssen Sie anschließend nur das Entitlement bearbeiten – neue Kunden übernehmen es automatisch, während bestehende Grants ihren erworbenen Snapshot behalten.