Перейти к содержимому

Документация

1. Выпустите токен на своём бэкенде

У вашего приложения есть ключ для подписи. Бэкенд и так знает, кто вошёл в систему, поэтому он подписывает недолговечный токен с именем этого пользователя. Сам ключ никогда не попадает в браузер.

import { createHmac } from 'node:crypto'

function mintToken(appId, userId, signingKey, ttlSeconds = 900) {
  const payload = {
    aid: appId,
    sub: userId,                                 // your own user id
    exp: Math.floor(Date.now() / 1000) + ttlSeconds,
    // tnt: workspaceId,                         // optional: one tenant's bell
  }
  const encoded = Buffer.from(JSON.stringify(payload)).toString('base64url')
  const signature = createHmac('sha256', signingKey).update(encoded).digest('base64url')
  return `${encoded}.${signature}`
}

2. Поместите колокольчик на страницу

<script src="https://notifybell.altixcode.com/embed/notify-bell.js" defer></script>

<notify-bell app-id="app_…" token="…" api-url="https://notifybell.altixcode.com"></notify-bell>

Это пользовательский элемент, поэтому он одинаково работает в React, Vue, Svelte, Rails или на обычной странице. Просто задайте атрибут token заново при обновлении — и элемент переподключится сам.

3. Отправляйте уведомления с бэкенда

curl -X POST https://notifybell.altixcode.com/api/v1/apps/APP_ID/notifications \
  -H "Authorization: Bearer nb_…" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriberId": "usr_99812",
    "title": "Deployment completed",
    "body": "Your production build v1.4.2 was deployed.",
    "category": "system",
    "actionUrl": "https://app.example.com/deployments/123",
    "dedupeKey": "deploy-123"
  }'

Подписчик создаётся при первой отправке, поэтому отдельный шаг синхронизации пользователей не нужен. Передайте dedupeKey — и повторная попытка из вашего обработчика задач не заставит колокольчик прозвенеть дважды.

SDK для сервера и React

Нужен типизированный клиент вместо голого HTTP? @notifybell/node публикует уведомления, делает рассылки и выпускает токены подписчиков, повторяя запросы при 429 и 5xx. @notifybell/react выводит колокольчик как компонент и обновляет его токен до истечения срока. Оба пакета под лицензией MIT и доступны в npm.

npm install @notifybell/node @notifybell/react

// server
import { NotifyBell, mintSubscriberToken } from '@notifybell/node'
const app = new NotifyBell({ apiKey: process.env.NOTIFYBELL_API_KEY }).app('app_123')
await app.publish({ subscriberId: user.id, title: 'Your export is ready' })
const token = mintSubscriberToken({ appId: 'app_123', subscriberId: user.id, signingKey })

// React
import { NotifyBell } from '@notifybell/react'
<NotifyBell appId="app_123" token={token} getToken={fetchFreshToken} />

Оформление

Элемент отрисовывается внутри shadow root, поэтому ваш CSS не может случайно изменить его вид, а его собственные стили не протекают на вашу страницу. Три части открыты намеренно:

notify-bell::part(bell)   { color: #64748b; }
notify-bell::part(badge)  { background: #2563eb; }
notify-bell::part(panel)  { border-radius: 4px; }

Язык, оформление и события

Атрибуты: app-id, token, api-url, lang. Свойство strings переводит каждое слово (title, markAll, all, unread, archived, archive, restore, markRead, markUnread, empty, more, required…), а strings.categories задаёт названия категорий. События: notify-bell:click и notify-bell:action можно отменить — вызовите preventDefault(), чтобы перейти внутри приложения вместо новой вкладки; notify-bell:token-expired просит новый токен. Тема берётся из панели; ваши CSS-свойства на элементе (--nb-accent, --nb-badge, --nb-radius) и ::part(bell | badge | panel | toast) важнее.

const bell = document.querySelector('notify-bell')
bell.strings = {
  title: 'Benachrichtigungen',
  markAll: 'Alle gelesen',
  categories: { billing: 'Rechnungen' },
}
bell.addEventListener('notify-bell:click', (event) => {
  event.preventDefault()            // route in-app instead of opening a tab
  router.push(event.detail.data.path)
})
bell.addEventListener('notify-bell:token-expired', async () => {
  bell.setAttribute('token', await fetchFreshToken())
})

/* CSS */
notify-bell { --nb-accent: #0f766e; --nb-badge: #b91c1c; --nb-radius: 8px; }

Вебхуки

Добавьте эндпоинт для каждого приложения на странице «Вебхуки», и NotifyBell будет отправлять на него события POST-запросами: notification.created, notification.read, notification.seen, notification.clicked, notification.archived, notification.retracted, subscriber.erased. Каждый запрос содержит NotifyBell-Signature (t=метка времени,v1=HMAC-SHA256 от "метка.тело" с секретом эндпоинта); отклоняйте всё, что не проходит проверку или старше пяти минут. Ответ не из 2xx повторяется через 1 минуту, 5 минут, 30 минут, 2 часа и 12 часов, затем помечается как неудачный и сохраняется для ручного повтора. Доставка как минимум один раз: дедуплицируйте по id в теле.

import { createHmac, timingSafeEqual } from 'node:crypto'

// rawBody: the request body exactly as received, before JSON parsing.
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  const age = Math.abs(Date.now() / 1000 - Number(parts.t))
  if (!parts.t || !parts.v1 || age > 300) return false
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest()
  const given = Buffer.from(parts.v1, 'hex')
  return given.length === expected.length && timingSafeEqual(given, expected)
}

Справочник API

Эндпоинты бэкенда принимают API-ключ (Authorization: Bearer nb_…). Эндпоинты ленты принимают токен Подписчика — в заголовке bearer или в ?token=.

Честные ограничения