Eventos en tiempo real para tu app

1. Primeros pasos

1. Inicia sesión en devquake.com y abre Pulse desde tu cuenta (pruébalo gratis 24 horas o suscríbete).
2. Crea un servicio API. Copia la clave secreta enseguida: solo se muestra una vez.
3. En Tus sitios web, añade tu sitio y su registro DNS (o activa Permitir localhost para probar en tu ordenador).
4. Abre la Prueba en directo y envía tu primer evento.

2. Para qué se usa

Para todo aquello en lo que una página debe cambiar en cuanto pasa algo en otro lugar, sin recargar:

• Notificaciones: “Tu pedido ha sido enviado”, “Nuevo mensaje”, un contador que sube.
• Paneles en directo: ventas, registros, lecturas de sensores o el estado de los servidores en el momento.
• Chat y comentarios: mensajes que aparecen para todos en la sala.
• Puntuaciones y juegos: resultados en directo, turnos, un marcador en una tele y en los móviles a la vez.
• Colaboración: una lista o un tablero compartido donde todos ven los cambios de los demás.
• Estado de una tarea: “procesando… listo” para subidas, pagos o exportaciones.
• Presencia: quién está conectado o escribiendo ahora mismo.

3. El formato de los eventos

Cada evento tiene el mismo marco fijo y, dentro, tus propios datos como claves y valores:

• channel: adónde va, p. ej. orders o room-42. Quien escucha elige los canales que quiere.
• event: qué ha pasado, p. ej. order.created.
• data: tus claves y valores, p. ej. orderId: "A-17", total: 42.5, paid: true. Los valores son texto, números, sí/no (true/false) o vacíos (null).
• Pulse añade id, app (tu clave pública), source (servidor, página web, token de cliente o prueba en directo), sender (de un token de cliente) y at (la hora, en UTC).

Los canales cuyo nombre empieza por private- solo se pueden usar con un token de cliente o con la clave secreta, nunca solo con la clave pública.

4. Claves y seguridad

• Clave pública (pk_…): va en tus páginas web. Solo funciona desde tus sitios web verificados, solo puede escuchar canales públicos y, si lo permites, enviar a ellos.
• Clave secreta (sk_…): se queda en tu servidor. Puede enviar a cualquier canal y crear tokens de cliente. Pulse la rechaza cuando llega desde una página web, porque un secreto en un navegador ya no es secreto.
• Tokens de cliente: tu servidor crea uno para cada uno de tus usuarios, válido hasta una hora, con los canales que ese usuario puede usar y si puede enviar. Es la forma segura para canales privados y para usuarios con sesión iniciada.
• Solo tú: un servicio API pertenece únicamente a tu cuenta de DevQuake. No se puede compartir con otros miembros.
• Direcciones de servidor: si quieres, permite la clave secreta solo desde las direcciones IP de tus servidores.
• Vigilancia de filtraciones: Pulse cuenta las direcciones desde las que se usa tu clave secreta y registra las llamadas rechazadas. Si la clave aparece en demasiados sitios, te avisa: crea una nueva (la antigua sigue funcionando 24 horas).

Por qué una clave copiada no le sirve a nadie: la clave pública solo funciona en sitios web que han demostrado con DNS que son tuyos; la clave secreta se rechaza en las páginas web y puede vincularse a tus servidores; y cada servicio tiene límites, así que ni siquiera una clave robada puede hacer más de lo que permite tu plan.

5. Verificar tu sitio web

1. En Tus sitios web, introduce la dirección, p. ej. https://shop.example.com.
2. Pulse muestra un registro TXT: un nombre como _devquake-pulse.shop.example.com y un valor como devquake-pulse=….
3. Añádelo donde gestionas el DNS de tu dominio (tu hosting o tu proveedor de dominio).
4. Pulsa Comprobar ahora. Tras unos minutos (a veces una hora) el sitio web aparece como Verificado y funciona.

