תיעוד

זיהוי משתמשים

זיהוי משתמשים מקשר סשני צ׳אט אנונימיים עם פרופילי משתמשים אמיתיים.

איך זה עובד

כאשר אתם קוראים ל- Respondo.identify(), השדות שסיפקתם מצורפים לשיחה. כל השדות אופציונליים — העבירו רק את אלה שיש לכם. לדוגמה, אפשר לשלוח רק userId ללא אימייל או שם. סוכני התמיכה רואים נתונים אלה בלוח פרטי השיחה.

פרמטרים

מאפייןסוגנדרשתיאור
emailstringאופציונליכתובת האימייל של המשתמש
namestringאופציונלישם תצוגה
userIdstringאופציונלימזהה המשתמש הפנימי או מזהה התצוגה שלכם — מוצג כפי שהוא בלוח הבקרה
userHashstringאופציונליחתימת HMAC-SHA256 לאימות זהות
metadataobjectאופציונליזוגות מפתח-ערך של שדות מותאמים (plan, company וכו׳)
propertiesobjectאופציונלימאפייני איש קשר מותאמים המוגדרים ב-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,    // חייב להתאים למפתחות מ-Agent Settings
      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 כדי להוכיח קריפטוגרפית שזהות המשתמש נקבעה על ידי השרת שלכם, ולא על ידי קוד בצד הלקוח.

איך זה עובד

  1. הפעילו אימות זהות בהגדרות הערוץ שלכם — תקבלו מפתח סודי.
  2. על השרת שלכם, חשבו HMAC-SHA256(secret, userId) — הסוד הוא המפתח, ה-userId הוא ההודעה — ושלחו את התוצאה לצד הלקוח. אם אתם מזהים משתמשים לפי אימייל בלבד (ללא userId), חתמו על האימייל במקום: המטען החתום הוא userId כשהוא מוגדר, אחרת אימייל. אם אתם מעבירים את שניהם, חתמו על ה-userId; הוא מקבל עדיפות.
  3. העבירו את ה-hash כ- userHash ב- Respondo.identify().
  4. Respondo מאמת את ה-hash בצד השרת. אם אינו תקין, הזהות מוסרת והמשתמש מטופל כאנונימי.
לעולם אל תחשפו את המפתח הסודי בקוד צד הלקוח. חישוב ה-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');
}

// בנקודת הקצה של ה-API שלכם:
app.get('/api/respondo-hash', (req, res) => {
  const hash = generateUserHash(req.user.id);
  res.json({ userHash: hash });
});
Python
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()

# ב-view / בנקודת הקצה שלכם:
user_hash = generate_user_hash(request.user.id)
Go
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
// משכו את ה-hash מהשרת שלכם
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
});