Feature-Flag-Berechtigung

​

Was bereitgestellt wird

• Beim Kauf erstellt Dodo Payments die Gewährung direkt in Delivered. Sie gelangt niemals in Pending, erfordert keine Aktion des Kunden und hat keinen Bereitstellungsschritt, der fehlschlagen kann.
• Die Gewährung enthält eine typisierte feature-Nutzlast: { "feature_type": "boolean", "feature_id": "advanced_reports" }. Ihre Anwendung liest feature_id, um zu entscheiden, was freigeschaltet werden soll.
• Eine Kündigung, Rückerstattung oder manuelle Aufhebung verschiebt die Gewährung nach Revoked, und das Flag verschwindet aus den bereitgestellten Gewährungen des Kunden.

​

Ein Feature-Flag erstellen

1

Open Entitlements

Gehen Sie im Dashboard von Dodo Payments zu Entitlements und klicken Sie auf +, um eine neue Berechtigung zu erstellen. Wählen Sie anschließend Feature Flags.

2

Name the Flag

Geben Sie einen Anzeigenamen für Ihr Dashboard und Ihre Berichte sowie eine Beschreibung ein, damit Ihr Team weiß, was das Flag steuert. Die Feature ID wird von Ihrer Anwendung geprüft. Das Dashboard füllt sie anhand des Anzeigenamens aus (beispielsweise wird aus “API access” api_access), und Sie können sie bearbeiten. Sie darf keine Leerzeichen enthalten.

3

Add Metadata (Optional)

Aktivieren Sie Meta Data, um eine Schlüssel-Wert-Konfiguration wie Limits, Stufennamen oder Kontingente anzuhängen, die Ihre Anwendung zusammen mit dem Flag erhält. Klicken Sie für jedes Paar auf Add Entry. 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.

​

Mit einem Produkt verknüpfen

​

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

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

​

Limits mit Metadaten anhängen

• Eine spätere Bearbeitung der Metadaten der Berechtigung wirkt sich nur auf zukünftige Gewährungen aus. Kunden behalten die Limits, unter denen sie gekauft haben.
• Jede Gewährung gibt ihren Snapshot in ihrem Feld metadata zurück, sodass ein API-Aufruf sowohl das Flag als auch seine Konfiguration liefert.

​

Die Funktionen eines Kunden prü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",
)

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

​

Lebenszyklus

​

Webhooks

• entitlement_grant.created trifft bereits im Status Delivered mit der feature-Nutzlast ein. Aktivieren Sie die Funktion.
• entitlement_grant.delivered wird ausgelöst, wenn eine zuvor aufgehobene Gewährung wiederhergestellt wird. Aktivieren Sie die Funktion erneut.
• entitlement_grant.revoked bedeutet, dass der Zugriff entzogen wurde. Deaktivieren Sie die Funktion und prüfen Sie revocation_reason, um Ihre Nachricht auszuwählen.

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

​

Beispiel: Pro-Plan schaltet erweiterte Berichte frei

1. Erstellen Sie das Flag. Setzen Sie feature_id: advanced_reports mit den Metadaten { "tier": "pro", "monthly_report_limit": 100 }.
2. Verknüpfen Sie es mit Ihrem Abonnementprodukt für den Pro-Plan.
3. Ein Kunde abonniert. Dodo Payments erstellt eine Gewährung im Status Delivered 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 schaltet die Funktion frei. Prüfen Sie beim Laden des Dashboards den zwischengespeicherten Funktionsumfang (oder rufen Sie listEntitlementGrants auf) und rendern Sie den Tab für Berichte nur, wenn advanced_reports vorhanden ist.
5. Der Kunde kündigt. Dodo Payments hebt die Gewährung auf und löst entitlement_grant.revoked aus, woraufhin Ihr Handler die Funktion deaktiviert. Wird ein Abonnement später durch ein Mahnverfahren wiederhergestellt, aktiviert entitlement_grant.delivered die Funktion ohne Codeänderungen erneut.

​

Best Practices

• Verwenden Sie stabile Feature-IDs in snake_case. Ihr Anwendungscode prüft diese Zeichenfolgen. Eine Umbenennung ist daher auf beiden Seiten eine inkompatible Änderung.
• Verwenden Sie ein Flag pro Fähigkeit. Bevorzugen Sie advanced_reports und api_access als zwei Berechtigungen gegenüber einer einzelnen pro_bundle, damit Aufhebungen und Plankombinationen übersichtlich bleiben.
• Steuern Sie den Status über Webhooks und überprüfen Sie ihn mit der API. Webhooks halten Ihre Datenbank aktuell. Der Listenendpunkt ist die Quelle der Wahrheit für Abgleichsaufgaben und Cache-Fehltreffer.
• Behandeln Sie Revoked als sofort wirksam. Ein aufgehobenes Flag bedeutet, dass der Kunde nicht länger für die Funktion bezahlt. Sperren Sie sie bei der nächsten Anfrage, nicht erst bei der nächsten Sitzung.
• Legen Sie Limits in Metadaten statt im Code ab. Wenn Sie ein Kontingent ändern, müssen Sie anschließend nur die Berechtigung bearbeiten. Neue Kunden erhalten den neuen Wert, während bestehende Gewährungen ihren gekauften Snapshot behalten.