العملاء المسجّلون

الجزء الأول

لأصحاب الأعمال

ما الذي يتغيّر لعملائك

• يعرف Nova اسم العميل، ولا يطلب منه بريدًا إلكترونيًا لديك أصلًا.
• محادثته تتبعه. المحادثة التي بدأها على الحاسوب تظهر على هاتفه بمجرّد أن يسجّل الدخول.
• إذا تحدّث قبل تسجيل الدخول، تنتقل تلك المحادثة إلى حسابه عند تسجيل الدخول.
• تستطيع أدواتك العمل لهذا العميل وحده، مثل الإجابة عن «أين طلبي؟» من سجلّ طلباته هو.
• على WhatsApp، يكون رقم العميل موثّقًا من WhatsApp أصلًا، فتعمل الأدوات نفسها هناك أيضًا.

لماذا هو آمن

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

ما عليك فعله في البوابة

1. أنشئ مفتاح الهوية السرّي

   في بوابة Nova، افتح Channels › Installation وابحث عن Signed-in customers، ثم اختر Create secret.

   يظهر المفتاح مرّة واحدة فقط. انسخه وأرسله إلى مطوّرك عبر مدير كلمات مرور أو قناة خاصة أخرى، وليس أبدًا عبر بريد إلكتروني أو محادثة عادية.

2. أرسل هذه الصفحة إلى مطوّرك

   الجزء الثاني أدناه فيه كل ما يحتاجه. في معظم المواقع يستغرق الأمر أقل من ساعة، وعلى Shopify هو مقطع واحد في القالب.

3. دع أدواتك تستخدم بيانات العميل (اختياري)

   افتح MCP Servers، وعدّل الخادم، ثم انتقل إلى Tools. تحت كل مُدخل، يتيح لك Filled by اختيار معرّف العميل المسجّل، أو بريده، أو رقمه على WhatsApp، أو متغيّر. لا يرى الذكاء الاصطناعي القيمة التي تُملأ بهذه الطريقة ولا يستطيع تغييرها.

   القيم التي تتشاركها عدّة أدوات، مثل معرّف المتجر أو مفتاح API، تُضاف في بطاقة Variables في الصفحة نفسها. علّم مفاتيح API بأنها Secret كي لا تظهر مجدّدًا.

4. حدّد من يستطيع المحادثة (اختياري)

   فعّل Only signed-in customers can chat إذا كانت المحادثة لأصحاب الحسابات فقط، مثل منطقة الأعضاء. يُطلب من الجميع غيرهم تسجيل الدخول.

أين تراه

يظهر العملاء المسجّلون في Contacts مع معرّفهم تحت أسمائهم، ويمكنك البحث بهذا المعرّف. وفي Conversations، تُظهر لوحة التفاصيل علامة Signed in مع المعرّف والاسم وأي تفاصيل إضافية أرسلها موقعك.

متى تغيّر المفتاح السرّي

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

الجزء الثاني

للمطوّرين

كيف يعمل التوقيع

لكل عميل مسجّل، أرسل إلى Nova معرّفه وتوقيعًا: قيمة HMAC-SHA256 للمعرّف كنصّ، باستخدام مفتاح الهوية السرّي، مكتوبة بصيغة hex بأحرف صغيرة. أنشئ التوقيع على خادمك. يجب ألا يصل المفتاح السرّي إلى المتصفّح أبدًا.

مثال محسوب: بالمفتاح test-secret والمعرّف 42، يكون التوقيع 0c448d9ba9697edc6e65d581ad07fba78e907baad3c1e452d3ead109363f97bf. إذا أعطاك الكود قيمة مختلفة، تأكّد من تحويل المعرّف إلى نصّ قبل التوقيع.

الخطوة 1. وقّع المعرّف على خادمك

// PHP
$userHash = hash_hmac('sha256', (string) $customer->id, getenv('NOVA_IDENTITY_SECRET'));

// Node
const userHash = crypto
  .createHmac('sha256', process.env.NOVA_IDENTITY_SECRET)
  .update(String(customer.id))
  .digest('hex');

# Python
user_hash = hmac.new(os.environ['NOVA_IDENTITY_SECRET'].encode(),
                     str(customer.id).encode(), hashlib.sha256).hexdigest()

الخطوة 2. مرّر العميل إلى الأداة

استخدم ما يناسب موقعك. يجب أن تحمل هذه البيانات فقط الصفحات التي يكون فيها العميل مسجّل الدخول.

قبل سكربت الأداة. الأنسب للصفحات التي يولّدها خادمك لعميل واحد.

<script>
  window.kockatoosSettings = {
    identity: {
      userId: '42',
      userHash: 'SIGNATURE_FROM_YOUR_SERVER',
      name: 'Jane Doe',
      email: 'jane@example.com',
      attributes: { plan: 'gold' },
    },
  };
</script>
<script src="https://nova.kockatoos.co/widget.js" data-key="YOUR_WIDGET_KEY" async></script>

