إذن الراية المميزة

​

ما يتم تسليمه

• عند الشراء، تُنشأ المنحة وتنتقل مباشرة إلى delivered. لا يوجد مرحلة pending، ولا إجراء من العميل، ولا طريقة للفشل في التسليم.
• تحمل المنحة حمولة بطابع feature: { "feature_type": "boolean", "feature_id": "advanced_reports" }. يقرأ تطبيقك feature_id لتحديد ما يجب فتحه.
• الإلغاء أو الاسترداد أو الإلغاء اليدوي ينقل المنحة إلى revoked، ويختفي العلم من تطبيقك.

​

إنشاء راية مميزة

1

Open Entitlements

في لوحة التحكم Dodo Payments، اذهب إلى الأذونات وانقر على + لبدء إذن جديد، ثم اختر الرايات المميزة.

2

Name the flag

أعط الراية اسم عرض للوحة التحكم الخاصة بك، ومعرف ميزة ستتحقق منه تطبيقك (تقترح لوحة التحكم واحدًا من الاسم)، ووصف حتى يعرف فريقك ماذا يتحكم.

3

Optionally add metadata

تبديل البيانات الوصفية لإرفاق تكوين المفاتيح والقيم — الحدود، أسماء المستويات، الحصص — التي يتم تسليمها إلى تطبيقك جنبًا إلى جنب مع الراية. انظر إرفاق الحدود بالبيانات الوصفية.

4

Confirm

انقر تأكيد. تظهر الراية في قائمة الأذونات الخاصة بك، جاهزة للإرفاق بالمنتجات.

​

إرفاق بمنتج

​

التكوين المطلوب

​

الإنشاء عبر 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"),
    },
  ),
})

​

إرفاق الحدود بالبيانات الوصفية

• تحرير البيانات الوصفية للإذن لاحقًا يؤثر فقط على المنح المستقبلية. يحتفظ العملاء بالحدود التي اشتروا تحتها.
• يتم إرجاع اللقطة على كل منحة كحقلها metadata، لذا يتيح لك اتصال API واحد الحصول على الراية وتكوينها.

​

تحقق من ميزات العميل

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

​

دورة الحياة

​

خدمات الويب

• entitlement_grant.created — تصل بالفعل delivered مع حمولة feature. قم بتمكين الميزة.
• entitlement_grant.delivered — يتم تشغيلها عندما يتم استعادة منحة ملغاة مسبقًا. قم بإعادة تمكين الميزة.
• entitlement_grant.revoked — الوصول محظور. قم بتعطيل الميزة وتحقق من revocation_reason لتحديد رسائلك.

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

​

مثال: خطة Pro تفتح التقارير المتقدمة

1. أنشئ الراية. feature_id: advanced_reports مع البيانات الوصفية { "tier": "pro", "monthly_report_limit": 100 }.
2. قم بإرفاقها بمنتج الاشتراك في خطة Pro الخاصة بك.
3. اشتراك العميل. ينشئ Dodo Payments منحة delivered ويطلق entitlement_grant.created؛ يقوم معالج الويب هوك الخاص بك بتمكين advanced_reports للعميل بحد 100.
4. تطبيقك يبوّب الميزة. عند تحميل لوحة العدادات، تحقق من مجموعة الميزات المخبأة (أو اتصل بـ listEntitlementGrants) وعرض علامة التبويب للتقارير فقط عند توفر advanced_reports.
5. قام العميل بالإلغاء. يقوم Dodo Payments بإلغاء المنحة ويطلق entitlement_grant.revoked؛ يقوم معالجك بتعطيل الميزة. إذا تعافى العميل لاحقًا عبر عملية dunning، entitlement_grant.delivered تستعيدها - لا حاجة لتغيير التعليمات البرمجية.

​

أفضل الممارسات

• استخدم معرفات السمات الثابتة، الsnake_case. تتحقق تطبيقك من هذه السلاسل؛ تغيير الاسم يعد تغييرًا كسرًا على كلا الجانبين.
• علم واحد لكل قدرة. فضل advanced_reports + api_access كأذونات اثنين على راية واحدة pro_bundle — تظل المخالفة وخليط الخطط نظيفة.
• ادفع الحالة من خلال خدمات الويب، وتحقق من خلال API. تجعل الخدمات المعطاة قاعدة بياناتك محدثة؛ قائمة النقاط تكون مصدر الحقيقة لأعمال التوفيق والأخطاء في التخزين المؤقت.
• تعامل مع revoked على أنها فورية. يعني العلم الذي تم إلغاؤه أن العميل لم يعد يدفع مقابل الميزة. اعتمد على الطلب التالي، وليس الجلسة التالية.
• ضع الحدود في البيانات الوصفية، وليس في الكود. يؤدي تغيير الحصة بعد ذلك فقط إلى تحرير الإذن - يلتقط العملاء الجدد تلقائيًا بينما تحتفظ المنح الحالية بلقطة الشراء الخاصة بهم.
• Use stable, snake_case feature ids. Your application code checks these strings; renaming one is a breaking change on both sides.
• One flag per capability. Prefer advanced_reports + api_access as two entitlements over a single pro_bundle — revocation and plan mixes stay clean.
• Drive state from webhooks, verify with the API. Webhooks keep your database current; the list endpoint is the source of truth for reconciliation jobs and cache misses.
• Treat revoked as immediate. A revoked flag means the customer is no longer paying for the feature. Gate on the next request, not the next session.
• Put limits in metadata, not in code. Changing a quota then only requires editing the entitlement — new customers pick it up automatically while existing grants keep their purchased snapshot.