Documentazione
1. Genera un token nel tuo backend
La tua app ha una chiave di firma. Il tuo backend sa già chi ha effettuato l'accesso, quindi firma un token di breve durata che indica quell'utente. La chiave non raggiunge mai il browser.
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. Inserisci la campanella nella pagina
<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>È un elemento personalizzato, quindi funziona allo stesso modo in React, Vue, Svelte, Rails o in una pagina HTML semplice. Imposta di nuovo l'attributo token quando lo rinnovi e l'elemento si riconnetterà da solo.
3. Pubblica dal tuo backend
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"
}'L'iscritto viene creato alla prima pubblicazione, quindi non serve alcun passaggio di sincronizzazione degli utenti. Passa una dedupeKey e un nuovo tentativo del tuo job runner non farà suonare la campanella due volte.
SDK per server e React
Preferisci un client tipizzato all’HTTP grezzo? @notifybell/node pubblica, invia broadcast e genera i token degli iscritti, con nuovi tentativi su 429 e 5xx. @notifybell/react mostra la campanella come componente e rinnova il token prima che scada. Entrambi hanno licenza MIT e sono su 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} />Personalizzare lo stile
L'elemento viene renderizzato in uno shadow root, così il tuo CSS non può modificarne lo stile per errore e i suoi stili non possono interferire con la tua pagina. Tre parti sono esposte intenzionalmente:
notify-bell::part(bell) { color: #64748b; }
notify-bell::part(badge) { background: #2563eb; }
notify-bell::part(panel) { border-radius: 4px; }Lingua, tema ed eventi
Attributi: app-id, token, api-url, lang. La proprietà strings traduce ogni parola (title, markAll, all, unread, archived, archive, restore, markRead, markUnread, empty, more, required…) e strings.categories dà un nome alle categorie. Eventi: notify-bell:click e notify-bell:action sono annullabili: chiama preventDefault() per navigare nell’app invece di aprire una scheda; notify-bell:token-expired chiede un nuovo token. Il tema arriva dalla dashboard; le tue proprietà CSS sull’elemento (--nb-accent, --nb-badge, --nb-radius) e ::part(bell | badge | panel | toast) hanno la precedenza.
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; }Webhook
Aggiungi un endpoint per app nella pagina Webhook e NotifyBell vi invia gli eventi in POST: notification.created, notification.read, notification.seen, notification.clicked, notification.archived, notification.retracted, subscriber.erased. Ogni richiesta include NotifyBell-Signature (t=timestamp,v1=HMAC-SHA256 di "timestamp.corpo" con il segreto dell’endpoint); rifiuta ciò che non si verifica o ha più di cinque minuti. Una risposta non 2xx viene ritentata dopo 1 minuto, 5 minuti, 30 minuti, 2 ore e 12 ore, poi segnata come fallita e conservata per un nuovo tentativo manuale. Consegna almeno una volta: deduplica sull’id del payload.
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)
}Riferimento API
Gli endpoint di backend richiedono una chiave API (Authorization: Bearer nb_…). Quelli della inbox richiedono un token di Iscritto, come header bearer o ?token=.
POST/api/v1/apps/{appId}/notifications
Pubblica per un iscritto (subscriberId) o fino a 100 (subscriberIds). Facoltativi: body, category, actionUrl, iconUrl, data (oggetto JSON fino a 4 KB), priority, dedupeKey, actions (fino a due pulsanti {label, url}), expiresAt (ISO 8601, entro un anno), template con variables, sendAt (consegna differita, entro 90 giorni). batch: {key, windowSeconds (60–86400), title con {{ count }}} raggruppa una raffica in una notifica per iscritto; non con sendAt. tenant: l’id del tuo workspace; una campanella il cui token porta tnt mostra le notifiche di quel tenant e quelle senza.
Chiave API
PATCH · DELETE/api/v1/apps/{appId}/notifications/{id}
PATCH riscrive una notifica inviata (title, body, actionUrl, iconUrl, data, actions; null cancella) senza un secondo avviso. DELETE la ritira dalla casella. Le campanelle aperte si aggiornano subito.
Chiave API
DELETE/api/v1/apps/{appId}/notifications?dedupeKey=…
Ritira ogni copia inviata con quella chiave di deduplica: così si annulla un invio a tutti. Gli invii programmati e dalla dashboard usano scheduled:<id>.
Chiave API
POST/api/v1/apps/{appId}/broadcasts
Pubblica per tutti gli iscritti dell’app o, con topic, per chi segue l’argomento. Stessi campi facoltativi di una pubblicazione, inclusi template e sendAt. Con un dedupeKey un nuovo tentativo non notifica due volte.
Chiave API
GET · DELETE/api/v1/apps/{appId}/scheduled[/{id}]
GET elenca gli invii programmati con stato e numero di consegne. DELETE /scheduled/{id} annulla un invio non ancora partito.
Chiave API
GET/api/v1/apps/{appId}/templates
I modelli modificati nella dashboard. Pubblicane uno con template: "key" e variables: { … }; una variabile mancante restituisce un 400 che la nomina.
Chiave API
GET/api/v1/apps/{appId}/subscribers
Gli iscritti dell’app, i più recentemente attivi per primi: limit (1–100), cursor. Si creano pubblicando loro.
Chiave API
GET · PUT/api/v1/apps/{appId}/subscribers/{externalId}/topics
Legge o sostituisce gli argomenti seguiti da un iscritto ({topics: [...]}, fino a 100). GET /topics elenca ogni argomento con il numero di iscritti.
Chiave API
GET · PATCH · DELETE/api/v1/apps/{appId}/subscribers/{externalId}
Consulta, aggiorna (email, name; null cancella) o elimina un iscritto con tutte le sue notifiche.
Chiave API
GET/api/v1/apps/{appId}/me/feed
Una pagina della casella: limit (1–100), cursor, unreadOnly=true, archived=true, snoozed=true, category=a,b (solo quelle categorie). Le notifiche scadute sono escluse. Restituisce i conteggi non lette e non viste.
Token di Iscritto
GET/api/v1/apps/{appId}/me/stream
Server-Sent Events: ready, notification, read, unread, read-all, seen, archive, archive-read, update, retract, snooze.
Token di Iscritto
POST/api/v1/apps/{appId}/me/read
Segna una come letta ({notificationId}), tutte come lette ({all: true}) o una come non letta ({notificationId, read: false}).
Token di Iscritto
POST/api/v1/apps/{appId}/me/click
L’utente ha agito su una notifica ({notificationId}, action facoltativa: 0 o 1 per un pulsante). La segna anche come letta; conta come clic nelle analisi.
Token di Iscritto
POST/api/v1/apps/{appId}/me/seen
Segna tutto come visto ({all: true}): chiamalo quando si apre la campanella.
Token di Iscritto
POST/api/v1/apps/{appId}/me/archive
Archivia una notifica ({notificationId}) o ripristinala ({notificationId, archived: false}). Oppure tutte quelle già lette in una volta: {allRead: true, categories?}.
Token di Iscritto
POST/api/v1/apps/{appId}/me/snooze
Posticipare una notifica fino a un momento ({notificationId, until}: ISO 8601, al massimo 30 giorni). Esce subito dal feed e dai contatori e torna non letta. until: null la termina prima.
Token di Iscritto
POST/api/v1/apps/{appId}/me/delete
Eliminare per sempre una propria notifica ({notificationId}). L’archiviazione la conserva, questo no.
Token di Iscritto
GET · PATCH/api/v1/apps/{appId}/me/preferences
Leggi e imposta le scelte per categoria ({category, enabled}). Le categorie obbligatorie hanno required: true e non si possono disattivare.
Token di Iscritto
GET/api/v1/apps/{appId}/me/config
Il tema e le etichette delle categorie impostati nella dashboard. L’embed li legge al caricamento, quindi una modifica non richiede deploy.
Token di Iscritto
Limiti dichiarati
- La distribuzione in tempo reale passa da Redis. Ogni istanza inoltra le nuove notifiche tramite un unico canale Redis, così una campanella connessa ovunque riceve una pubblicazione gestita ovunque. Se Redis non è raggiungibile per poco, ogni istanza continua a servire le proprie connessioni, e non si perde mai nulla, perché la inbox è salvata e non riprodotta.
- Non ci sono email, SMS o notifiche push. È una scelta deliberata. Se ti serve un routing multicanale, questo non è il prodotto giusto.
- Uno stream resta aperto per quindici minuti, poi viene chiuso e il browser si riconnette con il token che l'elemento ha in quel momento. Anche i token degli Iscritti durano quindici minuti per impostazione predefinita, quindi reimposta l'attributo token prima della scadenza: con un token scaduto la campanella smette di aggiornarsi finché non lo fai. L'elemento emette un evento notify-bell:token-expired quando il suo token viene rifiutato, così la tua pagina può ottenerne uno nuovo in quel momento.
- I token durano al massimo 24 ore. Un token di Iscritto la cui scadenza è a più di un giorno viene rifiutato, chiunque l'abbia emesso: così un token firmato con una chiave che poi ruoti non può sopravviverle a lungo.
- Le richieste hanno un limite di frequenza. La pubblicazione consente 1.200 richieste al minuto per chiave API; ogni Iscritto ha 120 richieste di inbox al minuto e fino a 5 stream aperti. Oltre, l'API risponde 429 con un'intestazione Retry-After.