تعريف المستخدم

يربط تعريف المستخدمين جلسات الدردشة المجهولة بملفات المستخدمين الحقيقية.

كيف يعمل

عند استدعاء Respondo.identify()، تُرفَق الحقول المقدّمة بالمحادثة. جميع الحقول اختيارية — مرّر فقط ما لديك منها. على سبيل المثال، يمكنك إرسال userId فقط دون بريد إلكتروني أو اسم. يرى موظفو الدعم هذه البيانات في لوحة تفاصيل المحادثة.

المعاملات#

الخاصية	النوع	مطلوب	الوصف
email	string	اختياري	عنوان البريد الإلكتروني للمستخدم
name	string	اختياري	الاسم المعروض
userId	string	اختياري	معرّف المستخدم الداخلي أو المعرّف المعروض لديك — يُعرض كما هو في لوحة التحكّم
userHash	string	اختياري	توقيع HMAC-SHA256 للتحقق من الهوية
metadata	object	اختياري	أزواج مفتاح-قيمة من الحقول المخصصة (الخطة، الشركة، إلخ)
properties	object	اختياري	خصائص جهة اتصال مخصصة معرّفة في إعدادات الوكيل (Agent Settings). يجب أن تطابق المفاتيح تعريفات الخصائص. تُخزَّن القيم ببادئة `cp_` ويمكن التصفية بها في صندوق الوارد.

مثال: تطبيق أحادي الصفحةjavascript

// بعد تسجيل الدخول بنجاح
async function onLogin(user) {
  await authenticateUser(user);

  Respondo.identify({
    email: user.email,
    name: user.fullName,
    userId: user.id,
    metadata: {
      plan: user.subscription.plan,
      company: user.company.name,
      role: user.role,
      signedUp: user.createdAt
    },
    properties: {                        // خصائص جهة اتصال مخصصة
      account_type: user.accountType,    // يجب أن تطابق المفاتيح من إعدادات الوكيل
      industry: user.industry,
      contract_tier: user.tier
    }
  });
}

مع مقتطف التثبيت القياسي يمكنك استدعاء identify() في أي وقت — الاستدعاءات التي تتم قبل اكتمال تحميل widget.js يضعها المقتطف في طابور ويعيد تشغيلها تلقائياً بمجرد تهيئة الأداة. لا تُهمَل بيانات الهوية (مع تحذير في وحدة التحكم) إلا إذا حمّلت widget.js بنفسك واستدعيت identify() قبل استدعاء init() إطلاقاً — في الإعدادات اليدوية استدعِ دائماً init() أولاً.

الزوار المجهولون#

إذا لم تستدعِ identify()، تُعيّن الأداة تلقائياً معرّف زائر دائماً مخزّناً في localStorage (بالمفتاح respondoai_visitor_id). في لوحة التحكّم، تظهر المحادثة باسم Guest · Web widget.

الوضع	العرض في لوحة التحكّم	HMAC مطلوب
بدون `identify()`	Guest · Web widget	لا
`identify({ email, name })`	يظهر الاسم + البريد الإلكتروني	لا — إلا إذا كان التحقق من الهوية مفعّلاً؛ عندها يُجرَّد البريد الإلكتروني/الاسم غير الموقَّعين بصمت وتبقى الجلسة مجهولة
`identify({ userId })`	يُعرض userId كما هو	لا — إلا إذا كان التحقق من الهوية مفعّلاً؛ عندها يلزم `userHash` صالح وإلا تُجرَّد الهوية
`identify({ userId, userHash })`	هوية مستخدم موثّقة	نعم — موثّقة تشفيرياً

عند تفعيل التحقق من الهوية للقناة، أي استدعاء identify() يحمل بريداً إلكترونياً أو userId دون userHash صالح يُجرَّد على جانب الخادم ويبقى الزائر مجهولاً — انظر التحقق من الهوية (HMAC) أدناه.

يبقى معرّف الزائر عبر الجلسات على المتصفح نفسه. لا يُرسَل أبداً إلى Respondo كهوية موثّقة — يُستخدم فقط لاستمرارية المحادثة المجهولة.

التعريف باستخدام userId فقط (دون بريد إلكتروني أو اسم)#

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

userId + metadata (دون بريد إلكتروني أو اسم)javascript

// منصّتك تملك معرّف عرض فقط — هذا كافٍ
Respondo.identify({
  userId: user.displayId,      // مثال "USR-4821" — يُعرض في لوحة التحكّم
  metadata: {                  // سياق إضافي اختياري
    plan: 'premium',
    region: 'eu-west'
  }
});
// لا حاجة لبريد إلكتروني أو اسم — تعمل الأداة بـ userId فقط

