Skip to main content
¿Usas un asistente de programación con IA? Usa este prompt para una instalación asistida por IA:
Limitación de Expo Go: Las notificaciones push no funcionan en Expo Go. Debes crear un development build para probar las funciones de OneSignal.

Requisitos

Requisitos iOS
  • 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+
Requisitos Android
  • 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).
Si su organización ya tiene una cuenta de OneSignal, solicite ser invitado a la Organización. De lo contrario, regístrese para obtener una cuenta gratuita para comenzar.
1

Cree o seleccione su aplicación

Cree una nueva aplicación haciendo clic en Nueva aplicación/sitio web, o agregue una plataforma a una aplicación existente en Configuración > Push e In-App. Seleccione la(s) plataforma(s) que desea configurar y haga clic en Siguiente: Configure su plataforma.
Panel de OneSignal que muestra el flujo de configuración de nueva aplicación con nombre de organización, nombre de app y selección de canal

Configuración de su primera aplicación, organización y canal de OneSignal.

2

Configure las credenciales de plataforma

Ingrese las credenciales para su plataforma:Haga clic en Guardar y continuar después de ingresar sus credenciales.
3

Guarde su ID de aplicación e instale el SDK

Su ID de aplicación se muestra en la pantalla final. Cópielo y guárdelo — lo necesita al inicializar el SDK. Seleccione su plataforma de SDK y siga la guía de configuración.
Panel de OneSignal que muestra el ID de aplicación y la opción de invitar al equipo después de la configuración

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.
npm
Agrega el paquete react-native-onesignal a tu proyecto.

2. Configurar el plugin

Abre tu app.json (o app.config.js / app.config.ts). Debes incluir las siguientes configuraciones. Configuraciones requeridas
string
requerido
El identificador de paquete de tu app. Debe coincidir con la autenticación p8 o p12 configurada en tu app de OneSignal.
object
requerido
Debe incluir la clave UIBackgroundModes establecida en ["remote-notification"].
object
requerido
Derechos (entitlements) de iOS requeridos para notificaciones push.
  • Establece aps-environment en "development" para pruebas y "production" para compilaciones de TestFlight y App Store.
Asegúrate de agregar el plugin [onesignal-expo-plugin] al frente del array de plugins. Debe ser el primer plugin en el array. Hacerlo evitará el error OneSignal/OneSignal.h file not found.

Opcional: Deshabilitar el módulo de ubicación

Si tu app no usa OneSignal.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.
Si tu 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.
A partir de onesignal-expo-plugin 2.6.0, puedes importar withOneSignal para obtener soporte completo de TypeScript y autocompletado en las props del plugin.
app.config.ts

3. Inicializar SDK

Dependiendo de tu estructura Expo (entrada de App tradicional o Expo Router), inicializa OneSignal siguiendo estas opciones.
En tu archivo 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.
Si no tienes acceso a la app de OneSignal, pide a tus Miembros del Equipo que te inviten.
App.tsx
Listeners reutilizables con 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.
Revisa nuestro repositorio GitHub del Plugin Expo de OneSignal para opciones de configuración adicionales, instrucciones de configuración más complejas o abre un issue. ¡Nuestros SDKs son de código abierto y damos la bienvenida a PRs!

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.
Después de confirmar que su compilación de Android funciona:

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.
Esto debe usar las mismas credenciales configuradas en tu configuración EAS.

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

Puedes ver este error al compilar con Xcode 15+, debido a un cambio de configuración predeterminado que afecta sistemas multiplataforma.
  1. Abre tu carpeta .xcworkspace en Xcode y navega a tu objetivo de app > Build Phases.
  2. Deberías tener una fase llamada “Embed Foundation Extensions” o “Embed App Extensions”.
  3. Arrastra y mueve esta fase de compilación a arriba de “Run Script”.
  4. Compila y ejecuta tu app. El error debería estar resuelto.

Orden correcto de Build Phases en Xcode.

Desmarca Copy only when installing.

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

Error de ruta para PBXGroup.


