OneSignal: Guía Completa de Implementación (Mobile Push, Web Push y Email)
Guía completa para implementar OneSignal en Mobile Push, Web Push y Email: pasos exactos, errores comunes y configuración avanzada, basada en implementaciones reales con clientes de Bildung Data.
OneSignal es la plataforma de mensajería omnicanal más utilizada del mundo — y por una buena razón. Permite enviar push notifications, emails, SMS e In-App Messages desde un solo lugar, con una integración técnica relativamente sencilla. Pero "relativamente sencilla" no significa que no haya errores comunes que hacen perder tiempo, suscriptores y dinero. Esta guía, armada desde nuestra experiencia implementando OneSignal con clientes reales, cubre todos los canales con los pasos exactos que hay que seguir — y los errores que hay que evitar.
Si necesitás ayuda implementando OneSignal o querés revisar tu implementación actual, escribime a guido@bildungdata.com.
📱 Mobile Push & In-App Messages
El canal más impactante de OneSignal. Bien implementado, el push mobile tiene tasas de apertura 3-10x superiores al email. Acá están los pasos críticos para hacerlo bien desde el inicio.
Paso 1 — Crear la app en OneSignal
Ingresá a onesignal.com → New App/Website → elegí "Mobile App". Una vez creada, guardá el App ID y la REST API Key desde Settings. Los vas a necesitar en la integración del SDK y en los llamados a la API REST.
Paso 2 — Cargar las credenciales de push
Cada plataforma requiere sus propias credenciales para poder enviar notificaciones:
Android (FCM): subir el archivo JSON de Firebase desde la consola de Firebase.
iOS (APNs): subir el certificado .p8 de Apple desde tu Apple Developer Account.
Huawei: credenciales de Huawei Push Kit (si tu app necesita soporte para dispositivos sin Google Play).
Dónde configurarlas: Settings → Push & In-App → Google Android (FCM) / Apple iOS (APNs).
Paso 3 — Instalar el SDK en la app
Agregá el SDK de OneSignal al proyecto: vía Gradle para Android o CocoaPods / Swift Package Manager para iOS. Una vez instalado, inicializá con el App ID en el arranque de la app — en el Application.onCreate() en Android o en el AppDelegate en iOS.
Paso 4 — Configurar el small icon en Android
Este paso es fácil de pasar por alto y tiene un impacto visible: sin un ícono configurado correctamente, las notificaciones de Android aparecen con un ícono genérico blanco. El ícono debe ser un PNG con fondo transparente y diseño monocromo. Tamaño recomendado: 96x96px.
Paso 5 — Pedir permiso con un InApp previo (soft opt-in)
Antes de mostrar el permission prompt nativo del sistema operativo, mostrá un InApp Message propio que explique el valor de las notificaciones. Esto mejora drásticamente el opt-in rate.
Crítico para iOS: el prompt nativo de iOS solo se puede mostrar UNA VEZ. Si el usuario lo rechaza, no se puede volver a pedir sin que vaya a configuraciones manualmente. Por eso el InApp previo es fundamental — filtrá a los usuarios que van a decir que sí antes de gastar la única oportunidad.
Paso 6 — Configurar la Notification Service Extension en iOS
La NSE (Notification Service Extension) es un target adicional en Xcode que procesa las notificaciones antes de mostrarlas. Es obligatoria para: Confirmed Delivery, imágenes en notificaciones, badges y action buttons.
Sin la NSE configurada, iOS no reporta Confirmed Deliveries y las imágenes simplemente no aparecen. También hay que configurar App Groups para que la NSE y la app principal puedan compartir datos.
Pasos 7 y 8 — Testing y verificación de métricas
Enviá un mensaje de prueba desde el Dashboard a un device de test. Probá con la app en foreground y background, en Android e iOS por separado. Luego verificá en el Dashboard: suscriptores activos, opt-in rate por plataforma y que los mensajes muestren los estados Sent / Delivered / Confirmed.
🌐 Web Push
Web Push permite enviar notificaciones a los navegadores de escritorio y mobile sin necesidad de una app. Compatible con Chrome, Firefox, Edge y (desde iOS 16.4+) Safari mobile si el usuario agrega el sitio a su pantalla de inicio.
Paso 1 — Crear la app y copiar credenciales
onesignal.com → New App/Website → "Web". Guardá el App ID y REST API Key.
Paso 2 — Instalar el Web SDK
Agregá el snippet JS de OneSignal en el <head> de todas las páginas del sitio. También se puede instalar vía Google Tag Manager. Verificá que cargue sin errores en la consola del navegador antes de continuar.
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
await OneSignal.init({
appId: "TU_APP_ID",
});
});
</script>
Paso 3 — Configurar el Permission Prompt
Tenés tres opciones para pedir permiso al usuario:
Slide Prompt: un banner de OneSignal que convierte mejor que el prompt nativo directo.
Native Browser Prompt: el popup del navegador directamente.
Custom Prompt (InApp previo): tu propio diseño antes del prompt nativo.
Al igual que en iOS mobile, el permission prompt nativo del navegador solo se puede mostrar UNA VEZ. Si el usuario lo rechaza, el navegador no vuelve a preguntar. Usá el Slide Prompt o un InApp previo para maximizar las chances.
Paso 4 — Configurar iOS Web Push (Safari mobile)
Para soportar usuarios en iOS 16.4+ en Safari, necesitás un archivo manifest.json en el directorio raíz de tu sitio. Además, iOS requiere que el usuario agregue el sitio a su pantalla de inicio antes de poder suscribirse — es una limitación del sistema operativo, no de OneSignal.
Pasos 5 y 6 — Testing y métricas web
Creá una campaña de prueba desde el Dashboard y verificá recepción en Chrome y Safari. En el Dashboard deberías ver suscriptores activos, opt-in rate y mensajes con estado Sent / Delivered.
⚙️ Advanced Settings — Opcionales pero muy recomendados
Estos pasos no son obligatorios para enviar el primer mensaje, pero son fundamentales para sacarle el verdadero potencial a OneSignal: segmentación precisa, personalización y automatización.
1 — Identificación de usuarios con external_id
Cuando el usuario hace login en tu app o sitio, identificalo en OneSignal con tu propio ID de usuario. Esto permite targetear usuarios específicos y cruzar los datos de OneSignal con tu backend o CRM.
// Cuando el usuario hace login
OneSignal.login('TU_USER_ID');
// Cuando hace logout
OneSignal.logout();
El external_id debe ser el mismo ID que usás en tu backend. Sin esto, no podés enviar notificaciones transaccionales a un usuario específico.
2 — Data Tags para segmentación
Los Data Tags son propiedades de usuario que podés usar para segmentar y personalizar mensajes. Se envían vía SDK o API.
// Setear propiedades del usuario
OneSignal.User.addTags({
plan: 'premium',
ciudad: 'bsas',
ultima_compra: '2024-03-15'
});
3 — Custom Events para triggers avanzados
Los Custom Events permiten registrar acciones específicas del usuario para disparar automatizaciones (Journeys) e In-App Messages.
// Trackear un evento personalizado
OneSignal.trackEvent('purchase', { amount: 100, product: 'course' });
// Otros ejemplos
OneSignal.trackEvent('article_read', { category: 'tecnologia' });
OneSignal.trackEvent('checkout_started');
Los triggers básicos como "app open" o "tiempo en pantalla" funcionan sin código adicional. Los Custom Events requieren implementación pero abren posibilidades avanzadas de personalización.
4 — Mensajería transaccional vía API REST
Para envíos automáticos desde tu backend (ej: "pedido despachado", confirmación de pago, alertas de sistema), integrá el endpoint POST /notifications de la API REST de OneSignal.
curl --request POST \
--url https://api.onesignal.com/notifications \
--header 'Authorization: Key TU_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"app_id": "TU_APP_ID",
"include_aliases": { "external_id": ["user_123"] },
"target_channel": "push",
"contents": { "en": "Tu pedido fue despachado 🚀" }
}'
5 — Migrar suscriptores existentes
Si venías con otro proveedor de push, podés importar los push tokens históricos y emails vía CSV o API para no perder tu base de suscriptores.
✉️ Email
OneSignal también maneja email, lo que permite coordinar push y email desde un solo lugar. Eso es muy poderoso para Journeys omnicanal: si el usuario no abre el push en 24hs, le mandás el email automáticamente.
Paso 1 — Habilitar el canal Email
Ir a Settings → Platforms → Email → Activate. Por defecto OneSignal usa Mailgun con IP compartida. Si ya tenés Sendgrid, Mailgun propio o Mailchimp, podés conectarlos para no pagar volumen de email a OneSignal. Para alto volumen, se puede solicitar una IP dedicada.
Paso 2 — Configurar el dominio de envío (SPF / DKIM / DMARC)
Este es el paso más técnico y el más crítico para la deliverabilidad. Sin autenticación del dominio, los emails caen en spam. Hay que agregar tres registros DNS:
SPF: autoriza a OneSignal a enviar emails en nombre de tu dominio.
DKIM: firma criptográfica que verifica que el email no fue alterado en tránsito.
DMARC: define qué hacer con los emails que no pasen SPF o DKIM.
Este paso lo debe hacer el equipo de IT o quien administre el DNS del dominio. Sin esto, no importa qué tan buenos sean tus emails — van al spam.
Paso 3 — From Name, From Email y Reply-To
Configurá el nombre y dirección del remitente que verán los usuarios (ej: "Equipo MiApp" hola@miapp.com). También configurá el Reply-To para los casos en que los usuarios respondan directamente.
Pasos 4 y 5 — Importar emails existentes y capturar nuevos vía SDK
Si tenés una base de emails histórica, importala vía CSV o API. Incluí el external_id para cruzar con los perfiles de usuario existentes. Solo importá usuarios que tenían opt-in previo — nunca listas compradas.
// Capturar el email del usuario cuando lo ingresa
OneSignal.User.addEmail('usuario@mail.com');
Pasos 6 y 7 — Templates y Unsubscribe
Creá los templates en el editor drag-and-drop de OneSignal. Siempre incluí un link de unsubscribe visible y funcional — es requerido legalmente (CAN-SPAM, GDPR). OneSignal lo gestiona automáticamente si usás su footer por defecto.
Pasos 8 y 9 — Testing y métricas de deliverability
Antes de lanzar, enviá un email de prueba a una dirección propia y verificá: que llega, que no cae en spam, que los links funcionan y que el unsubscribe funciona. Revisá en Gmail y Outlook, y en vista mobile.
Métricas de referencia: bounce rate normal menor a 2%, open rate objetivo mayor a 20%. Un bounce rate alto indica problemas de lista o de configuración DNS.
📌 Canales Adicionales: SMS, WhatsApp e Integraciones
OneSignal también soporta SMS vía Twilio y WhatsApp vía Meta/Twilio Webhooks, lo que lo convierte en una plataforma verdaderamente omnicanal. En cuanto a integraciones nativas, tiene conectores con Amplitude, Mixpanel y Appsflyer — muy útiles para cruzar datos de comportamiento con las campañas de mensajería.
Conclusión: el orden importa
OneSignal es una plataforma muy poderosa, pero como toda integración técnica, el diablo está en los detalles. Los errores más costosos que vemos en implementaciones reales son: no configurar la NSE en iOS (perdés Confirmed Delivery e imágenes), gastar el prompt nativo sin un InApp previo (perdés opt-in rate para siempre), y no autenticar el dominio de email (tus emails van al spam desde el día uno).
Seguir esta checklist en orden te evita esos errores y te deja una implementación sólida sobre la cual construir campañas, Journeys y automatizaciones que realmente convierten. Si necesitás ayuda con la implementación, en Bildung Data somos partners de OneSignal y acompañamos proyectos de integración end-to-end.
📖 Documentación oficial completa: documentation.onesignal.com
