إضافة اشتراكات Discourse

[SubStrider]

[دليل] كيفية إعداد اشتراكات Discourse باستخدام جداول أسعار Stripe (والعقبات الشائعة)

مرحباً بالجميع،

بعد عملية استكشاف أخطاء طويلة، أردت مشاركة دليل نهائي لإعداد المكون الإضافي الرسمي discourse-subscriptions باستخدام طريقة جدول أسعار Stripe الحديثة. هذا النهج قوي ولكنه يحتوي على بعض الخطوات الحاسمة التي ليست واضحة على الفور ويمكن أن تؤدي إلى أخطاء مثل فشل webhooks (404 Not Found) أو عدم إضافة المستخدمين إلى المجموعات بعد دفع ناجح.

إليك العملية خطوة بخطوة التي تم التأكد من أنها تعمل.

---

الجزء الأول: إعداد Stripe

تستخدم هذه العملية Stripe كـ “مصدر للحقيقة” لجميع المنتجات والأسعار.

1. إنشاء المنتجات والأسعار الخاصة بك

• في لوحة تحكم Stripe الخاصة بك، تأكد من أنك في وضع مباشر (Live Mode).
• انتقل إلى المنتجات (Products) > كتالوج المنتجات (Product catalog).
• قم بإنشاء منتجاتك الرئيسية أولاً (على سبيل المثال، “عضوية مميزة”، “وصول VIP”).
• ضمن كل منتج، قم بإنشاء جميع الأسعار المرتبطة (على سبيل المثال، XX / شهر، XXX / سنة).

2. خطوة البيانات الوصفية (Metadata) الحاسمة لكي يقوم المكون الإضافي بإضافة المستخدمين تلقائيًا إلى مجموعة، يجب عليك إضافة بيانات وصفية محددة إلى كل كائن سعر (Price object) تقوم بإنشائه. قد تجعل واجهة مستخدم لوحة تحكم Stripe هذا الأمر صعب العثور عليه.

• عند إنشاء سعر جديد (أو إذا كان بإمكانك العثور على خيار “تحرير السعر” (Edit price))، يجب عليك إضافة بيانات وصفية. قد تحتاج إلى النقر فوق “خيارات إضافية” (Additional options) أثناء إنشاء السعر للكشف عن حقول البيانات الوصفية.
• انقر فوق + إضافة بيانات وصفية (+ Add metadata) وأدخل ما يلي:
  • المفتاح (KEY): group_name
  • القيمة (VALUE): معرف/اسم المجموعة الفريد والقابل للاستخدام في عنوان URL من Discourse، وليس اسمها الكامل.

مثال:

• إذا كان الاسم الكامل لمجموعة Discourse الخاصة بك هو “Enclave Plus”، فمن المحتمل أن يكون معرفها هو EnclavePlus.
• يجب عليك استخدام EnclavePlus كقيمة. استخدام "Enclave Plus" مع مسافة سيفشل.

• يجب عليك تكرار هذا لكل خطة سعر تريد ربطها بمجموعة.

3. إنشاء جدول أسعار Stripe الخاص بك

• انتقل إلى المنتجات (Products) > جداول الأسعار (Pricing tables).
• قم بإنشاء جدول جديد وأضف الأسعار التي قمت بتكوينها للتو.
• بعد نشر الجدول، انقر فوق زر “نسخ الكود” (Copy code) للحصول على معرف جدول الأسعار (Pricing table ID) الخاص بك (يبدأ بـ prctbl_...).

4. تكوين نقطة نهاية Webhook (إصلاح خطأ 404) هذه هي النقطة الأكثر شيوعًا للفشل.

• انتقل إلى المطورون (Developers) > Webhooks وانقر فوق + إضافة نقطة نهاية (+ Add endpoint).
• يجب أن يكون عنوان URL لنقطة النهاية (Endpoint URL) بالتنسيق التالي: https://your-discourse-site.com/s/hooks
• ملاحظة: المسار الصحيح هو /s/hooks، وليس /s/stripe/webhook.
• بالنسبة لـ الأحداث المراد إرسالها (Events to send)، أضف على الأقل:
  • checkout.session.completed
  • customer.subscription.deleted
• قم بإنشاء نقطة النهاية وانسخ سر التوقيع (Signing secret) (يبدأ بـ whsec_...).

---

الجزء الثاني: تكوين Discourse

الآن، لنقم بتكوين المكون الإضافي لاستخدام كل ما قمت بإعداده في Stripe.

1. إدخال مفاتيح API ومعرف جدول الأسعار

• انتقل إلى Admin > Settings وابحث عن discourse subscriptions.
• أدخل مفاتيح Stripe الحية الخاصة بك:
  • discourse subscriptions public key (pk_live_...)
  • discourse subscriptions secret key (sk_live_...)
  • discourse subscriptions webhook secret (whsec_...)
• قم بتمكين وضع جدول الأسعار:
  • حدد مربع discourse subscriptions pricing table enabled.
  • الصق معرف prctbl_... الخاص بك في حقل discourse subscriptions pricing table id.

2. ربط منتجات Stripe بمجموعات Discourse حتى مع جدول الأسعار، تحتاج إلى إخبار Discourse أي مجموعة تنتمي إلى أي منتج.

• انتقل إلى Admin > Plugins > Subscriptions وانقر فوق علامة التبويب المنتجات (Products).
• انقر فوق إنشاء منتج جديد (Create New Product).
• أدخل اسم المنتج (Product Name) الذي يطابق تمامًا اسم المنتج في Stripe (على سبيل المثال، Enclave Plus).
• احفظ المنتج. في صفحة المنتج، قم بالتمرير لأسفل وانقر فوق إضافة خطة جديدة (Add New Plan).
• هذه الخطة هي مجرد “جسر”. الحقل الحاسم الوحيد هو مجموعة المستخدمين (User Group).
  • اسم مستعار للخطة (Plan Nickname): Enclave Plus Group Link (أو أي شيء لمرجعك).
  • مجموعة المستخدمين (User Group): حدد مجموعة Discourse الصحيحة من القائمة المنسدلة.
  • يمكن ترك الحقول الأخرى (المبلغ، الفاصل الزمني) كافتراضية، حيث سيتم تجاهلها.
• احفظ الخطة. كرر هذا لجميع منتجاتك المختلفة.

---

ملخص استكشاف الأخطاء وإصلاحها

• المشكلة: تفشل Webhooks مع خطأ 404 Not Found.
  • الحل: عنوان URL لنقطة النهاية في Stripe غير صحيح. يجب أن يكون https://your-discourse-site.com/s/hooks.
• المشكلة: Webhook ناجح (200 OK) ويظهر الدفع في ملف تعريف الفواتير للمستخدم، ولكن لم تتم إضافته إلى المجموعة.
  • الحل: البيانات الوصفية الخاصة بك غير صحيحة. تحقق من ثلاثة أشياء:
    1. يجب أن تكون البيانات الوصفية على كائن سعر Stripe (Stripe Price)، وليس كائن المنتج (Product object).
    2. يجب أن يكون مفتاح البيانات الوصفية هو group_name بالضبط.
    3. يجب أن تكون قيمة البيانات الوصفية هي المعرف/الاسم الفريد للمجموعة (على سبيل المثال، EnclavePlus)، وليس اسمها الكامل مع المسافات.

آمل أن يوفر هذا الدليل وقتًا وإحباطًا للآخرين في هذا الإعداد المعقد ولكنه قوي للغاية.