Requisitos
- Una app Expo administrada. Para apps React Native simples, consulta Configuración del SDK React Native.
- Expo development build
- Expo SDK 53+ (React Native 0.79+) con Nueva Arquitectura habilitada
- EAS CLI (documentación EAS Build)
- App y plataforma de OneSignal configuradas
- macOS con Xcode 14+ (las instrucciones de configuración usan Xcode 16.2)
- Dispositivo con iOS 12+, iPadOS 12+ o simulador Xcode ejecutando iOS 16.2+
- CocoaPods 1.16.2+
- Dispositivo o emulador Android 7.0+ con Google Play Store (Services) instalado
Configure su aplicación y plataforma de OneSignal
Configure su aplicación de OneSignal con las plataformas que admite — Apple (APNs), Google (FCM), Huawei (HMS) y/o Amazon (ADM).Instrucciones de configuración paso a paso
Instrucciones de configuración paso a paso
Cree o seleccione su aplicación

Configuración de su primera aplicación, organización y canal de OneSignal.
Configure las credenciales de plataforma
- Android: Configure las credenciales de Firebase
- iOS: Token p8 (Recomendado) o Certificado p12
- Amazon: Genere una clave API
- Huawei: Autorice OneSignal
Guarde su ID de aplicación e instale el SDK

Guarde su ID de aplicación e invite a miembros adicionales del equipo.
Configuración del SDK
1. Agregar SDK
Instala el plugin Expo de OneSignal usando la CLI de Expo.react-native-onesignal a tu proyecto.
2. Configurar el plugin
Abre tuapp.json (o app.config.js / app.config.ts). Debes incluir las siguientes configuraciones.
Configuraciones requeridas
UIBackgroundModes establecida en ["remote-notification"].- Establece
aps-environmenten"development"para pruebas y"production"para compilaciones de TestFlight y App Store.
Props adicionales del plugin.
Props adicionales del plugin.
Opcional: Deshabilitar el módulo de ubicación
Si tu app no usaOneSignal.Location, establece disableLocation en true en las props del plugin Expo de OneSignal. Esta opción requiere react-native-onesignal 5.5.1 o posterior. El plugin configura la resolución de dependencias nativas para que react-native-onesignal excluya el módulo de ubicación. En iOS, el plugin escribe la configuración de entorno del Podfile que se usa durante la resolución de CocoaPods. En Android, el plugin escribe onesignal.disableLocation=true en las propiedades Gradle generadas.
Podfile de iOS generado declara explícitamente OneSignalXCFramework en un target de Notification Service Extension o de widget de Live Activity, usa una subespecificación modular como OneSignalXCFramework/OneSignal o OneSignalXCFramework/OneSignalLiveActivities. El pod 'OneSignalXCFramework' agregado resuelve OneSignalComplete e incluye ubicación. Después de un prebuild limpio, verifica que ni OneSignalComplete ni OneSignalLocation aparezcan en ios/Podfile.lock.
- app.config.ts
- app.json
onesignal-expo-plugin 2.6.0, puedes importar withOneSignal para obtener soporte completo de TypeScript y autocompletado en las props del plugin.3. Inicializar SDK
Dependiendo de tu estructura Expo (entrada de App tradicional o Expo Router), inicializa OneSignal siguiendo estas opciones.- Entrada de App Tradicional
- Expo Router
App.tsx o App.js inicializa OneSignal con los métodos proporcionados.Reemplaza YOUR_APP_ID con tu ID de App de OneSignal que se encuentra en tu dashboard de OneSignal Settings > Keys & IDs.useCallback
Si tu listener necesita acceder a props o state, defínelo fuera de useEffect con useCallback para que la misma referencia se use al agregar y quitar el listener. Pasar referencias de función diferentes a addEventListener y removeEventListener no tiene efecto — el listener no se elimina y puede dispararse después de que el componente se desmonte.
Configuración de Android
Asegúrese de que su aplicación de OneSignal esté configurada para la plataforma Android usando sus credenciales de Firebase. Configure sus iconos de notificación para que coincidan con la marca de su aplicación. El icono pequeño es obligatorio. Si lo omite, las notificaciones muestran un icono de campana predeterminado. Compilar para Android En este punto, debería poder compilar y ejecutar su aplicación en un dispositivo Android físico o emulador sin problemas.- Continúe con la configuración de iOS, si corresponde.
- O avance a Probar la integración del SDK de OneSignal.
Configuración iOS
Asegúrate de que tu app de OneSignal esté configurada para la plataforma iOS usando ya sea el Token p8 (Recomendado) o Certificado p12.Compilar para iOS
Ahora deberías poder compilar y ejecutar tu app en un dispositivo iOS real o simulador iOS (16.2+).Errores comunes de compilación iOS
Cycle Inside... building could produce unreliable results.
Cycle Inside... building could produce unreliable results.
- Abre tu carpeta
.xcworkspaceen Xcode y navega a tu objetivo de app > Build Phases. - Deberías tener una fase llamada “Embed Foundation Extensions” o “Embed App Extensions”.
- Arrastra y mueve esta fase de compilación a arriba de “Run Script”.
- Compila y ejecuta tu app. El error debería estar resuelto.