Para probar en tu propio ordenador, activa Permitir localhost: las páginas en http://localhost funcionan sin registro DNS. Desactívalo cuando pases a producción.

6. Tu propia estructura de datos

En Tu estructura de datos describes cada evento que usas: sus claves, su tipo (texto, número o sí/no) y cuáles son obligatorias. Por ejemplo order.created con orderId (texto, obligatoria), total (número) y paid (sí/no).

• Los eventos descritos se comprueban: si falta una clave obligatoria o un tipo es incorrecto, se rechaza con un error claro.
• Los eventos que no has descrito se siguen aceptando, salvo que actives Solo eventos descritos.
• Con Solo eventos descritos activado, también se rechazan los eventos y las claves desconocidos: recomendado en producción.

Las claves empiezan por una letra o _ y contienen letras, dígitos y _. Como máximo 20 claves por evento; valores de texto de hasta 500 caracteres.

7. Escenario de prueba en directo (5 minutos)

Necesitas: tu servicio API, un ordenador con terminal y un móvil (o una segunda ventana del navegador). Todavía no necesitas un sitio web.

1. Abre tu servicio API y pulsa Prueba en directo. Deja el canal demo y pulsa Conectar: el punto se pone verde, En directo.
2. Abre la misma página en tu móvil (con la sesión de DevQuake iniciada) y pulsa Conectar también allí.
3. En el ordenador, en Enviar, deja el evento hello con la clave text = Hello y pulsa Enviar evento. El móvil lo muestra en menos de un segundo, con lo que ha tardado.
4. Envía desde el móvil: el ordenador lo recibe. Ambos escuchan demo.
5. En un terminal, ejecuta el ejemplo curl de la página con tu clave secreta en lugar de $PULSE_SECRET_KEY. Ambas páginas reciben un evento de un servidor.
6. Prueba las reglas: añade un evento descrito en Tu estructura de datos, activa Solo eventos descritos y envía uno con un tipo incorrecto: se rechaza indicando el motivo.
7. Prueba los canales privados: desconecta, activa Usar un token de cliente, pon los canales en private-demo, conecta en ambos dispositivos y vuelve a enviar.

Durante la prueba gratuita los eventos llegan con 3 segundos de retraso y las conexiones son más cortas: es a propósito. Si una página muestra “Conectado (polling)”, las conexiones en directo están bloqueadas en esa red; los eventos siguen llegando, cada pocos segundos.

8. La API en resumen

• POST /api/v1/events: envía un evento. Cuerpo: { "channel", "event", "data" }. Autenticación: Authorization: Bearer sk_… (servidor), Authorization: Bearer <client token> o X-Pulse-Key: pk_… (página web en un sitio verificado). Responde 202 { id, at }.
• GET /api/v1/stream?key=pk_…&channels=a,b: eventos en directo (Server-Sent Events). Usa token= en lugar de key= para un token de cliente. Los clientes que se reconectan se ponen al día desde su último evento (Last-Event-ID).
• GET /api/v1/poll?key=…&channels=…&after=<id>: los mismos eventos preguntando cada pocos segundos, para lugares donde las conexiones en directo no funcionan. Responde { events, next, retryAfterMs }.
• GET /api/v1/client: una pequeña biblioteca para navegador que se conecta, se reconecta, renueva los tokens y pasa a polling por sí sola.
• Los errores llegan como { "error": { "code", "message" } } con el estado HTTP (401 clave, 403 no permitido, 402 sin suscripción, 429 demasiadas, con Retry-After).

9. Prueba, suscripción y acceso completo

Pulse funciona junto a todas las demás apps de DevQuake, así que cada cuenta tiene límites justos. Tu plan actual y sus cifras se muestran en la página de inicio de la app.

