Easy Notification System - Alpha System Plugins

Introdução

O Easy Notification System é uma biblioteca JavaScript abrangente para gerenciamento avançado de notificações em aplicações web. Ela oferece recursos poderosos, como priorização, filtragem por categoria, segmentação de usuários, analytics, customização visual, agendamento e persistência de notificações. Com ela, você pode exibir notificações dinâmicas, persistentes ou agendadas, além de ajustar comportamentos, animações, cores, sons e ações do usuário.

Principais funcionalidades do Easy Notification System:

Exibição simultânea de múltiplas notificações com controle de concorrência.
Filtragem por categorias e segmentação de usuários.
Customização completa de cores, estilos, animações e sons.
Prioridade, fila e agendamento de notificações.
Interações do usuário, como clique, hover e fechamento manual.
Métricas e eventos de analytics integrados.
Suporte a notificações nativas (do navegador) individualmente ou globalmente.
Persistência de notificações usando localStorage.
Gerenciamento de duplicatas e estratégias de fallback.
Extensível e fácil de integrar com outras partes da aplicação.

Características Principais

Suporte a Várias Notificações: Controle quantas notificações são exibidas simultaneamente e gerencie filas com tamanho máximo configurável.
Filtragem e Categorias: Agrupe notificações por categoria e aplique filtros para exibir somente as que desejar. Defina prioridades por categoria para controlar a ordem de exibição.
Segmentação de Usuários: Defina segmentos de usuários e mostre notificações específicas baseadas no perfil do usuário.
Prioridade e Fila: Ajuste a ordem de exibição com base em prioridade e categorias, permitindo uma gestão eficiente das notificações.
Agendamento: Agende notificações para o futuro ou exiba-as em momentos específicos utilizando timestamps.
Estilos, Animações e Sons Customizáveis: Personalize cores, animações (fade, slide, scale, flip ou animações customizadas), estilos e sons para criar experiências únicas.
Interações e Persistência: Adicione botões de fechamento, clique na notificação, persistência (sem tempo limite) e reações ao hover. Controle auto-dismissal baseado em cliques e movimentos do mouse.
Analytics Integrado: Colete métricas sobre exibição, cliques, tempo de interação e progresso das notificações.
Notificações Nativas: Opção de exibir notificações nativas do navegador para certas notificações ou de forma global.
Persistência de Notificações: Mantenha notificações persistentes usando localStorage, garantindo que elas permaneçam mesmo após recarregamentos da página.
Gerenciamento de Duplicatas e Fallback: Controle para evitar notificações duplicadas e estratégias de fallback para casos de falha na exibição.

Instalação

Para instalar o Easy Notification System, basta incluir o script JavaScript no seu HTML:

<script src="https://cdn.alphasystem.dev/plugins/easy-notification-system/latest/script-min.js"></script>

Após a inclusão do script, uma instância padrão será criada automaticamente e estará disponível como window.EasyNotificationInstance. Você pode utilizá-la diretamente para configurar e gerenciar notificações:

// Utiliza a instância padrão
const notifier = window.EasyNotificationInstance;

Configuração

O Easy Notification System oferece diversas opções de configuração. Ao utilizar a instância padrão, você pode sobrescrever as configurações globais para adaptar o comportamento às suas necessidades:

enabled: Ativa ou desativa o sistema de notificações (Padrão: true).
defaultDisplayTime: Tempo padrão de exibição em milissegundos (Padrão: 5000).
maxConcurrent: Máximo de notificações exibidas simultaneamente (Padrão: 15).
animationDuration: Duração da animação em milissegundos (Padrão: 300).
maxQueueSize: Tamanho máximo da fila de notificações (Padrão: 1000).
allowDuplicate: Permite notificações duplicadas (Padrão: false).
defaultType: Tipo padrão da notificação (ex: 'info', 'warning', 'success', 'danger'). Padrão: 'info'.
defaultCategory: Categoria padrão das notificações (Padrão: 'general').
segmentMatching: Habilita a correspondência de segmentos de usuário (Padrão: true).
priorityEnabled: Habilita a ordenação por prioridade (Padrão: true).
analyticsEnabled: Registra eventos de analytics (Padrão: true).
categoryFilteringEnabled: Permite filtrar notificações por categoria (Padrão: true).
userInteractionTracking: Acompanha interações do usuário (Padrão: true).
maxRetriesOnDisplayError: Número máximo de tentativas de reexibição em caso de erro (Padrão: 3).
containerId: ID personalizado para o container das notificações (Padrão: null).
animationType: Tipo de animação (ex: 'fade', 'slide', 'scale', 'flip' ou animações customizadas). Padrão: 'fade'.
customAnimations: Objeto contendo animações CSS customizadas.
customStyles: Objeto contendo estilos CSS customizados para as notificações.
fallbackStrategy: Estratégia de fallback em caso de erro na exibição ('queue', etc.) (Padrão: 'queue').
timeIncrementOnRetry: Incremento de tempo em milissegundos para tentativas de reexibição (Padrão: 1000).
categoryPriorities: Objeto definindo prioridades para categorias específicas.
userSegments: Objeto definindo segmentos de usuário.
globalFilters: Array de filtros globais para notificações.
autoDismissOnClick: Fecha a notificação ao clicar (Padrão: true).
autoDismissOnHoverOut: Fecha a notificação ao sair do hover (se habilitado) (Padrão: false).
hoverPause: Pausa o temporizador quando o mouse está sobre a notificação (Padrão: true).
retryOnFailure: Tenta reexibir notificações em caso de falha (Padrão: true).
position: Posição do container (ex: 'top-right', 'top-left', 'bottom-right', 'bottom-left'). Padrão: 'top-right'.
useNativeNotifications: Quando true, todas as notificações são exibidas como notificações nativas do navegador (Padrão: false).
defaultSound: URL do som padrão para notificações (Padrão: null).
showTimerBar: Exibe uma barra de temporizador na notificação (Padrão: true).

// Utilizando a instância padrão com configurações customizadas
window.EasyNotificationInstance.cfg = {
  maxConcurrent: 5,
  defaultType: 'info',
  position: 'bottom-left',
  animationType: 'slide',
  autoDismissOnHoverOut: true,
  useNativeNotifications: false,
  customAnimations: {
    bounceIn: '@keyframes bounceIn { from { transform: scale(0.3); opacity: 0; } to { transform: scale(1); opacity: 1; } }'
  },
  customStyles: {
    'div[data-notification-id]': {
      background: '#333',
      color: '#fff'
    }
  }
};

Uso e Integração

Após configurar, você pode criar e exibir notificações facilmente utilizando a instância padrão window.EasyNotificationInstance:

Criar Notificação: Use createNotification passando título, mensagem, tipo, etc. Este método retorna o ID da notificação criada.
Notificações Persistentes: Defina persistent: true para manter a notificação visível até ser fechada manualmente.
Agendar Notificações: Use scheduleNotification para exibir notificações no futuro.
Categorias e Segmentos: Ajuste category e segments para filtrar quem vê as notificações.
Notificações Nativas por Notificação: Defina nativeNotification: true em uma notificação específica para que ela seja exibida como notificação nativa do navegador, independentemente de useNativeNotifications global.
Fechamento Manual: Use dismissNotification passando o ID da notificação.
Controle da Barra de Progresso: Utilize métodos como increaseProgress, decreaseProgress e setProgress para manipular a barra de progresso das notificações.
Definir Dados do Usuário: Use setUserData para definir dados do usuário que serão usados na segmentação.
Definir Segmentos de Usuário: Use defineSegment para criar segmentos personalizados.
Gerenciar Categorias: Use allowCategory e blockCategory para controlar quais categorias de notificações são exibidas.
Gerenciar Prioridades de Categoria: Use setCategoryPriority para definir prioridades específicas para categorias.
Eventos: Use on para escutar eventos como 'show', 'click', 'hide', 'displayed', 'progress_increase', 'progress_decrease', 'progress_set' e triggerEvent para disparar eventos customizados.
Analytics: Use getAnalytics para obter logs de analytics e clearAnalytics para limpar os logs.
Requisição de Permissão: Use requestPermission para solicitar permissão para notificações nativas.
Reproduzir Som: Use playSound para reproduzir um som específico para uma notificação.

Exemplo básico:

const notifier = window.EasyNotificationInstance;

const notificationId = notifier.createNotification({
  title: 'Olá!',
  message: 'Esta é uma notificação de teste.',
  type: 'info',
  displayTime: 3000
});

console.log('ID da Notificação:', notificationId);

Notificação persistente (sem tempo limite):

const persistentNotifId = notifier.createNotification({
  title: 'Atenção',
  message: 'Esta notificação só fechará se você clicar no X.',
  type: 'warning',
  persistent: true
});