Orden correcto de Build Phases en Xcode.

Desmarca Copy only when installing.
Error PBXGroup
Error PBXGroup
PBXGroup intentó inicializar un objeto con ISA desconocido PBXFileSystemSynchronizedRootGroup desde atributos: {"isa"=>"...", "exceptions"=>["//", "..."], "explicitFileTypes"=>{}, "explicitFolders"=>[], "path"=>"OneSignalNotificationServiceExtension", "sourceTree"=>"<group>"}- Encuentra la carpeta listada bajo “path” en el error
- En la barra lateral del proyecto Xcode, haz clic derecho en la carpeta
- Selecciona Convert to Group

Error de ruta para PBXGroup.

Convertir carpeta a grupo.
Probar la integración del SDK de OneSignal
Esta guía le ayuda a verificar que su integración del SDK de OneSignal funciona correctamente probando notificaciones push, registro de suscripciones y mensajería in-app.Verificar suscripciones móviles
Inicie su aplicación en un dispositivo de prueba.
requestPermission durante la inicialización.
Mensajes de permiso push de iOS y Android
Verifique su panel de OneSignal
- Vaya a Audiencia > Suscripciones.
- Debería ver una nueva entrada con el estado “Nunca suscrito”.

Panel mostrando suscripción con estado 'Nunca suscrito'
Regrese a la aplicación y toque Permitir en el mensaje.
Actualice la página de suscripciones del panel de OneSignal.

Panel mostrando suscripción con estado 'Suscrito'
Configurar suscripciones de prueba
Las suscripciones de prueba son útiles para probar una notificación push antes de enviar un mensaje.Agregar a suscripciones de prueba.

Agregando un dispositivo a suscripciones de prueba
Nombre su suscripción.
Cree un segmento de usuarios de prueba.
Nombre el segmento.
Test Users (el nombre es importante porque se usará más adelante).Agregue el filtro de usuarios de prueba y haga clic en Crear segmento.

Creando un segmento de 'Usuarios de prueba' con el filtro de usuarios de prueba
Enviar push de prueba mediante API
Obtenga su clave API de aplicación e ID de aplicación.
Actualice el código proporcionado.
YOUR_APP_API_KEY y YOUR_APP_ID en el código a continuación con sus claves reales. Este código usa el segmento Test Users que creamos anteriormente.Ejecute el código.
Verifique imágenes y entrega confirmada.

Notificación push con imagen en iOS y Android
Verifique la entrega confirmada.
Enviar un mensaje in-app
Los mensajes in-app le permiten comunicarse con los usuarios mientras están usando su aplicación.Cierre o ponga en segundo plano su aplicación en el dispositivo.
Cree un mensaje in-app.
- En su panel de OneSignal, navegue a Mensajes > In-App > Nuevo In-App.
- Busque y seleccione el mensaje de Bienvenida.
- Establezca su audiencia como el segmento de usuarios de prueba que usamos anteriormente.

Dirigiéndose al segmento de 'Usuarios de prueba' con un mensaje in-app
Personalice el contenido del mensaje si lo desea.

Ejemplo de personalización del mensaje de bienvenida in-app
Establezca el activador en 'Al abrir la aplicación'.
Programe la frecuencia.

Opciones de programación de mensajes in-app
Active el mensaje.
Abra la aplicación y vea el mensaje.

Mensaje de bienvenida in-app mostrado en dispositivos
- Recopilar suscripciones, configurar suscripciones de prueba y crear segmentos.
- Enviar push con imágenes y entrega confirmada usando segmentos y nuestra API de crear mensaje.
- Enviar mensajes in-app.
Identificación de usuarios
Anteriormente, demostramos cómo crear suscripciones móviles. Ahora ampliaremos la identificación de usuarios en todas sus suscripciones (incluidas push, email y SMS) usando el SDK de OneSignal. Cubriremos IDs externos, etiquetas, suscripciones multicanal, privacidad y seguimiento de eventos para ayudarle a unificar e involucrar a los usuarios en todas las plataformas.Asignar ID externo
Use un ID externo para identificar a los usuarios de manera consistente en todos los dispositivos, direcciones de correo electrónico y números de teléfono utilizando el identificador de usuario de su backend. Esto asegura que su mensajería permanezca unificada entre canales y sistemas de terceros (especialmente importante para integraciones). Establezca el ID externo con el métodologin de nuestro SDK cada vez que sean identificados por su aplicación.
Agregar etiquetas de datos
Las etiquetas son pares clave-valor de datos de cadena que puede usar para almacenar propiedades de usuario (comousername, role o preferencias) y eventos (como purchase_date, game_level o interacciones de usuario). Las etiquetas potencian la personalización de mensajes avanzada y la segmentación, permitiendo casos de uso más avanzados.
Establezca etiquetas con los métodos addTag y addTags de nuestro SDK a medida que ocurren eventos en su aplicación.
En este ejemplo, el usuario alcanzó el nivel 6 identificable por la etiqueta llamada current_level establecida en un valor de 6.