Convertir carpeta a grupo.

Después de confirmar que tu compilación iOS funciona, continúa con Probar la integración del SDK de OneSignal.

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.
Si está probando con un emulador de Android, debe iniciarse con un arranque en frío.
  1. Vaya a Administrador de dispositivos en Android Studio.
  2. Seleccione su dispositivo emulador y haga clic en Editar.
  3. Vaya a Configuración adicional o Más.
  4. Establezca la Opción de arranque en Arranque en frío.
  5. Guarde los cambios y reinicie el emulador.

Verificar suscripciones móviles

1

Inicie su aplicación en un dispositivo de prueba.

El mensaje de permiso push nativo debe aparecer automáticamente si agregó el método requestPermission durante la inicialización.

Mensajes de permiso push de iOS y Android

2

Verifique su panel de OneSignal

Antes de aceptar el mensaje, verifique el 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'

3

Regrese a la aplicación y toque Permitir en el mensaje.

4

Actualice la página de suscripciones del panel de OneSignal.

El estado de la suscripción ahora debería mostrar Suscrito.

Panel mostrando suscripción con estado 'Suscrito'

Ha creado exitosamente una suscripción móvil. Las suscripciones móviles se crean cuando los usuarios abren su aplicación por primera vez en un dispositivo o si desinstalan y reinstalan su aplicación en el mismo dispositivo.

Configurar suscripciones de prueba

Las suscripciones de prueba son útiles para probar una notificación push antes de enviar un mensaje.
1

Agregar a suscripciones de prueba.

En el panel, junto a la suscripción, haga clic en el botón Opciones (tres puntos) y seleccione Agregar a suscripciones de prueba.

Agregando un dispositivo a suscripciones de prueba

2

Nombre su suscripción.

Nombre la suscripción para que pueda identificar fácilmente su dispositivo más tarde en la pestaña de suscripciones de prueba.
3

Cree un segmento de usuarios de prueba.

Vaya a Audiencia > Segmentos > Nuevo segmento.
4

Nombre el segmento.

Nombre el segmento Test Users (el nombre es importante porque se usará más adelante).
5

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

Ha creado exitosamente un segmento de usuarios de prueba. Ahora podemos probar el envío de mensajes a este dispositivo individual y grupos de usuarios de prueba.

Enviar push de prueba mediante API

1

Obtenga su clave API de aplicación e ID de aplicación.

En su panel de OneSignal, vaya a Configuración > Claves e IDs.
2

Actualice el código proporcionado.

Reemplace 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.
3

Ejecute el código.

Ejecute el código en su terminal.
4

Verifique imágenes y entrega confirmada.

Si todos los pasos de configuración se completaron exitosamente, las suscripciones de prueba deberían recibir una notificación con una imagen incluida:

Notificación push con imagen en iOS y Android

Las imágenes aparecerán pequeñas en la vista de notificación colapsada. Expanda la notificación para ver la imagen completa.
5

Verifique la entrega confirmada.

En su panel, vaya a Entrega > Mensajes enviados, luego haga clic en el mensaje para ver las estadísticas.Debería ver la estadística confirmado, lo que significa que el dispositivo recibió el push.
Ha enviado exitosamente una notificación mediante nuestra API a un segmento.
  • ¿No recibió la imagen? Es posible que falte su extensión de servicio de notificaciones.
  • ¿No hay entrega confirmada? Revise la guía de solución de problemas aquí.
  • ¿Tiene problemas? Copie y pegue la solicitud de API y un registro desde el inicio hasta el final del lanzamiento de la aplicación en un archivo .txt. Luego comparta ambos con support@onesignal.com.

Enviar un mensaje in-app

Los mensajes in-app le permiten comunicarse con los usuarios mientras están usando su aplicación.
1

Cierre o ponga en segundo plano su aplicación en el dispositivo.

