SocialHub.AI
مركز المطورين · REST API

التخصيص: الحقول والوحدات

Flash مُصمم لكل علامة تجارية بطريقتين، وكلاهما على قاعدة بيانات مشتركة واحدة - لا يوجد تفرع. الحقول المخصصة تُضيف بياناتك الخاصة إلى سجل العضو ويتم تعيينها من خلال الإصدار 2 REST API. الوحدات هي إمكانيات اختيارية يتم تفعيلها لكل مساحة عمل ويتم فرضها بواسطة الخادم. يغطي هذا الدليل كلا الخيارين.

الخطوة 1 - تحديد الحقل (داخل التطبيق)

يتم تعريف الحقول قبل تعيينها.

يُنشئ المالك أو المسؤول حقولًا ضمن الإعدادات ← الحقول المخصصة. يحتوي كل حقل على key (اسمه البرمجي، مثلاً cf_membership_no)، وtype، وقائمة خيارات لأنواع التحديد. يتم تثبيت المفتاح والنوع بمجرد الإنشاء. لا يقوم API بإنشاء حقول جديدة؛ بل يُعيّن قيمًا للحقول الموجودة مسبقًا فقط، ويرفض المفاتيح غير المعروفة - جدول التعريف هو قائمة السماح.

الخطوة 2 - تحديد القيم عبر API

مرر customAttributes عند الإنشاء أو التحديث

يقبل كل من POST /api/v2/members (إنشاء) وPATCH /api/v2/members/{id} (تحديث) مفتاح customAttributes object مُشفّرًا باستخدام مفاتيح الحقول الخاصة بك. قم بالمصادقة باستخدام مفتاح Bearer fl_live_ بنطاق members:write.

curl -X POST https://flash.socialhub.ai/api/v2/members \
  -H "Authorization: Bearer fl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "fullName": "Ada Lovelace",
    "customAttributes": {
      "cf_membership_no": "A-10023",
      "cf_preferred_store": "flagship",
      "cf_child_birthday": "2018-05-01"
    }
  }'

عند التحديث، أرسل المفاتيح التي تريد تغييرها فقط. يؤدي تعيين مفتاح إلى null إلى مسحه.

curl -X PATCH https://flash.socialhub.ai/api/v2/members/{id} \
  -H "Authorization: Bearer fl_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "customAttributes": { "cf_preferred_store": "airport" } }'
أشكال القيمة حسب النوع

ما يقبله كل نوع حقل

النوعمثال على قيمة JSONيقبل
text"A-10023"string
number42number (أو رقمي string)
date"2018-05-01"تاريخ ISO (سنة-شهر-يوم)
booleantruetrue / false
enum"flagship"أحد خيارات المجال
list["running","tennis"]مجموعة فرعية من خيارات الحقل

التحقق من صحة البيانات صارم: يجب أن تتطابق القيمة مع نوع الحقل، ويجب أن تكون قيمة enum/list من بين الخيارات المحددة، ويتم رفض المفاتيح غير المعروفة باستخدام 400. لا تُقبل حقول البيانات الشخصية الحساسة (PII) حاليًا - يُرجى الاحتفاظ بالسمات المخصصة لقيم الأعمال غير الحساسة.

ما ستحصل عليه لاحقًا

قيمة واحدة، مستخدمة في جميع أنحاء المنصة

القطاعات

يُمكنك تصفية الأعضاء حسب أي حقل مُخصص باستخدام عوامل التشغيل المناسبة للنوع - نفس الحقل الذي قمت بتعيينه عبر API.

تخصيص البريد الإلكتروني

أشر إلى القيمة في النسخة باسم {{cf_membership_no}} أو {{member.cf_membership_no}}.

قراءة العضو

يتم إرجاع القيم المخصصة للعضو object ضمن customAttributes.

2 الوحدات

إمكانيات اختيارية، يتم تفعيلها لكل مساحة عمل

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

كيف تعمل آلية التحكم

يُنفذ بواسطة الخادم، في مكان واحد

لكل وحدة مفتاح ثابت (مثلاً tickets). يتم تفعيل إمكانية استخدام هذه الوحدة في مساحة العمل عبر مفتاح واحد خاص بكل مساحة، ويتم التحقق منه في نقطة تقييم واحدة، ويُطبق على جميع الوحدات التي تظهر فيها الوحدة — fail-closed: إذا كان المفتاح غير مُفعّل، فهذا يعني أن هذه الإمكانية غير متوفرة.

API

نقاط نهاية الوحدة المعطلة ترفض المكالمات برمز 403. لا يُترك الوصول للصدفة في واجهة المستخدم وحدها.

التنقل والصفحات

تظهر عناصر قائمة الوحدة وصفحاتها فقط عند تفعيلها في مساحة العمل، وتختفي تمامًا عند تعطيلها.

معزولة عن المستأجرين

تُمنح الصلاحيات لكل مساحة عمل على حدة. لا يمكن لأي علامة تجارية رؤية وحداتها وبياناتها.

التمديد دون إنشاء نسخة معدلة

كيفية إضافة وحدة جديدة

عندما تكون إحدى الميزات قابلة لإعادة الاستخدام، يتم إنشاؤها مرة واحدة كوحدة نمطية - تُسجَّل في كتالوج الوحدات النمطية تحت مفتاحها الخاص، مع بياناتها الخاصة، وصلاحياتها الخاصة API وصفحاتها الخاصة. يتم إنشاء هذه الميزة لأول مساحة عمل تحتاجها. الخطوة التالية هي ببساطة تشغيل المفتاح. هذا هو جوهر النموذج: تُعبّر اختلافات العملاء عن نفسها من خلال الإعدادات، بحيث يصل أي تحديث أو إصلاح إلى جميع مساحات العمل في آنٍ واحد.

  1. يتم تسجيل الوحدة في الكتالوج بمفتاح ووصف ثابتين.
  2. بياناتها ومسارات API محمية بهذا المفتاح (مغلقة في حالة الفشل).
  3. لا تظهر صفحاته وقوائم التنقل إلا عند تفعيل المفتاح.
  4. يقوم المالك بتفعيله لمساحة عمل؛ أما مساحة العمل الثانية فهي مجرد تبديل، وليست إعادة بناء.
إدارة الوحدات

تشغيل أو إيقاف الوحدات

يُدير مالكو مساحات العمل الوحدات من الإعدادات ← الوحدات. يُفعّل كل تغيير فورًا في API وواجهة المستخدم.

قاعدة القرار: استخدم التكوين أولاً؛ أضف حقل مخصص عندما تحتاج إلى تخزين قيمة؛ قم ببناء وحدة نمطية عندما تكون إحدى الإمكانيات قابلة لإعادة الاستخدام حقًا - ولا تقم أبدًا بتفرع المنتج من أجل عميل واحد.

هل تحتاج إلى نوع جديد كليًا من السجلات، وليس مجرد حقل إضافي؟ راجع كائنات مُخصَّصة - أنشئ مشروعك التجاري الخاص بدون كتابة أي كود object، ثم استعرض السجلات وقسِّمها. للحفاظ على تزامن بقية مكونات نظامك، راجع الموصلات والإشعارات. من الصفر إلى أول مكالمة مُوثَّقة - أنشئ مفتاحًا، وحدد نطاقاتك، وأرسل طلبًا.