TTL y urgencia en web push: que el aviso llegue a tiempo o no llegue

El TTL decide durante cuánto tiempo puede llegar todavía una notificación a un dispositivo que estaba apagado o sin conexión, y la urgencia decide si un dispositivo que intenta ahorrar batería la entrega ya o la deja para más tarde. Elegirlos es una decisión de producto: el TTL debe durar lo que el aviso sigue siendo cierto, y la urgencia debe ser alta solo cuando un retraso le cuesta algo a quien lo recibe.

En resumen:

• Un aviso caducado es peor que ninguno: un recordatorio que llega después de la cita confunde y resta confianza.
• TTL = segundos durante los que el aviso sigue siendo útil. Si el dispositivo no se conecta antes, no se entrega.
• Urgencia baja = menos gasto de batería a cambio de posibles retrasos; alta = entrega inmediata incluso con poca batería.
• En castly, ttl vale 86400 (24 horas) por defecto y como máximo 2419200 (28 días); urgency admite very-low, low, normal (por defecto) y high.
• En los avisos con hora fija, calcula el TTL en el momento de enviar.

Qué significa el TTL para quien recibe el aviso

Si el dispositivo está conectado cuando envías, la notificación llega en segundos y el TTL no interviene. Si está apagado o sin cobertura, el servicio push de su navegador guarda el mensaje y lo entrega cuando vuelve, pero solo durante los segundos que marca el TTL; pasado ese plazo, lo descarta.

Visto desde la persona que recibe el aviso, el TTL responde a una pregunta sencilla: ¿prefiero que esto me llegue tarde o que no me llegue? Un ejemplo: el viernes a las 18:30 envías «Tu clase empieza a las 19:00» con un TTL de 24 horas. El portátil de la alumna está cerrado hasta el sábado a las 10:00, y al abrirlo aparece el recordatorio de algo que ya pasó. Con un TTL de 1800 segundos, el aviso se habría descartado a las 19:00 y nadie habría visto una alerta falsa.

Un aviso tardío nunca es neutro. Un código caducado hace que la persona lo pruebe y falle, una oferta terminada parece un engaño y una alerta ya resuelta provoca una alarma inútil. Cada uno de esos momentos enseña que tus notificaciones no son fiables, y el siguiente paso suele ser bloquearlas. El caso extremo es ttl: 0, que significa «ahora o nunca»: se entrega si el dispositivo está disponible en ese instante y, si no, se descarta.

Qué significa la urgencia: batería frente a rapidez

La urgencia es una pista para el dispositivo sobre cuánta prisa hay. Un teléfono con poca batería o un portátil en modo de ahorro pueden retener los mensajes poco urgentes hasta un momento mejor. El estándar Web Push define cuatro niveles, y cada plataforma decide cómo aplicarlos:

• very-low: puede esperar a que el dispositivo esté cargando y con wifi. Para promociones y contenido sin prisa.
• low: puede esperar a que esté cargando o con wifi. Para novedades y resúmenes.
• normal: entrega habitual, sin esperar condiciones especiales. Para la mayoría de avisos personales.
• high: se entrega incluso con poca batería. Para lo que no puede esperar.

La urgencia no cambia el TTL ni consigue que un dispositivo apagado reciba antes el mensaje: solo influye en dispositivos conectados que intentan ahorrar energía. Por eso marcar todo como high no adelanta nada a quien está desconectado y, en cambio, gasta la batería de tus usuarios en avisos que podían esperar. Y una urgencia baja combinada con un TTL corto puede hacer que el aviso no llegue nunca: si eliges very-low, dale margen.

Qué TTL y urgencia usar en cada caso

La pregunta para el TTL es: ¿a partir de qué momento este aviso es falso, inútil o molesto? Para la urgencia: ¿qué pierde la persona si llega diez minutos tarde? Estos valores son reglas prácticas, no cifras de ningún estándar:

Fíjate en que los avisos con hora fija no tienen un TTL fijo: depende de cuándo los envíes. Un recordatorio que sale tres horas antes de la cita necesita un TTL de unas tres horas; si sale la víspera, de casi un día. Para elegir qué avisos merecen enviarse en primer lugar, repasa las notificaciones transaccionales.

Cómo fijar ttl y urgency al enviar

En la API de castly, POST /v1/notifications acepta dos campos opcionales: ttl, en segundos, de 0 a 2419200, y urgency. Si no los indicas, el aviso usa 86400 y normal: puede llegar hasta 24 horas tarde, algo razonable para mensajes generales pero no para nada con hora. Todos los campos están en la referencia de la API.

// Recordatorio de cita: deja de tener sentido a la hora de la cita
const secondsLeft = Math.floor((appointment.startsAt - Date.now()) / 1000);
const ttl = Math.min(secondsLeft - 300, 2419200); // 5 min de margen, 28 días como máximo

if (ttl > 0) {
  await fetch('https://castly.sh/v1/notifications', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.PUSH_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: { type: 'users', userIds: [appointment.userId] },
      title: 'Recordatorio: tu cita es a las 17:30',
      body: 'Consulta 3. Toca para ver cómo llegar.',
      url: `https://example.com/citas/${appointment.id}`,
      ttl,
      urgency: secondsLeft < 3600 ? 'high' : 'normal',
    }),
  });
}

Calcula el TTL justo antes de llamar a la API, no cuando programas el recordatorio: si el envío sale más tarde de lo previsto, un TTL calculado de antemano dejaría pasar avisos que ya no tienen sentido. Y si ya es tarde, no envíes nada.

Para probarlo sin escribir código, el Playground del panel deja elegir la vida del aviso (desde «ahora o nunca» hasta 28 días) y la urgencia antes de mandar una push de prueba a tu navegador. Una prueba útil: con un dispositivo de prueba apagado, envía un aviso con «ahora o nunca» y enciéndelo un minuto después. No debería aparecer nada.

Qué verás en tus métricas

Un aviso cuyo TTL vence antes de que el dispositivo se conecte queda como enviado, pero nunca como entregado. En el detalle de la notificación, o con GET /v1/notifications/:id, ese dispositivo aparece en sent sin pasar a delivered. Con TTL cortos, la proporción de entregadas baja, y es lo esperado: no lo «arregles» subiendo el TTL.

No lo confundas con una suscripción caducada: ahí el dispositivo ya no existe para tu web; aquí solo estaba desconectado mientras el aviso tenía sentido. Y para juzgar si un contenido funciona, mide los clics sobre las entregadas, no sobre las enviadas, como explicamos en cómo medir la tasa de clics.

Preguntas frecuentes

¿Qué TTL y urgencia se usan si no indico nada?

Un TTL de 86400 segundos (24 horas) y urgencia normal. Sirven para avisos generales, pero cualquier mensaje con fecha u hora merece su propio valor.

¿Cuál es el TTL máximo?

La API acepta hasta 2419200 segundos, es decir, 28 días. Es un máximo, no una garantía: el servicio push del navegador puede guardar el mensaje menos tiempo.

¿La urgencia high garantiza que el aviso llegue al instante?

No. Pide al dispositivo que no lo retrase para ahorrar batería, pero si está apagado o sin conexión el mensaje espera igual, como mucho hasta que venza el TTL.

¿El TTL borra una notificación que ya se mostró?

No. El TTL solo limita cuánto puede esperar el aviso antes de entregarse; una vez en pantalla, normalmente se queda en el centro de notificaciones hasta que la persona lo descarta. Por eso el texto debe seguir siendo cierto un rato después, o indicar la hora a la que se refiere.