لمنع انتحال userId، اقرنه بـ userHash (انظر التحقق من الهوية أدناه). بدون HMAC، يمكن لأي شخص تمرير أي userId من وحدة تحكم المتصفح.

Google Tag Manager / استدعاء identify() المؤجّل#

عند التضمين عبر GTM، قد لا تكون بيانات المستخدم متاحة عند تحميل الصفحة. طريقتان:

الخيار A: localStorageKey (بدون أي JS)javascript

// إذا كانت منصّتك تكتب معرّف المستخدم إلى localStorage بالفعل:
Respondo.init({
  agentId: 'YOUR_AGENT_ID',
  localStorageKey: 'myapp_user_id'  // يقرأ localStorage.getItem('myapp_user_id') تلقائياً
});
// لا حاجة لاستدعاء identify() — تلتقط الأداة userId من تلقاء نفسها

الخيار B: استدعاء identify() المؤجّل عبر dataLayerjavascript

// 1. هيّئ الأداة فوراً (وسم GTM)
Respondo.init({ agentId: 'YOUR_AGENT_ID' });

// 2. لاحقاً، عند ظهور بيانات المستخدم (مثلاً من dataLayer أو تطبيقك):
var waitForUser = setInterval(function() {
  var uid = localStorage.getItem('myapp_user_id');
  if (uid && window.Respondo && typeof window.Respondo.identify === 'function') {
    clearInterval(waitForUser);
    Respondo.identify({ userId: uid });
  }
}, 500);

يُستخدم localStorageKey فقط إذا لم يكن userId مضبوطاً بالفعل عبر identify(). تحظى استدعاءات identify() الصريحة دائماً بالأولوية.

التحقق من الهوية (HMAC)#

بدون تحقق، يمكن لأي شخص انتحال شخصية مستخدم عبر تمرير userId أو email مزيّف. يستخدم التحقق من الهوية خوارزمية HMAC-SHA256 لإثبات تشفيري بأن هوية المستخدم قد ضُبطت من خادمك، لا من كود جانب العميل.

كيف يعمل#

فعّل التحقق من الهوية في إعدادات قناتك — ستحصل على مفتاح سرّي.
على خادمك، احسب HMAC-SHA256(secret, userId) — المفتاح السرّي هو مفتاح التوقيع وuserId هو الرسالة — وأرسل النتيجة إلى الواجهة الأمامية. إذا كنت تعرّف المستخدمين بالبريد الإلكتروني فقط (دون userId)، فوقّع البريد الإلكتروني بدلاً منه: الحمولة الموقَّعة هي userId عند وجوده، وإلا البريد الإلكتروني. إذا مرّرت كليهما فوقّع userId؛ فهو صاحب الأولوية.
مرّر التجزئة كـ userHash في Respondo.identify().
يتحقق Respondo من التجزئة على جانب الخادم. إذا كانت غير صالحة، تُزال الهوية ويُعامَل المستخدم كمجهول.

لا تكشف مفتاحك السرّي أبداً في كود الواجهة الأمامية. يجب حساب HMAC على خادمك الخلفي.

بعد تفعيل التحقق، كل استدعاء identify() يحمل userId أو email يجب أن يتضمّن userHash صالحاً — وإلا تُجرَّد حقول الهوية ويُعامَل الزائر كمجهول.

أمثلة على جانب الخادم#

Node.jsjavascript

const crypto = require('crypto');

const SECRET = process.env.RESPONDO_IDENTITY_SECRET;

function generateUserHash(userId) {
  return crypto
    .createHmac('sha256', SECRET)
    .update(userId)
    .digest('hex');
}

// في نقطة نهاية API لديك:
app.get('/api/respondo-hash', (req, res) => {
  const hash = generateUserHash(req.user.id);
  res.json({ userHash: hash });
});

Pythonpython

import hmac, hashlib, os

SECRET = os.environ['RESPONDO_IDENTITY_SECRET']

def generate_user_hash(user_id: str) -> str:
    return hmac.new(
        SECRET.encode(),
        user_id.encode(),
        hashlib.sha256
    ).hexdigest()

# في العرض / نقطة النهاية لديك:
user_hash = generate_user_hash(request.user.id)

Gogo

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func GenerateUserHash(userID, secret string) string {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(userID))
    return hex.EncodeToString(mac.Sum(nil))
}

الاستخدام في الواجهة الأمامية#

مع التحقق من الهويةjavascript

// اجلب التجزئة من خادمك أنت
const { userHash } = await fetch('/api/respondo-hash').then(r => r.json());

Respondo.identify({
  email: user.email,
  name: user.name,
  userId: user.id,
  userHash: userHash  // توقيع HMAC-SHA256
});