Introducción

Bienvenido a la infraestructura de sincronización definitiva. BeeZync es un motor dual que incluye dos servicios de grado empresarial perfectamente integrados en tu plan:

Servicio 1

WEBSOCKETS

Mensajería bidireccional en vivo para navegadores y apps. Latencia en milisegundos para dashboards, chats y herramientas colaborativas mientras el usuario tiene la app abierta.

Servicio 2

PUSH NOTIFICATIONS

Reconecta con tus usuarios incluso cuando la app está cerrada o en segundo plano. Alertas nativas directas al sistema operativo (iOS, Android, macOS).

Conceptos Clave & Sinergia Mágica

La ventaja injusta de BeeZync frente a servicios tradicionales radica en la combinación inteligente de nuestros motores. No estás comprando dos servicios aislados; estás accediendo a un orquestador de mensajería de siguiente generación.

  • 1
    Proyecto Híbrido (Dual Engine) Cada aplicación que creas engloba de forma nativa tanto el motor de WebSockets como el ecosistema de Push Notifications. No necesitas configurar arquitecturas separadas.
  • 2
    Enrutamiento Inteligente (Smart Delivery)

    Este es el verdadero superpoder de BeeZync para llevar tu app al siguiente nivel. Cuando despachas una notificación, nuestro motor inteligente toma una decisión en milisegundos:

    Si el usuario tiene la app abierta (Activo): BeeZync intercepta el envío y lo entrega directamente a través del WebSocket. Esto garantiza una entrega instantánea (latencia cero), ahorra batería, evita los límites/retrasos de los proveedores (Apple/Google) y permite animaciones súper fluidas (in-app alerts) dentro de tu aplicación.
    Si el usuario tiene la app cerrada (Inactivo): El motor delega silenciosamente la carga útil hacia Firebase (FCM) o Apple (APNs). El sistema operativo del teléfono se encarga de despertar la pantalla y mostrar la alerta nativa Push. ¡Todo esto en automático sin que tú escribas lógica condicional!
  • 3
    Despacho Asíncrono Unificado Ya sea que envíes un Push masivo a un millón de usuarios o un evento WebSocket, nosotros encolamos la petición y la distribuimos globalmente sin estrangular los recursos de tu servidor backend.

Quick Start

Un vistazo rápido a cómo interactuar con los dos motores principales de la plataforma en menos de un minuto.

// 1. Conexión del cliente al motor WEBSOCKET
const wsUrl = `wss://api.beezync.com/v1/ws?app_id=TU_APP_ID&api_key=TU_APP_KEY`;
const socket = new WebSocket(wsUrl);

socket.onopen = () => {
    // Suscribirse a un canal
    socket.send(JSON.stringify({ action: "subscribe", channel: "general" }));
};

socket.onmessage = (event) => {
    console.log('¡Evento de Socket Recibido!', JSON.parse(event.data));
};
// 2. Despachar mensaje WEBSOCKET desde Laravel
Http::withHeaders([
    'Authorization' => 'Bearer TU_APP_KEY',
])->post('https://api.beezync.com/v1/api/send-ws', [
    'app_id'  => 'TU_APP_ID',
    'channel' => 'general',
    'payload' => [
        'message' => 'Hola mundo en tiempo real!'
    ]
]);
curl -X POST https://api.beezync.com/v1/api/send-ws \
  -H "Authorization: Bearer TU_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "TU_APP_ID",
    "channel": "general",
    "payload": { "message": "Hola desde la terminal" }
  }'
// Despachar una notificación PUSH masiva desde Laravel
Http::withHeaders([
    'Authorization' => 'Bearer TU_APP_KEY',
])->post('https://api.beezync.com/v1/api/send-push', [
    'app_id'      => 'TU_APP_ID',
    'target_type' => 'all',
    'title'       => '¡Gran Venta!',
    'body'        => 'Descubre nuestras nuevas promociones.'
]);
curl -X POST https://api.beezync.com/v1/api/send-push \
  -H "Authorization: Bearer TU_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "TU_APP_ID",
    "target_type": "all",
    "title": "¡Gran Venta!",
    "body": "Descubre nuestras nuevas promociones."
  }'

Sección 2

API REST (Backend)

Autenticación Global

Todas las peticiones a la API REST de BeeZync (para envío de mensajes WebSockets o Pushes) requieren autenticación segura. Debes enviar tu App Key en la cabecera HTTP Authorization utilizando el esquema Bearer.

Seguridad: Mantén tu App Key en secreto (ej. en tu archivo .env). Nunca expongas tu App Key en el código frontend de los clientes. El frontend solo la usa temporalmente para inicializar la conexión WebSocket segura, no para enviar peticiones REST.

Despacho WebSockets WEBSOCKET

