Introdução

Bem-vindo à infraestrutura definitiva de sincronização. O BeeZync é um motor duplo que inclui dois serviços de nível corporativo perfeitamente integrados ao seu plano:

Serviço 1

WEBSOCKETS

Mensagens bidirecionais ao vivo para navegadores e aplicativos. Latência em milissegundos para painéis, chats e ferramentas colaborativas enquanto o usuário mantém o aplicativo aberto.

Serviço 2

PUSH NOTIFICATIONS

Reconecte-se com seus usuários mesmo quando o aplicativo estiver fechado ou em segundo plano. Alertas nativos diretos para o sistema operacional (iOS, Android, macOS).

Conceitos-Chave e Sinergia Mágica

A vantagem injusta do BeeZync em relação aos serviços tradicionais está na combinação inteligente dos nossos motores. Você não está comprando dois serviços isolados; você está acessando um orquestrador de mensagens de última geração.

1
Projeto Híbrido (Dual Engine) Todo aplicativo que você cria engloba nativamente o motor WebSockets e o ecossistema de Push Notifications. Não é necessário configurar arquiteturas separadas.
2
Roteamento Inteligente (Smart Delivery) Killer Feature
Este é o verdadeiro superpoder do BeeZync para levar seu aplicativo ao próximo nível. Quando você envia uma notificação, nosso motor inteligente toma uma decisão em milissegundos:

Se o usuário estiver com o aplicativo aberto (Ativo): O BeeZync intercepta o envio e o entrega diretamente via WebSocket. Isso garante entrega instantânea (zero latência), economiza bateria, evita os limites/atrasos dos provedores (Apple/Google) e permite animações muito fluidas (in-app alerts) dentro do seu aplicativo.

Se o usuário estiver com o aplicativo fechado (Inativo): O motor delega silenciosamente a carga útil para o Firebase (FCM) ou Apple (APNs). O sistema operacional do telefone encarrega-se de ativar a tela e mostrar o alerta nativo Push. Tudo isso automaticamente, sem você precisar escrever lógicas condicionais!
3
Despacho Assíncrono Unificado Seja enviando um Push massivo para um milhão de usuários ou um único evento WebSocket, enfileiramos a solicitação e a distribuímos globalmente sem sobrecarregar os recursos do seu servidor backend.

Quick Start

Uma visão rápida de como interagir com os dois motores principais da plataforma em menos de um minuto.

// 1. Conexão do cliente com o motor WEBSOCKET
const wsUrl = `wss://api.beezync.com/v1/ws?app_id=SEU_APP_ID&api_key=SUA_APP_KEY`;
const socket = new WebSocket(wsUrl);

socket.onopen = () => {
    // Inscrever-se num canal
    socket.send(JSON.stringify({ action: "subscribe", channel: "geral" }));
};

socket.onmessage = (event) => {
    console.log('Evento de Socket Recebido!', JSON.parse(event.data));
};

// 2. Despachar mensagem WEBSOCKET do Laravel
Http::withHeaders([
    'Authorization' => 'Bearer SUA_APP_KEY',
])->post('https://api.beezync.com/v1/api/send-ws', [
    'app_id'  => 'SEU_APP_ID',
    'channel' => 'geral',
    'payload' => [
        'message' => 'Olá mundo em tempo real!'
    ]
]);

curl -X POST https://api.beezync.com/v1/api/send-ws \
  -H "Authorization: Bearer SUA_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "SEU_APP_ID",
    "channel": "geral",
    "payload": { "message": "Olá do terminal" }
  }'

// Despachar notificação PUSH massiva do Laravel
Http::withHeaders([
    'Authorization' => 'Bearer SUA_APP_KEY',
])->post('https://api.beezync.com/v1/api/send-push', [
    'app_id'      => 'SEU_APP_ID',
    'target_type' => 'all',
    'title'       => 'Grande Promoção!',
    'body'        => 'Descubra as novas funcionalidades do app.'
]);

curl -X POST https://api.beezync.com/v1/api/send-push \
  -H "Authorization: Bearer SUA_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "SEU_APP_ID",
    "target_type": "all",
    "title": "Grande Promoção!",
    "body": "Descubra as novas funcionalidades do app."
  }'

Autenticação Global

Todas as solicitações para a API REST BeeZync (para envio de mensagens WebSocket ou Push) requerem autenticação segura. Você deve enviar a sua App Key no cabeçalho HTTP Authorization usando o esquema Bearer.

Segurança: Mantenha a sua App Key em segredo (ex: no seu arquivo .env). Nunca exponha a sua App Key no código do frontend dos clientes. O frontend a utiliza apenas temporariamente para iniciar a conexão segura com o WebSocket, e não para solicitações REST.

Despacho WebSocket WEBSOCKET

Este serviço transmite mensagens em tempo real para navegadores/aplicativos que têm uma conexão ativa com o socket do BeeZync. Endpoint: POST /v1/api/send-ws

Corpo da Solicitação (JSON)

Parâmetro	Tipo	Descrição
app_id	string (required)	O UUID do seu aplicativo.
channel	string (required)	O nome do canal WebSocket para o qual despachar (ex: `chat.sala.12`).
payload	object (required)	Objeto JSON com os dados que você deseja transmitir aos clientes conectados.

