Ідентифікація користувачів

Ідентифікація користувачів пов’язує анонімні сесії чату з реальними профілями користувачів.

Як це працює

Коли ви викликаєте Respondo.identify(), передані поля прикріплюються до розмови. Усі поля необов’язкові — передавайте лише ті, що у вас є. Наприклад, ви можете надіслати лише userId без email чи імені. Агенти підтримки бачать ці дані на панелі деталей розмови.

Параметри#

Властивість	Тип	Обов’язково	Опис
email	string	необов’язково	Email-адреса користувача
name	string	необов’язково	Відображуване ім’я
userId	string	необов’язково	Ваш внутрішній ID користувача або відображуваний ID — показується в панелі як є
userHash	string	необов’язково	Підпис HMAC-SHA256 для верифікації особи
metadata	object	необов’язково	Пари ключ-значення кастомних полів (plan, company тощо)
properties	object	необов’язково	Кастомні властивості контакту, визначені в Agent Settings. Ключі мають відповідати визначенням властивостей. Значення зберігаються з префіксом `cp_` і доступні для фільтрації в Inbox.

Приклад: односторінковий застосунок (SPA)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(), віджет автоматично призначає постійний visitor ID, що зберігається в localStorage (ключ respondoai_visitor_id). У панелі розмова відображається як Guest · Web widget.

Режим	Відображення в панелі	Потрібен HMAC
Без `identify()`	Guest · Web widget	Ні
`identify({ email, name })`	Показуються ім’я + email	Ні — якщо не ввімкнено верифікацію особи; тоді непідписані email/ім’я мовчки відкидаються, і сесія залишається анонімною
`identify({ userId })`	userId показується як є	Ні — якщо не ввімкнено верифікацію особи; тоді потрібен дійсний `userHash`, інакше особа відкидається
`identify({ userId, userHash })`	Перевірена особа користувача	Так — криптографічно перевірено

Коли для каналу ввімкнено верифікацію особи, будь-який виклик identify() з email чи userId без дійсного userHash відкидається на боці сервера, і відвідувач залишається анонімним — див. «Верифікація особи (HMAC)» нижче.

Visitor ID зберігається між сесіями в тому самому браузері. Він ніколи не надсилається до Respondo як автентифікована особа — він використовується лише для безперервності анонімних розмов.

Ідентифікація лише за userId (без email чи імені)#

Якщо ваша платформа не має email чи імен користувачів — наприклад, у вас є лише внутрішній відображуваний ID — ви можете передати лише userId. Інші поля не потрібні. Панель показуватиме userId як є в деталях розмови.

userId + metadata (без email чи імені)javascript

// Ваша платформа має лише відображуваний ID — цього достатньо
Respondo.identify({
  userId: user.displayId,      // напр. "USR-4821" — показується в панелі
  metadata: {                  // необов’язковий додатковий контекст
    plan: 'premium',
    region: 'eu-west'
  }
});
// Email чи ім’я не потрібні — віджет працює лише з userId

Щоб запобігти підробці userId, поєднайте його з userHash (див. розділ «Верифікація особи» нижче). Без HMAC будь-хто може передати будь-який userId з консолі браузера.

Google Tag Manager / відкладений identify()#

Під час вбудовування через GTM дані користувача можуть бути недоступні на момент завантаження сторінки. Два підходи:

Варіант A: localStorageKey (не потрібен JS)javascript

// Якщо ваша платформа вже записує ID користувача в 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 — повідомленням — і надішліть результат на фронтенд. Якщо ви ідентифікуєте користувачів лише за email (без userId), підписуйте email: підписується userId, коли він заданий, інакше email. Якщо ви передаєте обидва, підписуйте 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()

# У вашому view / ендпоінті:
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
});