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.) y las plantillas para cada uno
• Cómo segmentas y orientas a los usuarios
• Las métricas de análisis o conversión que rastreas

​

2. Mapear tu terminología a OneSignal

​

3. Agregar el SDK de OneSignal (desarrolladores)

• login — Establece el External ID para identificar a un usuario en dispositivos y canales.
• addEmail — Crea una suscripción de email a partir de una dirección recopilada en tu app o sitio.
• addSms — Crea una suscripción de SMS a partir de un número de teléfono recopilado en tu app o sitio.

​

4. Eliminar tu implementación heredada

• Migración limpia — Elimina tu SDK antiguo por completo y reemplázalo con OneSignal en una sola versión de la app. Este es el enfoque recomendado.
• Migración por fases — Mantén ambos SDKs temporalmente, enviando desde cada proveedor a diferentes grupos de usuarios según la versión de la app. Usa esto solo si no puedes eliminar el SDK antiguo en una sola versión.

​

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

​

Conflicto con el SDK de Firebase Messaging

• Elimina los receivers heredados de Firebase de AndroidManifest.xml.
• No llames a FirebaseMessaging.getToken() ni a FirebaseMessaging.deleteToken().
• Asegúrate de que OneSignal sea el único SDK que gestiona el ciclo de vida del token push.

​

Manejo de payload push

​

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

• Deja que OneSignal gestione los tokens push de forma exclusiva. Comparte el token con tu sistema antiguo si es necesario (consulta Conflictos de token push arriba).
• Actualiza filtros de payload para que tu SDK heredado ignore los pushes de OneSignal (consulta Manejo de payload push arriba).
• Envía desde tu proveedor antiguo a usuarios en la versión anterior de la app y desde OneSignal a usuarios en la versión más nueva.
• Establece una fecha de corte clara y un plan de eliminación gradual.

​

5. Migración de web push

1. Elimina el código del SDK heredado y los archivos de Service Worker de tu sitio web.
2. Agrega el siguiente fragmento para cancelar el registro del antiguo Service Worker. Reemplaza sw.js con el nombre del archivo Service Worker de tu proveedor heredado.

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

​

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 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.
2. Exporta datos de usuario de prueba del sistema antiguo.
3. Formatea datos para la API Create user de OneSignal.
4. Importa primero los usuarios de prueba. Una vez verificado, repite el proceso para los usuarios restantes antes del lanzamiento.

​

8. 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 ni 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 desde OneSignal.
• Verifica si hay 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 y confirma con tus desarrolladores qué ruta de migración se tomó (limpia o por fases) y si se importaron usuarios.
• En tu plataforma anterior, crea un segmento de usuarios que aún no han actualizado a la nueva versión de la app. Continúa enviando desde tu proveedor antiguo a este grupo, animándolos a actualizar.
• Deja de enviar desde el proveedor anterior una vez que los conteos de suscriptores se estabilicen en OneSignal.
• Si sigues una migración por fases, elimina el SDK del proveedor antiguo en el próximo lanzamiento de la app después de la fecha de corte.

​

Preguntas frecuentes

​

¿Puedo ejecutar OneSignal junto con mi proveedor push actual?

​

¿Puedo importar suscriptores de web push?

​

¿Necesito volver a solicitar permiso de push a los usuarios después de migrar?

​

¿Se requiere calentamiento de email?

​

¿Puedo obtener una dirección IP dedicada?

​

¿Por cuánto tiempo debo seguir enviando desde mi proveedor antiguo?