• Prueba gratuita (24 horas): 1 servicio API, 3 conexiones en directo, 300 eventos al día, eventos pequeños, y los eventos llegan con 3 segundos de retraso.
• Suscrito: 3 servicios API, 25 conexiones en directo y 10.000 eventos al día cada uno, eventos al instante.
• Acceso completo: límites mucho más altos para uso en producción. Contáctanos y cuéntanos qué estás creando.

Cuando termina tu suscripción, tus servicios API dejan de responder (tus apps reciben “subscription required”). Cuando cancelas la suscripción o eliminas tu cuenta, se eliminan con todos sus datos.

10. Tus datos

Los eventos se guardan solo el tiempo necesario para que los clientes que se reconectan se pongan al día (como máximo un día, una semana con acceso completo), las cifras de uso 35 días y el registro de seguridad 30 días. Las claves secretas nunca se guardan, y las direcciones solo como hashes anónimos. Eliminar un servicio API, cancelar la suscripción o eliminar tu cuenta de DevQuake lo borra todo.

11. Pruébalo en directo

¿Quieres ver Pulse funcionando antes de escribir código? La demo Pruébalo en directo (en la página de inicio de la app) envía eventos entre dos de tus navegadores a través de la API real.

1. Abre Pruébalo en directo y pulsa Copiar el enlace.
2. Abre el enlace en un segundo navegador (otro navegador, una ventana privada o tu móvil) e inicia sesión con la misma cuenta de DevQuake.
3. Elige Un mensaje y escribe algo, o Tu propio JSON y pega un objeto plano como { "order": 42, "paid": true }.
4. Pulsa Enviar a mi otro navegador. El otro navegador muestra lo que ha llegado y cuánto ha tardado: del remitente al servidor, del servidor al navegador y de extremo a extremo, con la media, el más rápido y el más lento.

El marco del evento (canal, nombre del evento y las marcas demo_from y demo_sent_at) es fijo; tu contenido va en data. La demo usa un canal privado tuyo, es gratuita en todos los planes, no cuenta para tus límites, permite 30 eventos por minuto y borra los eventos de demo al cabo de una hora.

Ejemplos de código

Sustituye la clave de ejemplo por tu propia clave pública (tu servicio API muestra estos ejemplos con tu clave ya puesta).

<script src="https://pulse.devquake.com/api/v1/client"></script>
<script>
  var pulse = DevQuakePulse.connect({
    key: 'pk_YourPublicKeyFromTheApp00',
    channels: ['demo'],
    onEvent: function (e) { console.log(e.event, e.data); },
    onStatus: function (s) { console.log('pulse:', s); }
  });
  // Only when "Browsers may send events" is on:
  // pulse.send('demo', 'hello', { text: 'Hi' });
</script>

curl -X POST https://pulse.devquake.com/api/v1/events \
  -H "Authorization: Bearer $PULSE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"demo","event":"hello","data":{"text":"Hi","count":1}}'

// Your server (Node.js): a client token for one of your users, valid for one hour.
import { createHmac } from 'node:crypto';

const b64 = (o) => Buffer.from(JSON.stringify(o)).toString('base64url');

export function pulseToken(userId, channels, canSend) {
  const now = Math.floor(Date.now() / 1000);
  const head = b64({ alg: 'HS256', typ: 'JWT' }) + '.' + b64({
    app: 'pk_YourPublicKeyFromTheApp00', ch: channels, pub: canSend,
    sub: String(userId), iat: now, exp: now + 3600,
  });
  const sig = createHmac('sha256', process.env.PULSE_SECRET_KEY).update(head).digest('base64url');
  return head + '.' + sig;
}

// In the page: DevQuakePulse.connect({ token: () => fetch("/my/pulse-token").then((r) => r.text()), … })

{
  "id": "812",
  "app": "pk_YourPublicKeyFromTheApp00",
  "channel": "orders",
  "event": "order.created",
  "data": {
    "orderId": "A-17",
    "total": 42.5,
    "paid": true
  },
  "source": "server",
  "at": "2026-09-26T10:00:00.000Z"
}