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

​

ما يتم تسليمه

• عند إتمام عملية الشراء، يتم إنشاء المنحة وتنتقل مباشرةً إلى 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 لتحديد رسائلك.
• entitlement_grant.created — تصل وهي بالفعل في Delivered مع حمولة feature. فعّل الميزة.
• entitlement_grant.delivered — يتم إطلاقه عند استعادة منحة أُلغيت سابقًا. أعد تفعيل الميزة.
• entitlement_grant.revoked — تم سحب صلاحية الوصول. عطّل الميزة وتحقق من revocation_reason لتحديد الرسالة المناسبة.

​

مثال: خطة 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 تستعيدها - لا حاجة لتغيير التعليمات البرمجية.
6. أنشئ العلامة. feature_id: advanced_reports مع البيانات الوصفية { "tier": "pro", "monthly_report_limit": 100 }.
7. أرفقها بمنتج اشتراك Pro Plan.
8. يشترك أحد العملاء. تنشئ Dodo Payments منحة Delivered وتطلق entitlement_grant.created؛ ويمكّن معالج webhook لديك advanced_reports للعميل بحد أقصى قدره 100.
9. يتحكم تطبيقك في الوصول إلى الميزة. عند تحميل لوحة المعلومات، تحقّق من مجموعة الميزات المخزّنة مؤقتًا (أو استدعِ listEntitlementGrants) واعرض علامة تبويب التقارير فقط عندما تكون advanced_reports موجودة.
10. يلغي العميل اشتراكه. تلغي Dodo Payments المنحة وتطلق entitlement_grant.revoked؛ ويعطّل معالجك الميزة. وإذا استعاد العميل اشتراكه لاحقًا عبر عملية التحصيل المتأخر، فإن entitlement_grant.delivered يستعيدها — ولا حاجة إلى إجراء تغييرات على التعليمات البرمجية.

​

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

• استخدم معرفات السمات الثابتة، الsnake_case. تتحقق تطبيقك من هذه السلاسل؛ تغيير الاسم يعد تغييرًا كسرًا على كلا الجانبين.
• علم واحد لكل قدرة. فضل advanced_reports + api_access كأذونات اثنين على راية واحدة pro_bundle — تظل المخالفة وخليط الخطط نظيفة.
• ادفع الحالة من خلال خدمات الويب، وتحقق من خلال API. تجعل الخدمات المعطاة قاعدة بياناتك محدثة؛ قائمة النقاط تكون مصدر الحقيقة لأعمال التوفيق والأخطاء في التخزين المؤقت.
• تعامل مع revoked على أنها فورية. يعني العلم الذي تم إلغاؤه أن العميل لم يعد يدفع مقابل الميزة. اعتمد على الطلب التالي، وليس الجلسة التالية.
• ضع الحدود في البيانات الوصفية، وليس في الكود. يؤدي تغيير الحصة بعد ذلك فقط إلى تحرير الإذن - يلتقط العملاء الجدد تلقائيًا بينما تحتفظ المنح الحالية بلقطة الشراء الخاصة بهم.
• استخدم معرّفات ميزات ثابتة بنمط snake_case. يتحقق كود تطبيقك من هذه السلاسل؛ وإعادة تسمية إحداها تُعد تغييرًا يؤدي إلى كسر التوافق من كلا الجانبين.
• علامة واحدة لكل قدرة. فضّل advanced_reports + api_access كاستحقاقين بدلًا من pro_bundle واحد — إذ يظل الإلغاء ومزيج الخطط منظّمين.
• اعتمد على حالة webhooks، وتحقق باستخدام API. تحافظ webhooks على تحديث قاعدة بياناتك؛ وتُعد نقطة نهاية القائمة مصدر الحقيقة لمهام التسوية وحالات فقدان ذاكرة التخزين المؤقت.
• تعامل مع Revoked على أنه فوري. تعني العلامة المُلغاة أن العميل لم يعد يدفع مقابل الميزة. طبّق التحكم في الوصول عند الطلب التالي، لا عند الجلسة التالية.
• ضع الحدود في البيانات الوصفية، وليس في الكود. لا يتطلب تغيير الحصة بعد ذلك سوى تعديل الاستحقاق — إذ يحصل العملاء الجدد عليها تلقائيًا، بينما تحتفظ المنح الحالية بلقطة المشتريات الخاصة بها.