novuhq/novu

¿Qué hace novu?

Integra la bandeja de entrada de notificaciones en la aplicación de Novu en aplicaciones web. Compatible con React, Next.js y JavaScript vanilla. Incluye el componente Inbox (icono de campana + feed de notificaciones), componentes componibles (Bell, Notifications, InboxContent, Preferences), hooks sin cabeza, tematización de marca, props de renderizado personalizados, multi-tenencia mediante contextos, pestañas, localización y seguridad HMAC. Úsalo para añadir un centro de notificaciones en la aplicación, un icono de campana, un feed de notificaciones, actualizaciones de notificaciones en tiempo real o construir una experiencia de notificaciones personalizada.

Requisitos previos

• Una cuenta de Novu y un entorno configurado (NOVU_APPLICATION_ID).
• Para la función de campana/feed de notificaciones en React o Next.js, instala el paquete @novu/react.
• Para JavaScript vanilla, instala @novu/js.

Configuración

React / Next.js

1. Instala el paquete:

npm install @novu/react

2. Envuelve tu aplicación con el proveedor NovuProvider, pasando el applicationId de tu entorno de Novu:

import { NovuProvider } from '@novu/react';

function App() {
  return (
    <NovuProvider applicationId={import.meta.env.VITE_NOVU_APPLICATION_ID}>
      <Inbox />
    </NovuProvider>
  );
}

3. Para autenticación de usuario (notificaciones dirigidas), pasa subscriberId y opcionalmente un token HMAC firmado:

<NovuProvider
  applicationId="<APPLICATION_ID>"
  subscriberId="<SUBSCRIBER_ID>"
  token="<HMAC_TOKEN>"
>
  <Inbox />
</NovuProvider>

JavaScript vanilla

1. Instala el paquete:

npm install @novu/js

2. Usa el hook useInbox o la función createInbox:

import { createInbox } from '@novu/js';

const inbox = createInbox({
  applicationId: '<APPLICATION_ID>',
  subscriberId: '<SUBSCRIBER_ID>',
});

inbox.notifications
  .on('update', (data) => {
    console.log('Notificaciones actualizadas', data);
  })
  .catch((error) => {
    console.error('Error al suscribirse a notificaciones', error);
  });

Componentes

• Inbox: Componente todo en uno que renderiza el icono de campana y el feed de notificaciones. Se posiciona automáticamente en la pantalla.
• Bell: Solo el icono de campana.
• Notifications: Solo la lista de notificaciones y el feed.
• InboxContent: El contenido de la bandeja de entrada sin el icono de campana adjunto.
• Preferences: Gestión de preferencias de notificaciones para el usuario.

Props de renderizado personalizados

Puedes personalizar el aspecto de los componentes pasando props de renderizado renderBell, renderNotification, renderAction, renderEmpty y renderPreferences:

import { Inbox } from '@novu/react';

function CustomNotification({ notification }) {
  return (
    <div style={{ padding: '10px', borderBottom: '1px solid #eee' }}>
      <strong>{notification.subject}</strong>
      <p>{notification.body}</p>
    </div>
  );
}

function App() {
  return (
    <NovuProvider applicationId="<APP_ID>">
      <Inbox renderNotification={CustomNotification} />
    </NovuProvider>
  );
}

Pestañas

Las pestañas te permiten filtrar notificaciones (por ejemplo, 'Sin leer', 'Archivadas'). Pasa una prop tabs:

<Inbox
  tabs={[
    { label: 'Sin leer', filter: { read: false } },
    { label: 'Archivadas', filter: { archived: true } },
  ]}
/>

Localización

La bandeja de entrada de Novu admite localización. Pasa una prop localization con un objeto de cadenas traducidas:

<Inbox
  localization={{
    'inbox.title': 'Notificaciones',
    'inbox.actions.markAsRead': 'Marcar como leído',
    'inbox.actions.archive': 'Archivar',
  }}
/>

También puedes pasar el locale a NovuProvider para mensajes predefinidos:

<NovuProvider applicationId="<APP_ID>" localization={{ lang: 'es' }}>
  <Inbox />
</NovuProvider>

Configuración de múltiples inquilinos (Multi-tenancy)

Si tu aplicación tiene una arquitectura multiinquilino, puedes pasar un tenantIdentifier para filtrar notificaciones por inquilino:

<NovuProvider applicationId="<APP_ID>" subscriberId="<SUB_ID>" tenantIdentifier="<TENANT_ID>">
  <Inbox />
</NovuProvider>

Seguridad HMAC

Para evitar que usuarios no autorizados accedan a notificaciones, usa tokens HMAC. Genera un HMAC SHA-256 usando tu secretKey de Novu y el subscriberId. Pasa el token resultante al NovuProvider:

// Ejemplo del lado del servidor (Node.js)
const crypto = require('crypto');
const hmac = crypto.createHmac('sha256', process.env.NOVU_SECRET_KEY);
hmac.update(subscriberId);
const token = hmac.digest('hex');

// Pasa esto a tu frontend

Uso con Next.js

En Next.js con App Router, asegúrate de que el componente esté marcado como 'use client' ya que usa hooks:

// components/InboxWrapper.tsx
'use client';
import { NovuProvider, Inbox } from '@novu/react';

export default function InboxWrapper() {
  return (
    <NovuProvider applicationId={process.env.NEXT_PUBLIC_NOVU_APPLICATION_ID}>
      <Inbox />
    </NovuProvider>
  );
}

Hooks sin cabeza (Headless hooks)

Para control total, usa hooks como useInbox, useNotifications, useBell, usePreferences:

import { useInbox } from '@novu/react';

function CustomInbox() {
  const { notifications, markAsRead, archive, markAsArchived } = useInbox();

  return (
    <div>
      {notifications.map((notification) => (
        <div key={notification.id}>
          <span>{notification.subject}</span>
          <button onClick={() => markAsRead(notification.id)}>Leído</button>
          <button onClick={() => archive(notification.id)}>Archivar</button>
        </div>
      ))}
    </div>
  );
}

Más información

• Documentación de Novu
• Componente de bandeja de entrada React
• Componente de bandeja de entrada JavaScript
• Seguridad HMAC