Notificação nativa individual:

const nativeNotifId = notifier.createNotification({
  title: 'Notificação do Sistema',
  message: 'Esta notificação é nativa do navegador.',
  nativeNotification: true
});

Controle da Barra de Progresso:

// Criar uma notificação com barra de progresso
const progressNotifId = notifier.createNotification({
  title: 'Processando',
  message: 'O processo está em andamento...',
  type: 'info',
  hasProgressBar: true,
  displayTime: 10000,
  onClick: (n) => console.log('Notificação clicada:', n)
});

// Simular o progresso
let progress = 0;
const progressInterval = setInterval(() => {
  progress += 10;
  if (progress > 100) {
    clearInterval(progressInterval);
  } else {
    notifier.increaseProgress(progressNotifId, 10);
  }
}, 1000);

Agendar uma notificação para 10 segundos no futuro:

const futureTime = Date.now() + 10000; // 10 segundos no futuro
const scheduledNotifId = notifier.scheduleNotification({
  title: 'Lembrete',
  message: 'Esta notificação aparecerá em 10 segundos.',
  type: 'warning',
  time: futureTime
});

console.log('ID da Notificação Agendada:', scheduledNotifId);

Reproduzir Som em uma Notificação

// Criar uma notificação com som customizado
const soundNotifId = notifier.createNotification({
  title: 'Alerta Sonoro',
  message: 'Esta notificação reproduz um som específico.',
  type: 'danger',
  sound: 'https://example.com/sounds/alert.mp3'
});

// Reproduzir um som específico manualmente
notifier.playSound('https://example.com/sounds/notification.mp3');

Referência da API

Métodos Principais

createNotification(params): Cria e adiciona uma notificação à fila.
Parâmetros: { title, message, type, category, priority, displayTime, segments, onClick, onFinished, persistent, nativeNotification, hasProgressBar, progress, animationType, position, autoDismissOnHoverOut, sound, showTimerBar, redirect }
Retorno: string - ID da notificação criada.
Observação: nativeNotification: true faz com que apenas essa notificação seja exibida nativamente, independentemente de useNativeNotifications global.
scheduleNotification(params): Agenda uma notificação para ser exibida no futuro.
Parâmetros: { title, message, type, category, priority, displayTime, segments, onClick, onFinished, persistent, nativeNotification, hasProgressBar, progress, animationType, position, autoDismissOnHoverOut, sound, showTimerBar, redirect, time }
Retorno: string - ID da notificação agendada.
setUserData(data): Define dados do usuário para segmentação.
Parâmetros: object - Dados do usuário.
defineSegment(name, fn): Define um segmento de usuário com uma função de critério.
Parâmetros: string - Nome do segmento; function - Função que recebe userData e retorna true ou false.
allowCategory(cat): Permite exibir notificações de determinada categoria.
Parâmetros: string - Nome da categoria.
blockCategory(cat): Bloqueia exibição de determinada categoria.
Parâmetros: string - Nome da categoria.
setCategoryPriority(cat, val): Ajusta prioridade de uma categoria.
Parâmetros: string - Nome da categoria; number - Valor da prioridade.
on(event, fn): Escuta eventos (ex.: 'show', 'click', 'hide', 'displayed', 'progress_increase', 'progress_decrease', 'progress_set').
Parâmetros: string - Nome do evento; function - Função callback.
triggerEvent(event, data): Dispara eventos customizados.
Parâmetros: string - Nome do evento; any - Dados associados ao evento.
getAnalytics(): Retorna logs de analytics.
Retorno: array - Lista de eventos registrados.
clearAnalytics(): Limpa logs de analytics.
dismissNotification(id): Fecha a notificação com o ID fornecido.
Parâmetros: string - ID da notificação.
increaseProgress(id, amount, newMessage): Aumenta a barra de progresso da notificação especificada em uma quantidade.
Parâmetros: string - ID da notificação; number - Quantidade a aumentar; string - Nova mensagem opcional.
decreaseProgress(id, amount, newMessage): Diminui a barra de progresso da notificação especificada em uma quantidade.
Parâmetros: string - ID da notificação; number - Quantidade a diminuir; string - Nova mensagem opcional.
setProgress(id, value, newMessage): Define a barra de progresso da notificação especificada para um valor específico.
Parâmetros: string - ID da notificação; number - Valor da progressão (0-100); string - Nova mensagem opcional.
playSound(soundUrl): Reproduz um som específico.
Parâmetros: string - URL do arquivo de áudio.
Retorno: Promise - Promessa que resolve quando o som é reproduzido ou rejeita em caso de erro.
requestPermission(): Solicita permissão para exibir notificações nativas do navegador.
Retorno: Promise - Resultado da permissão.
markAsFinished(id, reason): Marca a notificação como finalizada, fechando-a.
Parâmetros: string - ID da notificação; string - Razão do fechamento (opcional, padrão: 'manual').
clearAllNotifications(): Remove todas as notificações ativas e limpa a fila de notificações.

