Introdução

Acione notificações e mensagens automatizadas com base em eventos do sistema.

🎯 O que este módulo faz?

O módulo Events permite que você configure notificações automatizadas que são acionadas quando algo acontece em seu sistema - como enviar um e-mail quando um produto está de volta em estoque ou uma notificação push quando um pedido é enviado.

Pense nisso como seu sistema de automação de notificações - você define o gatilho (o que acontece) e a ação (quem é notificado e como).

📖 Explicação Simples

Imagine que você está gerenciando uma loja online e deseja manter os usuários informados:

• 📦 Pedido realizado → Enviar e-mail de confirmação
• 🚚 Pedido enviado → Enviar notificação push com rastreamento
• ✅ Produto de volta em estoque → Notificar usuários que solicitaram alertas
• 💳 Pagamento recebido → Enviar e-mail de recibo
• 🎉 Nova promoção → Enviar e-mail de marketing para assinantes
• ⚠️ Senha alterada → Enviar alerta de segurança

Em vez de codificar manualmente cada notificação:

• ✅ Configure eventos no painel de administração do OneEntry
• ✅ Defina gatilhos (o que acontece)
• ✅ Configure ações (notificações a serem enviadas)
• ✅ Personalize mensagens por evento
• ✅ Acompanhe a entrega e o engajamento

Exemplo do mundo real:

Sem o Módulo de Eventos (manual):
- Usuário se registra → Escrever código para enviar e-mail ❌
- Produto reabastecido → Escrever código para notificar usuários ❌
- Cada evento precisa de código personalizado ❌

Com o Módulo de Eventos (automatizado):
- Configurar evento "Usuário Registrado" → Envia automaticamente e-mail de boas-vindas ✅
- Configurar evento "Produto Reabastecido" → Notifica automaticamente a lista de espera ✅
- Todos os eventos gerenciados em um só lugar ✅

✨ Conceitos Chave

O que é um Evento?

Um evento é algo que acontece em seu sistema que pode acionar notificações:

• Gatilho - A ação que inicia o evento (por exemplo, "pedido realizado")
• Notificação - O que os usuários recebem (e-mail, push, mensagem de socket)
• Destinatários - Quem é notificado (usuários específicos, todos os usuários, administradores)
• Modelo - O conteúdo da mensagem

Tipos de Evento

O OneEntry suporta diferentes tipos de gatilhos:

Tipo de Gatilho	Quando É Acionado	Exemplo
Mudança de Status	O status da entidade muda	Produto: Fora de Estoque → Em Estoque
Entidade Criada	Novo item adicionado	Novo pedido, novo registro de usuário
Entidade Atualizada	Item modificado	Perfil atualizado, status do pedido alterado
Gatilho Personalizado	Gatilho manual a partir do código	Newsletter enviada, promoção iniciada

Canais de Notificação

Três maneiras de notificar usuários:

Canal	Descrição	Melhor Para
E-mail	Enviar mensagens por e-mail	Confirmações de pedidos, recibos, newsletters
Notificação Push	Alertas para mobile/navegador	Atualizações em tempo real, alertas urgentes
Socket.IO	Mensagens websocket em tempo real	Atualizações ao vivo, chat, sincronização instantânea

Fluxo de Evento

1. Algo acontece (Gatilho)
   ↓
2. O evento detecta o gatilho
   ↓
3. O evento verifica condições (se houver)
   ↓
4. O evento envia notificações
   ↓
5. Os usuários recebem a mensagem

📋 O que você precisa saber

Gatilhos de Evento Comuns

Eventos típicos que você pode configurar:

E-commerce:

• Pedido realizado
• Pedido enviado
• Pedido entregue
• Pagamento recebido
• Produto de volta em estoque
• Alerta de queda de preço

Gerenciamento de Usuários:

• Usuário registrado
• E-mail verificado
• Senha alterada
• Perfil atualizado
• Conta excluída

Conteúdo:

• Novo artigo publicado
• Comentário adicionado
• Conteúdo aprovado
• Assinatura renovada

Variáveis de Modelo

Use marcadores em modelos de notificação

---

📊 Tabela de Referência Rápida - Métodos Comuns

