Migrar a OneSignal

• Desarrolladores implementando el SDK de OneSignal
• Especialistas en marketing gestionando campañas y análisis

​

Requisitos previos

• Configura una cuenta en OneSignal
• Invita a tu equipo

​

Pasos de migración

​

1. Auditar tu configuración de mensajería actual

• Las plataformas que soportas: iOS, Android, Web, email, SMS, etc.
• El código que maneja eventos de push y mensajes en la app:
  • Visualización en primer plano y manejo de clics
  • Uso de deep links para push, email, etc.
  • Manejo de tokens push y payloads
• Cómo estás recopilando direcciones de email, números de teléfono, tokens push, etc.
• Dominios de email y propiedad de DNS
• Remitentes de SMS y mecanismos de opt-in

• Los tipos de mensajes que envías: (transaccionales, marketing, etc.)
  • Plantillas para esos mensajes
• Cómo estás segmentando y orientando usuarios.
• Las métricas de análisis o conversión que rastreas.

​

2. Conceptos básicos de OneSignal

• Usuarios - Identificados vía External ID. Los usuarios están compuestos de propiedades (etiquetas, datos de sesión, etc.) y suscripciones (push, email, SMS).
• Suscripciones - Se refiere a cómo un usuario puede recibir mensajes. Hay 4 tipos de suscripciones:
  • Móvil: Puede recibir notificaciones push, mensajes en la app y Live Activities.
  • Web push: Puede recibir notificaciones push web.
  • Email: Puede recibir notificaciones de email.
  • SMS: Puede recibir notificaciones SMS.
• Segmentos - Un grupo de usuarios que comparten propiedades comunes.
• Etiquetas - Una propiedad de usuario personalizada.
• Eventos personalizados - Una acción que realiza un usuario.

​

3. Agregar el SDK de OneSignal (desarrolladores)

​

Identificar usuarios con External ID

• SDK móvil
• SDK web

​

Recopilar nuevos emails y números de teléfono

• Suscripciones de email: usa el método addEmail en nuestro SDK móvil y SDK web
• Suscripciones SMS: usa el método addSms en nuestro SDK móvil y SDK web

​

4. Eliminar tu implementación heredada

​

Conflictos y formato de token push

• Obtén el identificador de token push del dispositivo usando nuestro SDK móvil frontend
• Obtén el identificador del dispositivo usando nuestra API View user

• Formato de token APNS de iOS Push: 64 caracteres, solo caracteres hexadecimales (0-9,a-f). deviceToken.map {String(format: "%02x", $0)}.joined()
• Formato de token FCM de Android Push: Típicamente 163 caracteres, caracteres alfanuméricos, puede contener guiones, dos puntos y guión bajo.

​

Manejo de payload push

​

Migración por fases (solo apps móviles)

• No permitas que múltiples SDKs generen tokens push. Deja que OneSignal lo maneje, y comparte el token con tu sistema antiguo si es necesario.
  • Usa SDK frontend o API View user
• Actualiza filtros de payload para que tu SDK heredado no procese pushes de OneSignal.
  • OneSignal usa una clave "custom" en su rawPayload (docs).
  • Verifica esta clave en NotificationCompat (Android).
• Decide qué proveedor maneja qué tipos de notificaciones.
• Establece una fecha de corte clara y construye un plan de eliminación gradual para sistemas heredados.
  • Crea una plantilla de notificación para cada tipo de notificación que envíes.
  • Configura tu proveedor antiguo para enviar mensajes a usuarios en la versión anterior de tu app y OneSignal para enviar mensajes a usuarios en la versión más nueva de tu app.
  • Crea segmentos para orientar grupos de usuarios específicos.

​

5. Migración de web push

• No puedes importar suscripciones de web push debido a límites de seguridad del navegador. OneSignal registrará a los usuarios cuando regresen.
• Debes cancelar el registro de tus antiguos push service workers antes de que OneSignal pueda tomar el control.

