Access Tags

نظرة عامة

ليس كل المحتوى للجميع: مستندات للأعضاء فقط، مواد خاصة بمنطقة معينة، موارد مستويات مدفوعة. مع Access Tags يخدم روبوت دردشة واحد جماهير مختلفة بأمان. تضعون وسمًا على عنصر معرفة، ومنذ تلك اللحظة يصبح العنصر غير مرئي لأي زائر — باستثناء من تقدم صفحته ذلك الوسم موقّعًا من خادمكم الخاص. يُفرض التقييد في استعلام الاسترجاع لدينا، قبل أن يشارك نموذج الذكاء الاصطناعي أصلًا. الزائر بلا وسم لا يستطيع انتزاع المحتوى بأسئلة ذكية، لأنه لم يُسترجَع له قط.

كيف يعمل

1. أنتم من يضع الوسوم على عناصر المعرفة - في صفحة Access Tags أو مباشرة عبر API؛ العناصر بلا وسوم تظل تعمل للجميع
2. خادمكم يوقّع وسوم كل زائر - عندما يحمّل عضو مسجّل الدخول صفحتكم، يحدد نظامكم الخلفي صلاحياته ويوقّعها بمفتاح سري لا يملكه سواكم
3. الودجة ترسل الإثبات الموقّع - يسافر مع كل رسالة دردشة؛ المتصفح ينقله فحسب ولا يمكنه تعديله دون كسر التوقيع
4. نحن نتحقق ونفلتر - التوقيع الصالح يفتح العناصر ذات الوسوم المطابقة؛ الإثبات الغائب أو المعدّل أو المنتهي يعني حصول الزائر على المحتوى العام فقط

طريقة الإعداد

فعّلوا الميزة في صفحة Access Tags في لوحة التحكم — سيُولَّد مفتاح توقيع تلقائيًا. احتفظوا به على خادمكم فقط؛ فكل من يملكه يستطيع صنع إثباتات صالحة.

ضعوا الوسوم على المحتوى في الصفحة نفسها، أو عند إرسال العناصر عبر API:

POST /api/v1/knowledge/text/
{
  "title": "Members-only price list",
  "content": "...",
  "website_id": "123",
  "access_tags": ["premium"]
}

ثم اجعلوا خادمكم يطبع الإثبات الموقّع بجوار مقتطف الودجة. الرسالة المراد توقيعها هي قائمة الوسوم المفصولة بفواصل، موصولة بخط عمودي مع وقت الانتهاء عند استخدامه:

<?php
$tags    = "members,premium";          // this visitor's entitlements
$expires = time() + 3600;              // unix seconds, optional but recommended
$sig     = hash_hmac("sha256", $tags . "|" . $expires, $SECRET);
?>
<script>
window.Asyntai = window.Asyntai || {};
window.Asyntai.accessTags = "<?php echo $tags; ?>";
window.Asyntai.accessTagsExpires = "<?php echo $expires; ?>";
window.Asyntai.accessTagsSignature = "<?php echo $sig; ?>";
</script>

التوقيع نفسه في Node.js وPython:

// Node.js
const crypto = require("crypto");
const sig = crypto.createHmac("sha256", SECRET)
                  .update(tags + "|" + expires).digest("hex");

# Python
import hmac, hashlib
sig = hmac.new(SECRET.encode(), f"{tags}|{expires}".encode(),
               hashlib.sha256).hexdigest()

دون وقت انتهاء، وقّعوا سلسلة الوسوم وحدها. مع وقت الانتهاء يتوقف الإثبات عن العمل لحظة انقضائه — مفيد عندما يمكن سحب الصلاحيات، إذ يضطر الزائر لإعادة تحميل صفحة تتحكمون بها ليحصل على إثبات جديد.

منطق الوسوم

تُدمج وسوم العنصر بـ«و»: لا يُسترجع العنصر إلا عندما يظهر كل وسم عليه في إثبات الزائر. يمكن لإثبات الزائر أن يحمل ما شئتم من الصلاحيات، وتتم المطابقة على جميعها دفعة واحدة.

