Подтверждение личности вошедших пользователей

Если на вашем сайте или в приложении пользователи входят в аккаунт, виджет может их распознать. Тогда человек видит свои диалоги на любом устройстве, а команда видит один контакт вместо нескольких анонимных.

Зачем нужна подпись

Браузеру доверять нельзя: любой может вызвать identify с чужой эл. почтой. Поэтому ваш сервер вычисляет userHash, подпись HMAC-SHA256 с ключом подтверждения, который браузер никогда не видит.

Ключ подтверждения

Ключ находится в настройках чат-виджета на вкладке «Подтверждение личности». Видеть и менять его могут только владельцы.

• Храните ключ только на сервере, например в переменной SUPPORT_IDENTITY_SECRET. Никогда не вставляйте его в код браузера.
• После создания нового ключа старый работает ещё 24 часа, чтобы вы успели обновить сервер.

app.hrc.lt

Что подписывать

Подпись вычисляется из строки v1:<ID>:<эл. почта>. Эл. почта без пробелов по краям и строчными буквами; недостающая часть остаётся пустой.

v1:<externalId>:<эл. почта без пробелов по краям, строчными буквами>

v1:12345:jonas@example.com   ID и эл. почта
v1:12345:                    только ID
v1::jonas@example.com        только эл. почта, нужна настройка
                             «Моё приложение проверяет адреса эл. почты»

userHash это HMAC-SHA256 этой строки с ключом подтверждения, записанный 64 шестнадцатеричными символами.

Код для сервера

Node.js:

// Node.js (Express): ваш endpoint, только для вошедшего пользователя
import { createHmac } from 'node:crypto';

app.get('/api/support-hash', requireLogin, (req, res) => {
  const user = req.user;
  const email = (user.email ?? '').trim().toLowerCase();
  const canonical = `v1:${user.id ?? ''}:${email}`;
  const userHash = createHmac('sha256', process.env.SUPPORT_IDENTITY_SECRET)
    .update(canonical)
    .digest('hex');
  res.json({ userHash });
});

PHP:

<?php
// PHP: mb_strtolower, не strtolower, чтобы Ж и Ё тоже стали строчными
$email = mb_strtolower(trim($user->email ?? ''), 'UTF-8');
$canonical = 'v1:' . ($user->id ?? '') . ':' . $email;
$secret = getenv('SUPPORT_IDENTITY_SECRET');
$userHash = hash_hmac('sha256', $canonical, $secret);

Python:

# Python
import hashlib
import hmac
import os

user_id = "" if user.id is None else str(user.id)
email = (user.email or "").strip().lower()
canonical = f"v1:{user_id}:{email}"
secret = os.environ["SUPPORT_IDENTITY_SECRET"].encode()
user_hash = hmac.new(secret, canonical.encode(), hashlib.sha256).hexdigest()

Код для браузера

Всегда передавайте externalId строкой: число игнорируется.

// В браузере: получите подпись пользователя от своего сервера
const { userHash } = await fetch('/api/support-hash', {
  credentials: 'include',
}).then((r) => r.json());
HrcWidget('identify', {
  externalId: String(user.id ?? ''),
  email: user.email,
  name: user.name,
  userHash,
});

// При выходе
HrcWidget('reset');

С identify можно передать и поля профиля, смотрите Профиль посетителя.

«Моё приложение проверяет адреса эл. почты»

Включайте, только если ваше приложение проверяет, что эл. почта принадлежит пользователю (отправляет код или ссылку). Тогда подписанная эл. почта объединяет письма и диалоги одного человека в один контакт во всех чат-виджетах и почтовых ящиках.

Пока эта настройка выключена, всегда передавайте externalId пользователя. Подписанная эл. почта без ID отклоняется с ошибкой IDENTITY_INVALID, а эл. почта считается не подтверждённой, пока человек не ответит на наше письмо.

Только для вошедших

Режим «Только для вошедших» разрешает писать только распознанным пользователям. Анонимная сессия не может отправлять сообщения и менять профиль (IDENTITY_REQUIRED).

Проверьте подпись

В настройках есть поле проверки вычисленного значения: введите ID, эл. почту и значение, вычисленное на сервере, и приложение скажет, подходит ли оно. Проверка выполняется на сервере, ключ в браузер не отправляется. Если не подходит, проверьте, что эл. почта в нижнем регистре и что вы используете ключ этого виджета.

Ошибку вы видите и на своём сайте: HrcWidget('on', 'identify-failed', ...) получает код, но никогда не саму подпись.

Выход

Когда пользователь выходит, вызовите HrcWidget('reset'). Виджет забудет сессию, и следующий человек на том же устройстве не увидит чужих диалогов.