Un perfil de usuario en OneSignal con una etiqueta llamada "current_level" establecida en "6"

Editor de segmentos mostrando un segmento dirigido a usuarios con un valor de current_level mayor que 4 y menor que 10

Captura de pantalla mostrando una notificación push dirigida al segmento Nivel 5-10 con un mensaje personalizado

La notificación push se recibe en un dispositivo iOS y Android con el contenido personalizado
Agregar suscripciones de email y/o SMS
Anteriormente vimos cómo nuestro SDK crea suscripciones móviles para enviar mensajes push e in-app. También puede llegar a los usuarios a través de canales de email y SMS creando las suscripciones correspondientes.- Use el método
addEmailpara crear suscripciones de email. - Use el método
addSmspara crear suscripciones de SMS.

Un perfil de usuario con suscripciones push, email y SMS unificadas por ID externo
- Obtenga consentimiento explícito antes de agregar suscripciones de email o SMS.
- Explique los beneficios de cada canal de comunicación a los usuarios.
- Proporcione preferencias de canal para que los usuarios puedan seleccionar qué canales prefieren.
Privacidad y consentimiento del usuario
Para controlar cuándo OneSignal recopila datos de usuario, use los métodos de control de consentimiento del SDK:setConsentRequired(true): Previene la recopilación de datos hasta que se otorgue el consentimiento.setConsentGiven(true): Habilita la recopilación de datos una vez que se otorga el consentimiento.
Solicitar permisos push
En lugar de llamar arequestPermission() inmediatamente al abrir la aplicación, adopte un enfoque más estratégico. Use un mensaje in-app para explicar el valor de las notificaciones push antes de solicitar permiso.
Para mejores prácticas y detalles de implementación, consulte nuestra guía Solicitar permisos push.
Escuchar eventos push, de usuario e in-app
Use los oyentes del SDK para reaccionar a las acciones del usuario y cambios de estado. El SDK proporciona varios oyentes de eventos a los que puede conectarse. Consulte nuestra guía de referencia del SDK para obtener más detalles.Eventos de notificación push
addClickListener(): Detecte cuándo se toca una notificación. Útil para enlaces profundos.addForegroundLifecycleListener(): Controle cómo se comportan las notificaciones en primer plano.
Cambios de estado del usuario
addObserver()para estado del usuario: Detecte cuándo se establece el ID externo.addPermissionObserver(): Rastree la interacción específica del usuario con el mensaje de permiso push nativo.addObserver()para suscripción push: Rastree cuándo cambia el estado de la suscripción push.
Eventos de mensajes in-app
addClickListener(): Maneje acciones de clic in-app. Ideal para enlaces profundos o seguimiento de eventos.addLifecycleListener(): Rastree el ciclo de vida completo de los mensajes in-app (mostrados, clicados, descartados, etc.).
Configuración y capacidades avanzadas
Explore más capacidades para mejorar su integración:- 🔁 Migración a OneSignal desde otro servicio
- 🌍 Seguimiento de ubicación
- 🔗 Enlaces profundos
- 🔌 Integraciones
- 🧩 Extensiones de servicio móvil
- 🛎️ Botones de acción
- 🌐 Mensajería multiidioma
- 🛡️ Verificación de identidad
- 📊 Resultados personalizados
- 📲 Actividades en vivo
Configuración y referencia del SDK móvil
Asegúrese de haber habilitado todas las características clave revisando la guía de configuración de push móvil. Para obtener detalles completos sobre los métodos disponibles y opciones de configuración, visite la referencia del SDK móvil.Privacidad y consentimiento del usuario
Si tu app requiere el consentimiento del usuario antes de recopilar datos (p. ej., para el cumplimiento del RGPD), puedes retrasar la recopilación de datos de OneSignal hasta que se otorgue el consentimiento. Llama asetConsentRequired antes de initialize.
setConsentGiven(true) una vez que el usuario acepte. Consulta Manejo de datos personales para más detalles.Solución de problemas
support@onesignal.comPor favor incluya:- Detalles del problema que está experimentando y pasos para reproducir si están disponibles
- Su ID de aplicación de OneSignal
- El ID externo o ID de suscripción si corresponde
- La URL del mensaje que probó en el panel de OneSignal si corresponde
- Cualquier registro o mensaje de error relevante