«و» اختيار مقصود. مع مطابقة «أي وسم»، فإن إضافة وسم ثانٍ إلى عنصر كانت ستوسّع دائرة من يراه، فتضييق مستند إلى مجموعتين كان سينشره في الواقع بالكامل لكلتيهما. أما مع مطابقة «كل الوسوم»، فكل وسم تضيفونه لا يمكنه إلا أن يزيد التقييد، بحيث يميل الخطأ إلى الجانب الآمن.

كيف تعبّرون عن «أي من»

احذفوا هذا البُعد من العنصر. إذا كان إثبات كل زائر يحمل منطقته، فإن المستند بلا وسم منطقة يكون متاحًا لكل المناطق، بينما تظل وسومه الأخرى سارية. وهكذا فإن عنصرًا موسومًا بـpremium فقط يعني «أي منطقة، للمشتركين المميزين فقط».

للاختيار الحقيقي بين الأبعاد — مثلًا الشمال-مع-الأساسي أو الجنوب-مع-المميز ولا شيء غيرهما — أضيفوا العنصر مرتين بتركيبة واحدة في كل مرة، أو امنحوا الجمهورين وسمًا مشتركًا يدرجه خادمكم في إثباتيهما.

الحدود

• حتى 20 وسمًا لكل عنصر معرفة
• حتى 50 وسمًا في إثبات زائر واحد
• 50 حرفًا لكل وسم؛ الفواصل والخطوط العمودية غير مسموحة، لأن الإثبات سلسلة مفصولة بفواصل

تغيير الوسوم لاحقًا

يمكن استبدال الوسوم على عنصر قائم دون رفعه من جديد. يسري التغيير اعتبارًا من السؤال التالي — ولا تُعاد معالجة المحتوى نفسه.

POST /api/v1/knowledge/<id>/tags/
{
  "access_tags": ["premium"]
}

أرسلوا قائمة فارغة لجعل العنصر عامًا مرة أخرى. ويمكنكم أيضًا تحرير الوسوم يدويًا في صفحة Access Tags بلوحة التحكم.

ما هو مضمون

• فرض على جانب الخادم - يعمل الفلتر داخل استعلام قاعدة البيانات عند الاسترجاع؛ للزوار غير المصرح لهم لا تدخل العناصر الموسومة سياق الذكاء الاصطناعي أصلًا، فلا يوجد ما يتسرب
• الإغلاق عند الفشل في كل الحالات - لا توقيع، توقيع خاطئ، إثبات منتهٍ، ميزة معطّلة، خطة مخفّضة: في كل هذه الحالات يحصل الزائر على المحتوى العام فقط، ولا أكثر أبدًا
• المتصفح لا يستطيع تزوير الوصول - تعديل الوسوم في أدوات المطور يكسر التوقيع؛ المفتاح لدى خادمكم وحده
• منطق صلاحياتكم يبقى لكم - لا نعرف أبدًا كيف تقررون من يحصل على أي وسم؛ نتحقق فقط من أن خادمكم أكّد ذلك

جدير بالمعرفة

• Access Tags تفويض، وUser Context تخصيص - استخدموا User Context لإخبار الذكاء الاصطناعي عن العضو؛ واستخدموا Access Tags للتحكم في المعرفة التي يجوز له الاستناد إليها
• محتوى الموقع المزحوف عام دائمًا - مصدره موقعكم العام فلا شيء يُقيَّد؛ الوسوم تنطبق على عناصر النص والملفات وAPI
• تُدمج وسوم العنصر بـ«و» - راجعوا منطق الوسوم أعلاه؛ يجب أن يكون كل وسم على العنصر موجودًا في إثبات الزائر
• إعادة توليد المفتاح تُبطل كل الإثباتات القديمة - افعلوها إن كان المفتاح ربما تسرّب، ثم حدّثوا صفحاتكم لتوقّع بالجديد
• أسماء الوسوم متروكة لكم - حتى 20 لكل عنصر، 50 حرفًا لكل وسم، دون فواصل أو خطوط عمودية؛ ولا تظهر أبدًا في الدردشة التي يراها الزوار