Segmentar notificaciones push con etiquetas e IDs de usuario

Para segmentar notificaciones push se combinan dos herramientas: el ID de usuario, que vincula cada dispositivo suscrito con una cuenta de tu sistema y te deja avisar a una persona en todos sus dispositivos, y las etiquetas, pares clave-valor que describen al suscriptor (plan, idioma, intereses) y te dejan avisar a grupos. El ID se asigna al iniciar sesión; las etiquetas hay que mantenerlas al día cada vez que cambia el dato que representan.

En resumen:

• Un suscriptor es un navegador en un dispositivo; un usuario puede tener varios o ninguno.
• Usa el ID de usuario para avisos personales y las etiquetas para grupos estables.
• Diseña pocas etiquetas, con valores de texto cortos, normalizados y sin datos personales.
• Un segmento exige todas sus etiquetas a la vez; para un «o» necesitas otra estrategia.
• Si el dato vive en tu base de datos y cambia a menudo, envía a una lista de usuarios en lugar de copiarlo en etiquetas.

Suscriptor, usuario y etiqueta: tres cosas distintas

Casi todos los errores de segmentación vienen de confundir estos tres conceptos:

De aquí salen dos consecuencias. La primera: una persona con portátil y móvil tiene dos suscriptores con el mismo ID de usuario, y un envío por ID llega a ambos. La segunda: las etiquetas viven en cada suscriptor, no en la persona. Si Ana pasa al plan Pro desde el portátil y solo actualizas las etiquetas de ese navegador, su móvil seguirá diciendo free.

Vincular el ID de usuario

El ID de usuario es el identificador de tu propia base de datos. Asígnalo en dos momentos: al suscribir, si la persona ya ha iniciado sesión, y al iniciar sesión en un navegador que se suscribió como anónimo. Con el SDK de castly queda así:

// Desde el clic en «Activar avisos»
await Castly.subscribe({ userId: currentUser?.id, tags: { lang: 'es' } });

// Al iniciar sesión, si este navegador ya estaba suscrito
await Castly.identify(user.id, { lang: 'es', plan: user.plan });

// Al cerrar sesión en un equipo compartido
await Castly.identify(null);

El último paso se olvida a menudo. Si dos personas comparten un ordenador y no desvinculas el ID al cerrar sesión, la segunda recibirá los avisos personales de la primera.

Usa un ID interno y opaco, nunca el email ni el teléfono. El ID viaja en exportaciones, registros y webhooks, y cuantos menos datos personales contenga, menos tendrás que proteger; lo ampliamos en RGPD y notificaciones push.

Diseñar etiquetas que sirvan

Una buena etiqueta describe algo que cambia poco y que comparte mucha gente. En castly, cada suscriptor admite hasta 30 pares clave-valor de texto; las claves usan letras, números, guiones y guiones bajos (hasta 64 caracteres) y los valores tienen hasta 200 caracteres. Estos ejemplos muestran la diferencia:

Normaliza los valores (minúsculas, sin espacios, siempre el mismo vocabulario) y recuerda que son texto: "yes" o "1", no true. Una etiqueta escrita como Pro en un sitio y pro en otro parte tu segmento en dos sin que nadie lo note.

Enviar a un segmento o a usuarios concretos

Para un grupo, envía a un segmento. Un suscriptor entra en él solo si tiene todas las etiquetas indicadas a la vez; este ejemplo llega a quien tenga plan: pro y lang: es:

{
  "to": { "type": "segment", "tags": { "plan": "pro", "lang": "es" } },
  "title": "Ya está disponible el informe de noviembre",
  "url": "https://example.com/informes/2026-11"
}

Para personas concretas, usa el destino users con tus IDs (hasta 1000 por petición). Llega a todos los dispositivos activos de cada persona:

{
  "to": { "type": "users", "userIds": ["u_1842", "u_2093"] },
  "title": "Tu pedido ha salido del almacén"
}

Como el segmento combina con «y», el «o» requiere pensar un poco:

• Valores distintos de una misma clave (plan: pro o plan: scale): haz un envío por valor. Un suscriptor solo tiene un valor por clave, así que nadie recibe el aviso dos veces.
• Claves distintas (deals o news): dos envíos duplicarían el aviso a quien tenga ambas. Calcula la lista de usuarios en tu base de datos y envía a users, o crea una etiqueta derivada que represente la unión.

Antes de un envío grande, comprueba el tamaño de la audiencia: GET /v1/subscribers?status=active&tag=plan:pro lista los suscriptores activos con esa etiqueta. Todos los destinos y filtros están en la referencia de la API.

Mantener las etiquetas al día

Las etiquetas envejecen. Hay tres momentos para actualizarlas:

• Al iniciar sesión: identify() con las etiquetas actuales de la cuenta, como en el ejemplo anterior.
• Cuando la persona cambia una preferencia en tu web: setTags(). Sustituye las etiquetas del navegador por las que le pasas, así que envía siempre el conjunto completo y no solo la que cambia.
• Cuando el dato cambia en tu servidor, por ejemplo un cambio de plan que llega por el webhook de tu sistema de cobro: actualiza desde el backend todos los dispositivos del usuario.

const API = 'https://castly.sh/v1';
const headers = {
  Authorization: `Bearer ${process.env.PUSH_SECRET_KEY}`,
  'Content-Type': 'application/json',
};

async function updatePlanTag(userId, plan) {
  const url = `${API}/subscribers?userId=${encodeURIComponent(userId)}&status=active&limit=100`;
  const { data } = await fetch(url, { headers }).then((r) => r.json());
  for (const sub of data) {
    await fetch(`${API}/subscribers/${sub.id}`, {
      method: 'PATCH',
      headers,
      body: JSON.stringify({ tags: { ...sub.tags, plan } }), // conserva las demás
    });
  }
}

Si un dato cambia muy a menudo o solo existe en tu base de datos, no lo copies en etiquetas: consúltalo en el momento del envío y manda a la lista de usuarios resultante. Las etiquetas funcionan mejor para atributos estables o que conoce el propio navegador, como el idioma o los temas que la persona eligió en tu web.

Preguntas frecuentes

¿Puedo usar el email como ID de usuario?

Técnicamente es un texto como otro cualquiera, pero no conviene. El email es un dato personal que acabaría en registros y exportaciones, y además cambia; un ID interno opaco es más seguro y más estable.

¿Qué pasa con los suscriptores que no han iniciado sesión?

No tienen ID de usuario, así que solo puedes alcanzarlos con etiquetas o con un envío a todos. Cuando inicien sesión, identify() vincula su suscripción a la cuenta sin que tengan que volver a dar permiso.

¿Las etiquetas se comparten entre los dispositivos de un mismo usuario?

No. Cada suscriptor tiene sus propias etiquetas, de modo que el móvil y el portátil de una misma persona pueden tener valores distintos. Si el atributo pertenece a la cuenta, actualízalo en todos sus dispositivos desde el servidor.

¿Cuántas etiquetas debería usar?

Las menos posibles: unas pocas claves bien definidas, documentadas y con un vocabulario cerrado. El límite técnico suele ser holgado; el problema real es acabar con etiquetas que nadie mantiene y segmentos que ya no significan lo que dicen.

¿Cómo sé si un segmento responde mejor que otro?

Compara los clics sobre notificaciones entregadas de cada segmento con el mismo tipo de aviso y la misma ventana de tiempo. Te lo explicamos en cómo medir la tasa de clics.