​

مركز التفضيلات: صفحة التفضيل/إلغاء الاشتراك العامة

النسخة الإنجليزية الأصلية: Preference center: the public opt-in/opt-out page.

​

1. كوّن مرة واحدة: POST/GET /preference-center

​

حقول التكوين

​

موضوعات الاشتراك

• name (1–120 محرفًا) — الاسم الظاهر في الصفحة.
• description (اختياري، ≤500) — سطر سياق واحد يظهر بجانب المفتاح.
• defaultOptIn (الافتراضي false) — كيف تُعامل جهة الاتصال التي لا تفضيل مسجلًا لها.
• archived (اختياري) — تبقى الموضوعات المؤرشفة في سجل التدقيق لكنها لم تعد تظهر في الصفحة.

​

2. أنشئ رابطًا لكل جهة اتصال

curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/preference-center/link" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "cnt_01H…" }'

• يستهدف الرابط الصفحة المستضافة لا نقطة النهاية JSON. انسخه كما هو في قوالب التذييل/المرسل لديك؛ تجلب الصفحة نفسها نقطة النهاية البيانات تحت الغطاء.
• صلاحية 30 يومًا. بعدها يتحقق الرمز منتهيَ الصلاحية وعلى جهة الاتصال طلب رابط جديد (إنشاء رابط جديد يستدعي API مرة واحدة).
• الصفحة محايدة Locale وقت الإنشاء. يحل تطبيق الويب عملية إعادة توجيه مع إبقاء استعلام ?token=، فلا تحتاج إلى تخمين locale جهة الاتصال.

​

أين تضعه

• إرسالات تسويقية بنص حر: يُضاف نيابةً عنك. لا تحتاج إلى وضع الرابط. تُلحق Orbit سطر {optOutMessage}: {link} بكل إرسال تسويقي بنص حر ما دام مركز التفضيلات مفعّلًا — على sms وwhatsapp عبر نطاقك القصير المميز، وعلى email وبقية قنوات النص الحر كرابط مرمّز خام — وتُستثنى الإرسالات القالبية. الصفحة نفسها تشرح متى يظهر التذييل، وماذا يكتب النقر الملحق، وكيف يرتبط بصيغة “Reply STOP” لدى الناقل: انظر مركز التفضيلات: متى تلحق Orbit تذييل إلغاء الاشتراك نيابة عنك.
• الإرسالات التعاملية والقالبية: ضعه بنفسك. لا تحمل هذه الإرسالات التذييل الملحق أبدًا، لذا الرابط المنشأ أعلاه هو وسيلتها للحصول على إلغاء اشتراك بلمسة واحدة: انسخه كما هو في موضع إلغاء الاشتراك من قوالب بريدك، وأدرجه في النسخ القالبية أو المتون التعاملية حيث تريد واحدًا. إنشاء رابط قصير متتبع لكل موضع اختياري؛ إن فشل إنشاء الرابط القصير يظل الرابط الخام يعمل — البديل إضافي ولا يكون أبدًا ركيزة امتثال.
• إعادة تفضيل مدفوعة بالكبت. حين تعاود جهة الاتصال التفضيل عبر مسار آخر، يمكنك منحها رابطًا جديدًا لتحصل على الصفحة الذاتية نفسها.

​

3. صفحة الرمز العامة

• GET /preferences/:token — يعيد حمولة الصفحة.
• PUT /preferences/:token — يطبّق التحديثات.

​

استجابة GET

{
  "contactId": "cnt_01H…",
  "displayName": "…",
  "email": "m*****@example.com",      // masked
  "phone": "+15551****…",             // masked
  "channelPreferences": { "sms": "opted_in", "email": "opted_out" },
  "frequencyPreference": "all",
  "channels": ["sms", "email"],
  "topics": [ { "id": "newsletter", "name": "Newsletter", "defaultOptIn": false } ],
  "topicPreferences": { "newsletter": "opted_in" },
  "consentHistory": [
    { "channel": "all", "state": "opted_out", "topicId": "newsletter", "occurredAt": "2026-09-01T…" }
  ],
  "config": { /* the org's preference-center config */ }
}

​

جسم طلب PUT

{
  "channelPreferences": {
    "sms": "opted_in",
    "email": "opted_out"
  },
  "frequencyPreference": "important_only",
  "topicPreferences": { "newsletter": "opted_in" },
  "requestDataDeletion": false
}

• channelPreferences — يُسمح بخريطة جزئية (سجل جزئي في Zod)؛ تُطلب قناة واحدة على الأقل.
• frequencyPreference — اختياري، إحدى all، important_only، weekly_digest، monthly_digest.
• topicPreferences — خريطة اختيارية بصيغة { topicId: opted_in | opted_out } يُتحقق منها مقابل موضوعاتك المكوّنة؛ تُتجاهل المعرّفات غير المعروفة.
• requestDataDeletion — يسجّل طلب حذف GDPR إلى جانب إلغاء الاشتراك (انظر القسم 6).

​

4. كيف تجري التحديثات

• دفتر الموافقات. يُضاف صف consent_records واحد لكل قناة (أو لكل موضوع) مع source: preference_center — سجل تدقيق عبء الإثبات وفق GDPR Art 7 لديك.
• قائمة الكبت. عند أي قناة ملغاة، يُدرج هاتف/بريد جهة الاتصال المقنّن بنطاق all — حجب عابر للقنوات تقرأه كل بوابات الإرسال.
• سور STOP. يُضبط سور Redis سريع المسار عند إلغاء الاشتراك (ويُمسح عند إعادة التفضيل الكاملة)، فترى دفعات الحملات الجارية التغيير قبل أن يسري الكبت الأبطأ في قاعدة البيانات.
• سجل التدقيق. يُسجَّل compliance.preference_center_updated عند تغيير التكوين، وتُلتقط أحداث التفضيل/الإلغاء على مستوى جهة الاتصال في دفتر الموافقات.

​

5. دلالات مفتاح حذف GDPR

​

6. اختباره

curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/preference-center" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Acme Logistics",
    "primaryColor": "#1d4ed8",
    "channels": ["sms", "email"],
    "headerText": "Manage how Acme contacts you",
    "topics": [
      { "id": "shipping-updates", "name": "Shipping updates", "defaultOptIn": true },
      { "id": "promotions", "name": "Promotions", "defaultOptIn": false }
    ]
  }'

LINK=$(curl -s -X POST "https://api.orbit.devotel.io/api/v1/compliance/preference-center/link" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"cnt_01H…"}' | jq -r '.link')

TOKEN="${LINK#*token=}"

curl -s "https://api.orbit.devotel.io/api/v1/compliance/preferences/$TOKEN" | jq

curl -s -X PUT "https://api.orbit.devotel.io/api/v1/compliance/preferences/$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channelPreferences":{"sms":"opted_out"}}' | jq

​

Related

• بوابات الإرسال وحواجز ما قبل الإرسال — حيث يرد ملخص مركز التفضيلات إلى جانب ساعات الهدوء، والإيقاف الطارئ، وخواطئ المعدل.
• قوائم إلغاء الاشتراك والكبت — كيف يرتبط النطاق all واستيرادات CSV الجماعية بهذا السطح.
• إدارة الموافقات — واجهة API جهة المشغّل التي تخزّن دفتر الموافقات نفسه.
• مرجع DSAR — خط أنابيب المحو المتتبع الذي تُوجَّه إليه طلبات requestDataDeletion.