Push Notifications PUSH NOTIFICATION

Use este serviço para despertar o dispositivo do usuário mesmo que o aplicativo esteja fechado. Nativamente interconectado com APNs e FCM. Endpoint: POST /v1/api/send-push

{
  "app_id": "SEU_APP_ID",
  "target_type": "all", // "all", "device", "user" ou "segmented"
  "title": "Nova atualização",
  "body": "Descubra as novas funções do app.",
  "data": {
    // Carga útil silenciosa para o app processar em segundo plano
    "screen": "home",
    "id": 123
  }
}

Filtros e Segmentação PUSH NOTIFICATION

Para campanhas massivas ou notificações transacionais em grupo, o motor BeeZync permite alcançar seu público usando o compilador dinâmico com target_type: "segmented".

1. Atributos do Dispositivo (Nativos)

Propriedades que identificam a assinatura do dispositivo e controlam a entrega. Registradas automaticamente.

Atributo	Descrição
platform	Sistema operacional do cliente (`ios`, `android`, `web`).
device_id	Identificador de hardware exclusivo (UUID gerado pelo cliente).
external_user_id	O ID interno do seu próprio banco de dados, útil para vincular vários dispositivos (telefone e tablet) a um único usuário real.

2. Metadados Personalizados (Tags)

Pares chave-valor personalizáveis que você envia no objeto metadata ao registrar o dispositivo. São essenciais para agrupar públicos.

Campo (field)	Relação (relation)	Exemplo de Filtro JSON
platform	`=, !=`	`{"field": "platform", "relation": "=", "value": "ios"}`
tag	`=, !=, >, <`	`{"field": "tag", "key": "level", "relation": ">", "value": "10"}`
tag	`contains, array_contains`	`{"field": "tag", "key": "preferences", "relation": "array_contains", "value": "sports"}`

Casos de Uso de Segmentação

Notícias Esportivas (Array Contains)

Enviar alerta apenas para usuários inscritos no canal de esportes.

{"field": "tag", "key": "topics", "relation": "array_contains", "value": "sports"}

Promoção Regional (Igualdade)

Oferta exclusiva para clientes em um país específico.

{"field": "tag", "key": "country", "relation": "=", "value": "BR"}

Gamificação (Maior que)

Notificar jogadores nível 50+ sobre um torneio.

{"field": "tag", "key": "level", "relation": ">", "value": "50"}

Segmentação de Plataforma

Lembrar apenas usuários de iOS de atualizar o aplicativo.

{"field": "platform", "relation": "=", "value": "ios"}

Conexão Web / JS WEBSOCKET

A integração do frontend para WebSockets é extremamente leve. Você só precisa usar a API nativa WebSocket dos navegadores, sem bibliotecas pesadas.

// Manter a conexão ativa na sessão do usuário
const socket = new WebSocket('wss://api.beezync.com/v1/ws?app_id=XYZ&api_key=XYZ');

socket.onmessage = (e) => {
    const payload = JSON.parse(e.data);
    if (payload.channel === 'meu_canal') {
        // Atualizar interface, gráficos ou contadores
        updateDashboard(payload.data);
    }
};

Registro Móvel (iOS/Android) PUSH NOTIFICATION

O motor de Push precisa saber quem é o seu usuário. Para receber notificações Push, o aplicativo móvel deve capturar e enviar o seu Token físico (Google FCM ou Apple APNs) para o BeeZync. Endpoint: POST /v1/api/register-device

Atualizações de Telemetria: Se as preferências de um usuário mudarem (ex: comprar um plano premium ou alterar o idioma), simplesmente envie esse JSON novamente. O BeeZync realizará um `upsert` automático atualizando os metadata do dispositivo sem duplicá-lo com base no seu device_id.

{
  "token": "c3a_XYZ_...", // Token gerado pelo OS (Firebase/APNs)
  "platform": "android", // "ios", "android", ou "web"
  "device_id": "uuid-unico-do-telefone",
  "external_user_id": "user_555", // (Opcional) Vincular a um ID do seu backend
  "metadata": {
    // Tags personalizadas para usar com target_type: "segmented"
    "language": "pt",
    "plan": "pro",
    "topics": ["sports", "news"],
    "level": 12
  }
}

Ciclo de Vida e Telemetria GLOBAL

Compreender o ciclo de vida dos dispositivos é vital para manter um banco de dados limpo e uma segmentação precisa.

WebSockets (Conexões Efêmeras)

As conexões WebSocket são em tempo real e não persistem. Quando um usuário fecha a guia ou o aplicativo, o socket é destruído. Para saber quem está "online", seu backend deve registrar os eventos onopen e onclose ou usar a futura API de Presença.

Push Notifications (Assinaturas Persistentes)

Os tokens Push (FCM/APNs) são persistentes. Se um usuário desinstalar o aplicativo, o BeeZync não saberá imediatamente. Quando você envia um Push e o provedor (ex: Google) responde que o token é inválido, o BeeZync marcará automaticamente o dispositivo como Unsubscribed (inativo) limpando o seu banco de dados.