شناسایی کاربر

شناسایی کاربران، نشست‌های چت ناشناس را به پروفایل واقعی کاربران وصل می‌کند.

چطور کار می‌کند

وقتی Respondo.identify() را صدا می‌زنید، فیلدهای داده‌شده به گفت‌وگو پیوست می‌شوند. همهٔ فیلدها اختیاری‌اند — فقط آنچه را در اختیار دارید بفرستید. مثلاً می‌توانید تنها userId را بدون ایمیل یا نام بفرستید. کارشناسان پشتیبانی این داده‌ها را در پنل جزئیات گفت‌وگو می‌بینند.

پارامترها#

ویژگی	نوع	الزامی	توضیح
email	string	اختیاری	نشانی ایمیل کاربر
name	string	اختیاری	نام نمایشی
userId	string	اختیاری	شناسهٔ داخلی یا نمایشی کاربر شما — همان‌گونه که هست در داشبورد نمایش داده می‌شود
userHash	string	اختیاری	امضای HMAC-SHA256 برای تأیید هویت
metadata	object	اختیاری	جفت‌های کلید-مقدار از فیلدهای سفارشی (plan، company و مانند آن)
properties	object	اختیاری	ویژگی‌های سفارشی مخاطب که در Agent Settings تعریف شده‌اند. کلیدها باید با تعریف ویژگی‌ها یکی باشند. مقدارها با پیشوند `cp_` ذخیره می‌شوند و در Inbox قابل فیلتر کردن‌اند.

نمونه: اپ تک‌صفحه‌ایjavascript

// After successful login
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: {                        // custom contact properties
      account_type: user.accountType,    // must match keys from Agent Settings
      industry: user.industry,
      contract_tier: user.tier
    }
  });
}

با قطعه‌کد نصب استاندارد می‌توانید identify() را هر زمان صدا بزنید — فراخوانی‌هایی که پیش از پایان بارگذاری widget.js انجام شوند، توسط قطعه‌کد در صف قرار می‌گیرند و پس از راه‌اندازی ویجت به‌طور خودکار بازپخش می‌شوند. داده‌های هویت تنها زمانی حذف می‌شوند (همراه با هشدار در کنسول) که widget.js را خودتان بارگذاری کنید و identify() را پیش از هرگونه فراخوانی init() صدا بزنید — در راه‌اندازی‌های دستی همیشه ابتدا init() را صدا بزنید.

بازدیدکنندگان ناشناس#

اگر identify() را صدا نزنید، ویجت به‌طور خودکار یک visitor ID ماندگار می‌سازد که در 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) را در ادامه ببینید.

visitor ID در نشست‌های مختلف روی همان مرورگر باقی می‌ماند. هرگز به‌عنوان هویت احرازشده به Respondo فرستاده نمی‌شود — تنها برای پیوستگی گفت‌وگوی ناشناس به کار می‌رود.

شناسایی فقط با userId (بدون ایمیل یا نام)#

اگر پلتفرم شما ایمیل یا نام کاربران را ندارد — مثلاً فقط یک شناسهٔ نمایشی داخلی دارید — می‌توانید تنها userId را بفرستید. هیچ فیلد دیگری لازم نیست. داشبورد همان userId را در جزئیات گفت‌وگو نشان می‌دهد.

userId + metadata (بدون ایمیل یا نام)javascript

// Your platform only has a display ID — that's enough
Respondo.identify({
  userId: user.displayId,      // e.g. "USR-4821" — shown in dashboard
  metadata: {                  // optional extra context
    plan: 'premium',
    region: 'eu-west'
  }
});
// No email or name needed — the widget works with just userId

برای جلوگیری از جعل userId، آن را همراه userHash بفرستید (بخش تأیید هویت در ادامه). بدون HMAC، هر کسی می‌تواند از کنسول مرورگر هر userId دلخواهی بفرستد.

Google Tag Manager / فراخوانی تأخیری identify()#

هنگام جاسازی از راه GTM ممکن است داده‌های کاربر در زمان بارگذاری صفحه در دسترس نباشد. دو راه دارید:

گزینهٔ A: localStorageKey (بدون نیاز به JS)javascript

// If your platform already writes the user ID to localStorage:
Respondo.init({
  agentId: 'YOUR_AGENT_ID',
  localStorageKey: 'myapp_user_id'  // reads localStorage.getItem('myapp_user_id') automatically
});
// No identify() call needed — the widget picks up the userId on its own

گزینهٔ B: فراخوانی تأخیری identify() از راه dataLayerjavascript

// 1. Init widget immediately (GTM tag)
Respondo.init({ agentId: 'YOUR_AGENT_ID' });

// 2. Later, when user data appears (e.g. from dataLayer or your app):
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) را حساب کنید — secret همان کلید است و userId همان پیام — و نتیجه را به فرانت‌اند بفرستید. اگر کاربران را فقط با ایمیل شناسایی می‌کنید (بدون userId)، به‌جای آن ایمیل را امضا کنید: payload امضاشده در صورت وجود userId همان userId است، وگرنه email. اگر هر دو را بفرستید، userId امضا می‌شود؛ اولویت با اوست.
هش را به‌عنوان userHash در Respondo.identify() بفرستید.
Respondo هش را سمت سرور بررسی می‌کند. اگر نامعتبر باشد، هویت حذف می‌شود و کاربر ناشناس در نظر گرفته می‌شود.

کلید محرمانه را هرگز در کد فرانت‌اند نگذارید. HMAC باید روی backend شما حساب شود.

پس از فعال شدن تأیید، هر فراخوانی 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');
}

// In your API endpoint:
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()

# In your view / endpoint:
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

// Fetch the hash from YOUR server
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 signature
});