Esto se debe a que los usuarios deben cumplir con los criterios de audiencia in-app antes de que comience una nueva sesión. En OneSignal, una nueva sesión comienza cuando el usuario abre su aplicación después de que ha estado en segundo plano o cerrada durante al menos 30 segundos. Para obtener más detalles, consulte nuestra guía sobre cómo se muestran los mensajes in-app.
2

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

3

Personalice el contenido del mensaje si lo desea.

Ejemplo de personalización del mensaje de bienvenida in-app

4

Establezca el activador en 'Al abrir la aplicación'.

5

Programe la frecuencia.

En Programar > ¿Con qué frecuencia desea mostrar este mensaje? seleccione Cada vez que se cumplan las condiciones de activación.

Opciones de programación de mensajes in-app

6

Active el mensaje.

Haga clic en Activar mensaje para que esté disponible para sus usuarios de prueba cada vez que abran la aplicación.
7

Abra la aplicación y vea el mensaje.

Después de que el mensaje in-app esté activo, abra su aplicación. Debería verlo mostrarse:

Mensaje de bienvenida in-app mostrado en dispositivos

¿No ve el mensaje?
  • Inicie una nueva sesión
    • Debe cerrar o poner en segundo plano la aplicación durante al menos 30 segundos antes de volver a abrirla. Esto asegura que se inicie una nueva sesión.
    • Para obtener más información, consulte cómo se muestran los mensajes in-app.
  • ¿Sigue en el segmento de usuarios de prueba?
    • Si reinstaló o cambió de dispositivo, vuelva a agregar el dispositivo a suscripciones de prueba y confirme que forma parte del segmento de usuarios de prueba.
  • ¿Tiene problemas?
    • Siga Obtener un registro de depuración mientras reproduce los pasos anteriores. Esto generará un registro adicional que puede compartir con support@onesignal.com y le ayudaremos a investigar qué está sucediendo.
Ha configurado exitosamente el SDK de OneSignal y aprendió conceptos importantes como:Continúe con esta guía para identificar usuarios en su aplicación y configurar características adicionales.

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étodo login de nuestro SDK cada vez que sean identificados por su aplicación.
OneSignal genera IDs únicos de solo lectura para suscripciones (ID de suscripción) y usuarios (ID de OneSignal).A medida que los usuarios descargan su aplicación en diferentes dispositivos, se suscriben a su sitio web y/o le proporcionan direcciones de correo electrónico y números de teléfono fuera de su aplicación, se crearán nuevas suscripciones.Configurar el ID externo mediante nuestro SDK es altamente recomendado para identificar usuarios en todas sus suscripciones, independientemente de cómo se creen.

Agregar etiquetas de datos

Las etiquetas son pares clave-valor de datos de cadena que puede usar para almacenar propiedades de usuario (como username, 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"

Podemos crear un segmento de usuarios que tengan un nivel entre 5 y 10, y usar eso para enviar mensajes dirigidos y personalizados:

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. Si la dirección de correo electrónico y/o el número de teléfono ya existen en la aplicación de OneSignal, el SDK lo agregará al usuario existente, no creará duplicados. Puede ver usuarios unificados a través de Audiencia > Usuarios en el panel o con la API de ver usuario.

Un perfil de usuario con suscripciones push, email y SMS unificadas por ID externo

Mejores prácticas para la comunicación multicanal
  • 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: Consulte nuestra documentación de privacidad y seguridad para obtener más información sobre:

Solicitar permisos push

En lugar de llamar a requestPermission() 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

Para personalización completa, consulte extensiones de servicio móvil.

Cambios de estado del usuario

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:

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.
¡Felicitaciones! Ha completado exitosamente la guía de configuración 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 a setConsentRequired antes de initialize.
Cuando el consentimiento es requerido pero aún no se ha otorgado, el SDK se inicializa pero no envía ningún dato a OneSignal. Llama a setConsentGiven(true) una vez que el usuario acepte. Consulta Manejo de datos personales para más detalles.

Solución de problemas

¿Necesita ayuda?Chatee con nuestro equipo de Soporte o envíe un correo electrónico a 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
¡Estamos felices de ayudar!