Este servicio emite mensajes en tiempo real a los navegadores/apps que tengan una conexión viva al socket de BeeZync. Endpoint: POST /v1/api/send-ws

Cuerpo de la Petición (JSON)

Parámetro Tipo Descripción
app_id string (required) El UUID de tu aplicación.
channel string (required) El nombre del canal WebSocket al que despachar (ej. chat.room.12).
payload object (required) Objeto JSON con los datos que deseas transmitir a los clientes conectados.

Push Notifications PUSH NOTIFICATION

Utiliza este servicio para despertar el dispositivo del usuario incluso si la app está cerrada. Interconectado nativamente con APNs y FCM. Endpoint: POST /v1/api/send-push 

{
  "app_id": "TU_APP_ID",
  "target_type": "all", // "all", "device", "user" o "segmented"
  "title": "Nueva actualización",
  "body": "Descubre las nuevas funcionalidades de la app.",
  "data": {
    // Carga útil silenciosa para que la app móvil procese de fondo
    "screen": "home",
    "id": 123
  }
}

Filtros y Segmentación PUSH NOTIFICATION

Para campañas masivas o notificaciones transaccionales grupales, el motor de BeeZync permite alcanzar a tu audiencia utilizando el compilador dinámico con target_type: "segmented".

1. Atributos del Dispositivo (Nativos)

Propiedades que identifican la suscripción del dispositivo y controlan la entrega. Se registran automáticamente.

Atributo Descripción
platform Sistema operativo del cliente (ios, android, web).
device_id Identificador único del hardware (UUID generado por el cliente).
external_user_id El ID interno de tu propia base de datos, útil para vincular múltiples dispositivos (teléfono y tablet) a un mismo usuario real.

2. Metadata Personalizada (Tags)

Pares clave-valor customizables que envías dentro del objeto metadata al momento de registrar el dispositivo. Son fundamentales para agrupar audiencias.

Campo (field) Relación (relation) Ejemplo 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 Segmentación

Noticias Deportivas (Array Contains)

Enviar alerta solo a usuarios suscritos al canal de deportes.

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

Promoción Regional (Igualdad)

Oferta exclusiva para clientes de un país específico.

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

Gamificación (Mayor a)

Notificar un torneo a jugadores nivel 50+.

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

Segmentación de Plataforma

Recordar actualizar la app solo a usuarios iOS.

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

Sección 3

Integración Cliente (SDK)

Conexión Web / JS WEBSOCKET

La integración frontend para WebSockets es extremadamente ligera. Solo necesitas usar la API nativa WebSocket de los navegadores, sin librerías pesadas. 

// Mantén la conexión activa en la sesión del usuario
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 === 'mi_canal') {
        // Actualizar UI, gráficos o contadores en vivo
        updateDashboard(payload.data);
    }
};

Registro Móvil (iOS/Android) PUSH NOTIFICATION

El motor de Push necesita saber quién es tu usuario. Para recibir notificaciones Push, la app móvil debe capturar y enviar su Token físico (FCM de Google o APNs de Apple) a BeeZync. Endpoint: POST /v1/api/register-device

Actualizaciones de Telemetría: Si las preferencias de un usuario cambian (ej. compra un plan premium o cambia el idioma), simplemente envía de nuevo este JSON. BeeZync hará un `upsert` automático actualizando la metadata del dispositivo sin duplicarlo basándose en su device_id. 
{
  "token": "c3a_XYZ_...", // Token generado por el OS (Firebase/APNs)
  "platform": "android", // "ios", "android", o "web"
  "device_id": "uuid-unico-del-telefono",
  "external_user_id": "user_555", // (Opcional) Vincular a un ID de tu backend
  "metadata": {
    // Tags personalizados para usar con target_type: "segmented"
    "language": "es",
    "plan": "pro",
    "topics": ["sports", "news"],
    "level": 12
  }
}

Ciclo de Vida y Telemetría GLOBAL

Comprender el ciclo de vida de los dispositivos es vital para mantener una base de datos limpia y una segmentación precisa.

WebSockets (Conexiones Efímeras)

Las conexiones de WebSocket son en tiempo real y no persisten. Cuando un usuario cierra la pestaña o la app, el socket se destruye. Para saber quién está "en línea", tu backend debe registrar eventos de onopen y onclose o usar la futura API de Presencia.

Push Notifications (Suscripciones Persistentes)

Los tokens de Push (FCM/APNs) son persistentes. Si un usuario desinstala la app, BeeZync no lo sabrá de inmediato. Cuando envíes un Push y el proveedor (ej. Google) responda que el token es inválido, BeeZync marcará automáticamente el dispositivo como Unsubscribed (inactivo) limpiando tu base de datos.

Preguntas Frecuentes