بعد تحميل الصفحة. الأنسب لتطبيقات الصفحة الواحدة التي تعرف لاحقًا من سجّل الدخول. يصبح window.kockatoosChat متاحًا بعد تحميل الأداة.

window.kockatoosChat.identify({
  userId: customer.id,
  userHash: signatureFromYourServer,
  name: customer.name,
  email: customer.email,
  token: customerAccessToken, // optional
});

// When the customer signs out
window.kockatoosChat.logout();

على وسم السكربت. الصيغة الأقصر، للمعرّف والتوقيع فقط.

<script src="https://nova.kockatoos.co/widget.js" data-key="YOUR_WIDGET_KEY"
        data-user-id="42" data-user-hash="SIGNATURE_FROM_YOUR_SERVER" async></script>

الخطوة 3. سجّل خروج العميل

استدعِ window.kockatoosChat.logout() عندما يسجّل العميل خروجه، كي يبدأ الشخص التالي على المتصفّح نفسه محادثة جديدة. وكإجراء احتياطي، تُسقط الأداة المحادثة أيضًا عندما تذكر الصفحة عميلًا مختلفًا، أو لا تذكر أحدًا، عند التحميل التالي.

Shopify

الصق هذا في theme.liquid مكان سكربت الأداة الحالي، واستبدل القيمتين المؤقّتتين. يحسب Shopify التوقيع على خوادمه، فلا يصل المفتاح السرّي إلى الصفحة. لكن كل من يستطيع تعديل قالبك يستطيع قراءته، لذا ضيّق صلاحيات الوصول إلى القالب.

{% if customer %}
<script>
  window.kockatoosSettings = {
    identity: {
      userId: '{{ customer.id }}',
      userHash: '{{ customer.id | hmac_sha256: "YOUR_IDENTITY_SECRET" }}',
      name: {{ customer.name | json }},
      email: {{ customer.email | json }},
    },
  };
</script>
{% endif %}
<script src="https://nova.kockatoos.co/widget.js" data-key="YOUR_WIDGET_KEY" async></script>

حافظ على الأمان

• احفظ مفتاح الهوية السرّي في إعدادات بيئة خادمك، وليس أبدًا في كود الواجهة أو في مستودع عام.
• لا تطبع رمز وصول العميل أبدًا داخل HTML قد تقدّمه شبكة CDN أو ذاكرة تخزين مؤقت لشخص آخر. مرّره عبر identify() بعد تحميل الصفحة.
• التوقيع لا تنتهي صلاحيته. إذا تسرّب، فإنه يفتح سجلّ محادثات ذلك العميل إلى أن يُغيَّر المفتاح السرّي.

الاستخدام في أدواتك

يستطيع خادم MCP الخاص بك استقبال بيانات العميل بطريقتين، تُضبطان كلتاهما في نافذة خادم MCP في البوابة. تُكتب العناصر النائبة بين قوسين معقوفين مزدوجين، ويملؤها Nova لحظة الاستدعاء.

الترويسات

أضف ترويسات مثل Authorization: Bearer {{visitor.token}} أو X-Store: {{vars.store_id}}. تُرسَل مع استدعاءات الأدوات فقط، وليس عندما يقرأ Nova قائمة الأدوات، ولا تُرسَل إلا إلى عنوان الخادم نفسه. الترويسة المسمّاة Authorization تحلّ محلّ رمز الوصول الخاص بالخادم في استدعاءات الأدوات.

المُدخلات المملوءة

اضبط مُدخلًا في الأداة، مثل customer_id، ليُملأ بـ {{visitor.id}}. عندها لا يرى الذكاء الاصطناعي هذا المُدخل، فلا يستطيع أن يطلب عميلًا آخر أو يختاره. يضيف Nova القيمة بعد أن يقرّر الذكاء الاصطناعي استدعاء الأداة، ولا تُحفَظ القيمة في سجلّ المحادثة.

عندما يتعذّر ملء قيمة، مثل زائر غير مسجّل، يستبعد Nova تلك الأداة من المحادثة ويطلب من الزائر تسجيل الدخول إن احتاج إليها. ومع ذلك، يجب أن يتحقّق خادمك من كل طلب يصله.

حلّ المشكلات

يرى العملاء رسالة “Please sign in to chat with us.”

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

أداة لا تعمل أبدًا.

أحد مُدخلاتها المملوءة لم تكن له قيمة. ربما العميل غير مسجّل، أو تفصيل إضافي مفقود، أو تغيّر اسم متغيّر.

توقّف التعرّف على الجميع دفعة واحدة.

على الأرجح تمّ تغيير المفتاح السرّي. ضع المفتاح الجديد على خادمك.

عميل جديد على حاسوب مشترك يرى المحادثة السابقة.

استدعِ logout() عند تسجيل الخروج، أو تأكّد من أن الصفحة تمرّر العميل الجديد فور تسجيل دخوله.

هل يعمل هذا في تطبيق Flutter؟

ليس بعد. العملاء المسجّلون مدعومون في أداة الموقع، وعلى WhatsApp عبر الرقم الموثّق.