1. Elimina el SDK heredado: Código en el sitio web y archivos de Service Worker.
2. Agrega este código para asegurarte de que el Service Worker se cancele el registro.
3. Reemplaza sw.js con el nombre del archivo Service Worker de terceros.

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.getRegistrations().then(function(registrations) {
    for (let registration of registrations) {
      if (registration.active.scriptURL.includes("sw.js")) {
        registration.unregister();
      }
    }
  });
}

​

Migrar entre apps de OneSignal

• Las suscripciones de web push no pueden transferirse directamente entre apps. Cada suscripción está vinculada tanto al dominio (origin) de tu sitio como al App ID de OneSignal.
• Para migrar, actualiza el código de inicialización de OneSignal de tu sitio para usar el appId de App B:

OneSignal.init({
  appId: "YOUR_APP_B_ID",
});

• Cuando un usuario revisite tu sitio, el permiso push existente del navegador permitirá que OneSignal los registre silenciosamente en App B.
• No aparecerá un nuevo prompt de permiso, pero los usuarios deben visitar tu sitio al menos una vez para que la suscripción se cree en App B.
• Los suscriptores continuarán apareciendo en App A hasta que se vuelvan inactivos.

​

6. Configuración de email y SMS

​

¿Se requiere calentamiento de email?

​

¿Puedo obtener una dirección IP dedicada?

​

7. Importar usuarios existentes (opcional)

​

Consideraciones de plataforma

• Las direcciones de email deben ser de usuarios activos y válidos. No importes direcciones de email que nunca han hecho clic o abierto emails antes.
• Los números de teléfono deben estar en un formato específico y los usuarios deben haber consentido recibir SMS.
• Las suscripciones de iOS pueden comenzar a recibir notificaciones push inmediatamente después de la importación. Características como el seguimiento de clics de notificación y entregas confirmadas requieren que nuestro SDK esté activo en el dispositivo.
• Las suscripciones de Android/Huawei/Amazon deben tener nuestro SDK activo en el dispositivo para recibir notificaciones, ya sea a través de una actualización automática o actualización manual.
• Las suscripciones web no pueden importarse. Si sigues lo anterior en Migración de web push, la suscripción de web push se creará y el token push se obtendrá vía nuestro SDK cuando el usuario regrese al sitio.

​

Pasos de importación

1. Revisa los documentos de Usuarios y Suscripciones para comprender.
2. Exporta datos de usuario de prueba del sistema antiguo.
3. Formatea datos para la API Create user de OneSignal.
4. Importa usuarios de prueba y tras pruebas exitosas, mantén el proceso para repetir en la lista de verificación previa al lanzamiento.

• token - El token push o dirección de email o número de teléfono
• type - El tipo de suscripción: iOSPush, AndroidPush, WebPush, Email, SMS
• external_id - Un identificador único para el usuario. Se recomienda usarlo para seguimiento y análisis.

  {
    "identity": {
      "external_id": "user_12345"
    },
    "subscriptions": [
      {
        "type": "iOSPush",
        "token": "7abcd49d0affb7426a8f1202420e8f4e2fc4df58e49501adc383f3bd66df8636"
      },
      {
        "type": "AndroidPush",
        "token": "dQGm89TZQXiTvLsRIj_GBo:APA91bpgqFgqkP2qYvV1uW2kdK5Z3TjgCXB_1jkL6VJrgH3hoYn16MvFY19tzDE4OuSgKjYC7itbFpSJYHBfKLWt-xZYBpgCVhYn9K5neV_9-Zj7s9mOSjRUJ2IwEwVSYhR-j5ICF9WB"
      },
      {
        "type": "Email",
        "email": "test@example.com"
      },
      {
        "type": "SMS",
        "phone_number": "+1234567890"
      }
    ]
  }

​

7. Probar la migración

1. Habilita Debug Logging en el SDK de OneSignal.
2. Prueba en dispositivos reales para todas las plataformas (Android, iOS, Web, etc.).
3. Verifica el manejo de notificaciones tanto en primer plano como en segundo plano.