Método	O que Faz
getAllSubscriptions()	Obter todas as assinaturas
subscribeByMarker()	Inscrever-se em evento específico por marcador
unsubscribeByMarker()	Cancelar inscrição de evento específico por marcador

Nota: Os eventos são configurados no painel de administração do OneEntry. O SDK é somente leitura - use-o para buscar informações sobre eventos, não para criar eventos.

---

❓ Perguntas Comuns (FAQ)

Como eu crio ou edito eventos?

Os eventos são gerenciados no painel de administração do OneEntry:

1. Faça login no OneEntry admin
2. Vá para a seção de Eventos
3. Crie ou edite eventos
4. Configure gatilhos, canais e modelos
5. Ative o evento

O SDK é somente leitura - use-o para buscar informações sobre eventos, não para criar eventos.

---

Qual é a diferença entre Notificação Push e Socket.IO?

Notificação Push - Enviada para o dispositivo (funciona mesmo quando o aplicativo está fechado)

• Aparece no centro de notificações

• O usuário pode tocar para abrir o aplicativo

• Melhor para: Alertas importantes, lembretes

• Socket.IO - Mensagem websocket em tempo real (apenas quando o aplicativo está aberto)

  • Entrega instantânea para clientes conectados
  • Atualizações ao vivo sem atualização
  • Melhor para: Dados ao vivo, chat, colaboração

---

Posso acionar manualmente um evento a partir do meu código?

O SDK não suporta gatilhos manuais. Os eventos são acionados automaticamente com base nos gatilhos configurados no OneEntry.

---

Posso personalizar modelos de e-mail?

Sim! No painel de administração do OneEntry:

• Modelos de e-mail em HTML
• Estilização personalizada
• Suporte a múltiplos idiomas
• Teste antes de ativar

---

O que acontece se um evento falhar ao enviar?

O OneEntry lida com tentativas e registro:

• E-mails falhados são enfileirados para nova tentativa
• Notificações push falhadas são registradas
• Verifique os logs de eventos no painel de administração
• Configure opções de fallback

---

Posso usar conteúdo rico nas notificações?

• E-mail - Suporte total a HTML (imagens, links, estilização)
• Notificação Push - Título + texto do corpo + imagem opcional
• Socket.IO - Qualquer estrutura de dados JSON

---

Qual é a diferença entre Evento e envio de Formulário?

• Eventos - Notificações automatizadas acionadas pelo sistema
• Formulários - Dados enviados pelo usuário que você coleta

Exemplo:

• Evento: "Usuário registrado" → Enviar automaticamente e-mail de boas-vindas
• Formulário: Usuário preenche o formulário de contato → Você recebe a submissão

---

💡 Notas Importantes

📬 Canais de Notificação

Na Plataforma OneEntry, existem três maneiras de interagir com os usuários do seu sistema através do módulo "Events":

• 📧 E-mail - Enviar mensagens por e-mail com conteúdo HTML rico
• 📱 Notificação Push - Enviar alertas em tempo real para mobile/navegador
• 🔌 Socket.IO - Enviar mensagens websocket instantâneas para clientes conectados

---

Eventos são Somente Leitura no SDK

Lembre-se: O SDK é para ler eventos, não para criá-los.

---

Convenção de Nomenclatura de Eventos

Use marcadores claros e descritivos:

✅ Bons marcadores:
- order_confirmed
- product_back_in_stock
- user_registered
- payment_failed
- password_reset_requested

❌ Maus marcadores:
- event1
- notification
- email_event
- test

---

🎓 Melhores Práticas

• Use marcadores de eventos descritivos
• Teste eventos antes de ativar
• Forneça valores de fallback para variáveis
• Monitore os logs de eventos regularmente
• Desative eventos não utilizados
• Use canais apropriados (e-mail para recibos, push para urgência)
• Localize mensagens de eventos
• Lide com eventos ausentes/desativados de forma elegante

---

Mais informações sobre a interface do usuário do módulo https://doc.oneentry.cloud/docs/events/introduction

---

Definição do módulo Events

const { Events } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

---

🔗 Documentação Relacionada

• Módulo de Usuários - Gerenciar usuários que recebem notificações
• Módulo de Formulários - Coletar dados de formulários vs eventos acionados automaticamente
• Módulo de Administradores - Gerenciar quem configura eventos

---