Eventos Disponíveis

show: Disparado quando uma notificação está prestes a ser exibida.
click: Disparado quando o usuário clica na notificação.
hide: Disparado quando uma notificação é fechada.
displayed: Disparado quando a notificação efetivamente aparece na tela.
progress_increase: Disparado quando a barra de progresso é aumentada.
progress_decrease: Disparado quando a barra de progresso é diminuída.
progress_set: Disparado quando a barra de progresso é definida para um valor específico.

Resolução de Problemas

Notificações Não Aparecem: Verifique se o container é criado e se maxConcurrent não está zero. Confira também se as categorias não estão bloqueadas e se os segmentos do usuário estão corretos.
Eventos Não Disparam: Certifique-se de usar on antes de criar notificações para que os eventos sejam escutados corretamente.
AutoDismissOnHoverOut Não Funciona: Garanta que a opção autoDismissOnHoverOut esteja habilitada e que não esteja usando persistent ao mesmo tempo.
Animações Não Aplicam: Verifique a propriedade animationType e se as animações customizadas estão corretamente definidas. Confirme também se o CSS é suportado no navegador.
Notificações Nativas Não Aparecem: Certifique-se de que o usuário concedeu permissão para notificações do navegador. Caso nativeNotification não funcione individualmente, verifique as permissões ou a compatibilidade do navegador.
Barra de Tempo Não Aparece: Assegure-se de que a notificação tem a propriedade displayTime definida e que a animação está configurada corretamente.
Controle da Barra de Progresso Não Funciona: Verifique se a notificação possui hasProgressBar: true e se o ID fornecido está correto. Além disso, assegure-se de que métodos como increaseProgress, decreaseProgress e setProgress estão sendo chamados corretamente.
Persistência de Notificações Não Funciona: Verifique se a notificação está definida como persistent: true e se o navegador suporta o uso de localStorage.
Problemas com Segmentação de Usuário: Confirme se os segmentos estão definidos corretamente usando defineSegment e se os dados do usuário estão sendo passados corretamente com setUserData.
Problemas com Prioridades de Categoria: Certifique-se de que as prioridades estão definidas corretamente usando setCategoryPriority e que as categorias estão permitidas com allowCategory.
Erros na Requisição de Permissão: Verifique se a função requestPermission está sendo chamada no contexto correto e se não há restrições de CORS ou outras limitações do navegador.
Falha na Reprodução de Sons: Assegure-se de que a URL do som está correta e que o formato do áudio é suportado pelo navegador. Verifique também se há bloqueadores de áudio ativos.
Problemas com Notificações Persistentes: Verifique se a notificação está sendo corretamente salva no localStorage e se não há conflitos com outras instâncias ou scripts.

Exemplos de Código

Exemplo Básico

const notifier = window.EasyNotificationInstance;

const notificationId = notifier.createNotification({
  title: 'Olá!',
  message: 'Esta é uma notificação de teste.',
  type: 'info',
  displayTime: 3000
});

console.log('ID da Notificação:', notificationId);

Notificação com Segmentação de Usuário

const notifier = window.EasyNotificationInstance;

notifier.defineSegment('premium', (userData) => userData.isPremium === true);
notifier.setUserData({ isPremium: true });

const premiumNotifId = notifier.createNotification({
  title: 'Premium User',
  message: 'Obrigado por ser um usuário premium!',
  type: 'success',
  segments: ['premium']
});

console.log('ID da Notificação Premium:', premiumNotifId);

Agendamento de Notificação

const notifier = window.EasyNotificationInstance;

const futureTime = Date.now() + 10000; // 10 segundos no futuro
const scheduledNotifId = notifier.scheduleNotification({
  title: 'Lembrete',
  message: 'Esta notificação aparecerá em 10 segundos.',
  type: 'warning',
  time: futureTime
});

console.log('ID da Notificação Agendada:', scheduledNotifId);

Notificação Persistente com Fechamento Manual