• Envía notificaciones de prueba desde OneSignal a usuarios importados antes de agregar el SDK de OneSignal.
  • Deberías recibir el push en iOS pero no obtendrás entrega confirmada o análisis de clics.
  • Podrías recibir el push en Android si tienes otro SDK push y aún no implementaste los requisitos de Manejo de payload. Es probable que la notificación falte datos y no funcione como se espera al hacer clic.
• Envía notificaciones de prueba desde OneSignal a usuarios importados después de agregar el SDK de OneSignal.
  • Deberías recibir el push tanto en Android como en iOS junto con entrega confirmada y análisis de clics.
• Prueba el comportamiento de notificaciones con la app en diferentes estados.
• Verifica que los deep links y acciones personalizadas funcionen correctamente.

• Envía desde tu proveedor actual y OneSignal.
• Verifica notificaciones duplicadas
• Verifica que las notificaciones de cada proveedor se muestren correctamente
• Prueba escenarios de inicio/cierre de sesión de usuario

​

Lista de verificación previa al lanzamiento

• Construye un plan de mensajería para solicitar actualizaciones de app
• Considera usar push y mensajes en la app desde tu sistema antiguo para recordar suavemente a los usuarios que actualicen.

• Verifica que los análisis de push y mensajes en la app funcionen como se espera.
  • Los eventos de clic y entrega confirmada se rastrean en Android e iOS.
• Verifica que los eventos de clic y eventos recibidos en primer plano se manejen correctamente para mensajes enviados desde ambos proveedores.
• Si importas usuarios, exporta usuarios de Android e iOS que han estado activos en tu app en los últimos 270 días para evitar importar tokens expirados. Consulta Preguntas frecuentes sobre token expirado de FCM para detalles.

​

Lanzar tu app/sitio

• La mayoría de los usuarios tendrán su app actualizada automáticamente a la última versión.
• Cuando los usuarios abran tu app actualizada, no se les solicitará suscribirse a notificaciones push si los permisos ya fueron otorgados—ya sea a través de los prompts de permiso requeridos o la configuración de notificaciones de la app.

• Los usuarios se crearán automáticamente en OneSignal cuando abran la versión actualizada de la app. No se les solicitará push si estaban suscritos previamente.
• Necesitarás esperar a que abran la app actualizada antes de poder enviarles mensajes.
• Continúa enviando notificaciones y mensajes en la app desde el proveedor push anterior durante un par de días hasta que suficientes usuarios aparezcan en OneSignal. Envía alertas adicionales pidiéndoles que actualicen la app a la última versión.

​

Monitorear resultados

• Monitorea tasas de error y caídas después del despliegue.
• Observa invalidaciones de token inesperadas.
• Verifica análisis de integración de SDK.

• Marca la fecha de lanzamiento de la app.
• Comunícate con tus desarrolladores sobre:
  • Qué ruta de migración se tomó (migración Limpia o Por fases).
  • ¿Se importaron usuarios?
• Si sigues una migración Limpia:
  • En la plataforma anterior, crea un segmento o cohorte de usuarios que continúan activos. Verifica sus tiempos de sesión, mensajes recibidos y eventos de clic.
  • Solo los usuarios que no han actualizado la app deberían continuar activos y contenidos en este grupo.
  • Continúa enviando push y mensajes en la app desde tu proveedor anterior a estos usuarios, empujándolos suavemente a actualizar.
  • Deja de enviar desde el proveedor anterior hasta que estés listo para moverte completamente a OneSignal.
• Si sigues una migración Por fases:
  • En la plataforma anterior, crea un segmento o cohorte de usuarios que tienen la versión anterior de la app antes de OneSignal.
  • Continúa enviando push y mensajes en la app desde tu proveedor anterior a estos usuarios de app anterior, empujándolos suavemente a actualizar.
  • Deja de enviar desde el proveedor anterior hasta que estés listo para moverte completamente a OneSignal.
  • Elimina el código del proveedor push anterior en el próximo lanzamiento de la app.