const notifier = window.EasyNotificationInstance;

const notificacaoImportanteId = notifier.createNotification({
  title: 'Ação Necessária',
  message: 'Clique no X para fechar esta notificação persistente.',
  type: 'danger',
  persistent: true,
  onClick: (n) => console.log('Notificação clicada:', n)
});

// Exemplo de fechamento manual após 30 segundos
setTimeout(() => {
  notifier.dismissNotification(notificacaoImportanteId);
}, 30000);

Controle da Barra de Progresso

const notifier = window.EasyNotificationInstance;

// Criar uma notificação com barra de progresso
const progressNotifId = notifier.createNotification({
  title: 'Processando',
  message: 'O processo está em andamento...',
  type: 'info',
  hasProgressBar: true,
  displayTime: 10000,
  onClick: (n) => console.log('Notificação clicada:', n)
});

// Simular o progresso
let progress = 0;
const progressInterval = setInterval(() => {
  progress += 10;
  if (progress > 100) {
    clearInterval(progressInterval);
  } else {
    notifier.increaseProgress(progressNotifId, 10);
  }
}, 1000);

Definir Dados do Usuário e Segmentação

const notifier = window.EasyNotificationInstance;

// Definir dados do usuário
notifier.setUserData({
  isLoggedIn: true,
  role: 'admin'
});

// Definir segmentos
notifier.defineSegment('admin', (userData) => userData.role === 'admin');
notifier.defineSegment('loggedIn', (userData) => userData.isLoggedIn === true);

// Criar uma notificação para administradores logados
const adminNotifId = notifier.createNotification({
  title: 'Admin Access',
  message: 'Você tem acesso total ao sistema.',
  type: 'success',
  segments: ['admin', 'loggedIn']
});

console.log('ID da Notificação Admin:', adminNotifId);

Gerenciar Categorias e Prioridades

const notifier = window.EasyNotificationInstance;

// Permitir apenas notificações de categorias 'alert' e 'system'
notifier.allowCategory('alert');
notifier.allowCategory('system');

// Bloquear a categoria 'marketing'
notifier.blockCategory('marketing');

// Definir prioridades para categorias
notifier.setCategoryPriority('system', 10);
notifier.setCategoryPriority('alert', 5);
notifier.setCategoryPriority('marketing', 1);

// Criar notificações de diferentes categorias
notifier.createNotification({
  title: 'Sistema Atualizado',
  message: 'O sistema foi atualizado com sucesso.',
  type: 'success',
  category: 'system'
});

notifier.createNotification({
  title: 'Promoção Especial',
  message: 'Aproveite nossa promoção de 50% de desconto!',
  type: 'info',
  category: 'marketing'
});

Usar Animações Customizadas

const notifier = window.EasyNotificationInstance;

// Definir animações customizadas
const customAnimations = {
  bounceIn: `@keyframes bounceIn {
    from { transform: scale(0.3); opacity: 0; }
    to { transform: scale(1); opacity: 1; }
  }`,
  bounceOut: `@keyframes bounceOut {
    from { transform: scale(1); opacity: 1; }
    to { transform: scale(0.3); opacity: 0; }
  }`
};

// Atualizar configurações com animações customizadas
notifier.cfg.customAnimations = customAnimations;
notifier.cfg.animationType = 'bounce';

// Criar uma notificação usando a animação customizada
notifier.createNotification({
  title: 'Novo Evento',
  message: 'Você tem um novo evento no calendário.',
  type: 'info',
  animationType: 'bounce'
});

Reproduzir Som em uma Notificação

const notifier = window.EasyNotificationInstance;

// Criar uma notificação com som customizado
const soundNotifId = notifier.createNotification({
  title: 'Alerta Sonoro',
  message: 'Esta notificação reproduz um som específico.',
  type: 'danger',
  sound: 'https://example.com/sounds/alert.mp3'
});

// Reproduzir um som específico manualmente
notifier.playSound('https://example.com/sounds/notification.mp3');

Fechamento Manual de Notificação

const notifier = window.EasyNotificationInstance;

// Criar uma notificação
const notifId = notifier.createNotification({
  title: 'Fechamento Manual',
  message: 'Esta notificação será fechada manualmente.',
  type: 'info'
});

// Fechar a notificação após 5 segundos
setTimeout(() => {
  notifier.markAsFinished(notifId, 'manual');
  console.log('Notificação fechada manualmente:', notifId);
}, 5000);