Skip to main content
Esta guía le explica cómo agregar OneSignal a su aplicación Android usando Android Studio. Instalará nuestro SDK, configurará notificaciones push y mensajes dentro de la aplicación, y enviará mensajes de prueba para confirmar que todo funciona correctamente. Si es la primera vez que usa OneSignal, siga los pasos en orden. Si ya tiene experiencia, puede ir directamente a las secciones que necesite.
¿Usa un asistente de programación con IA? Para una instalación asistida por IA, use este prompt:

Paso 0. Configure FCM en OneSignal (requerido para entregar push)

Puede instalar e inicializar el SDK de Android de OneSignal sin completar este paso. Sin embargo, las notificaciones push no se entregarán hasta que las credenciales de Firebase Cloud Messaging (FCM) estén configuradas en su aplicación de OneSignal.
Si su empresa ya tiene una cuenta de OneSignal, solicite ser invitado con rol de administrador para configurar la aplicación. De lo contrario, regístrese para una cuenta gratuita para comenzar.
Estos pasos conectan su aplicación de OneSignal con Firebase Cloud Messaging (FCM). Solo necesita hacer esto una vez por aplicación.
  1. Inicie sesión en https://onesignal.com y cree o seleccione su aplicación.
  2. Navegue a Settings > Push & In-App.
  3. Seleccione Google Android (FCM) y haga clic en Continue para avanzar por el asistente de configuración.
  4. Suba su JSON de FCM Service Account.
  5. Continúe por el asistente de configuración para obtener su App ID. Este se usará para inicializar el SDK.
Para instrucciones completas de configuración, consulte nuestra guía de Configuración de push móvil.

Contrato de configuración y requisitos

Esta sección resume las herramientas, versiones y supuestos utilizados a lo largo de la guía.
  • Versión del SDK: 5.6.1+ (última versión: consulte los lanzamientos)
  • Instrucciones de configuración con IA: https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md
  • Repositorio del SDK: https://github.com/OneSignal/OneSignal-Android-SDK
  • Android Studio: Meerkat | 2024.3.1+
  • API de Android: 23+ mínimo (Android 6.0+), 31+ recomendado (Android 12+)
  • Dispositivo/emulador: Android 7.0+ con Google Play Services instalado
  • Dependencia requerida: com.onesignal:OneSignal:[5.6.1, 5.99.99]
  • Clase Application: Requerida para la inicialización correcta del SDK
  • Formato del App ID: UUID de 36 caracteres (ejemplo: 12345678-1234-1234-1234-123456789012). Se encuentra en Dashboard > Settings > Keys & IDs.
  • Inicialización: OneSignal.initWithContext(this, "YOUR_APP_ID")
  • Optimización de batería: Puede afectar las notificaciones en segundo plano
  • Recomendado: Asigne un External ID mediante OneSignal.login("user_id") para unificar usuarios entre dispositivos

Pasos de configuración de Android

Al finalizar los pasos a continuación, usted tendrá:
  • El SDK de OneSignal instalado e inicializado en su aplicación Android
  • La solicitud de permisos de notificaciones push funcionando correctamente en un dispositivo real
  • Una notificación push de prueba y un mensaje dentro de la aplicación entregados exitosamente
Si omitió el Paso 0 (Configurar FCM en OneSignal), aún puede completar la configuración de Android Studio a continuación. Complete el Paso 0 antes de probar o enviar notificaciones push.

Paso 1. Agregue el SDK de OneSignal

  1. En Android Studio, abra su archivo build.gradle.kts (Module: app) o build.gradle (Module: app)
  2. Agregue OneSignal a su sección dependencies:
build.gradle.kts de la app en Android Studio con la dependencia implementation de OneSignal agregada

El ejemplo muestra cómo agregar OneSignal al archivo build.gradle.kts de su aplicación.

  1. Sincronice Gradle: Haga clic en Sync Now en el banner que aparece o vaya a File > Sync Project with Gradle Files
Verifique que la sincronización de Gradle se complete exitosamente sin conflictos de dependencias.

Paso 2. Cree y configure la clase Application

Es una práctica recomendada inicializar OneSignal en el método onCreate de su clase Application para asegurar la configuración correcta del SDK en todos los puntos de entrada. Cree una clase Application si aún no tiene una:
  1. File > New > Kotlin Class/File (o Java Class)
  2. Nombre: ApplicationClass (o el nombre que prefiera)
Diálogo New Kotlin Class de Android Studio con ApplicationClass como nombre

El ejemplo muestra la creación de una nueva clase Kotlin llamada ApplicationClass.

Agregue el siguiente código de OneSignal a la clase Application. Reemplace YOUR_APP_ID con su App ID real de OneSignal desde el Dashboard > Settings > Keys & IDs.
ApplicationClass.kt en Android Studio mostrando initWithContext y requestPermission de OneSignal

Ejemplo del archivo ApplicationClass.kt.

No se recomienda inicializar en una Activity (como MainActivity) porque puede no ser llamada en arranques en frío de la aplicación desde deep links o notificaciones. Siempre inicialice OneSignal en su clase Application para mayor confiabilidad.
Registre la clase Application:
  1. Abra el archivo AndroidManifest.xml de su aplicación
  2. En su etiqueta <application> agregue android:name=".ApplicationClass" (reemplace .ApplicationClass con el nombre real de su clase si lo configuró de manera diferente).
AndroidManifest.xml
Revise su etiqueta <application> en busca de tools:node="replace". Ese marcador elimina los componentes fusionados de las librerías, incluida la PermissionsActivity de OneSignal. El flujo de permiso de notificaciones entonces falla con ActivityNotFoundException. Quite tools:node="replace". Si solo necesita sobrescribir un atributo, use tools:replace="android:theme" (o el atributo que esté cambiando).
Etiqueta application de AndroidManifest.xml con android:name configurado a .ApplicationClass

AndroidManifest.xml con el nombre .ApplicationClass.

Verifique que la aplicación se compile y ejecute sin errores.

Paso 3. Configure los iconos de notificación predeterminados (recomendado)

Reemplace el icono de campana predeterminado con un icono pequeño llamado ic_stat_onesignal_default. Use una silueta monocromática sobre fondo transparente, o Android renderizará un cuadrado blanco.
  1. Genere las densidades con Android Asset Studio.
  2. Coloque ic_stat_onesignal_default en cada carpeta de densidad: desde res/drawable-mdpi/ (24×24) hasta res/drawable-xxxhdpi/ (96×96).
Consulte Iconos de notificación para iconos grandes, color de acento y el comportamiento del icono de lanzador en Android 17.

Paso 4. Pruebe la integración

Verifique la creación de la Suscripción:
  1. Inicie la aplicación en un dispositivo o emulador con Google Play Services.
  2. Verifique en Dashboard > Audience > Subscriptions. El estado muestra Never Subscribed.
  3. Acepte el aviso de permisos cuando aparezca.
  4. Actualice el panel. El estado cambia a Subscribed.
Aviso de permisos de push en Android solicitando permitir notificaciones

Aviso de permisos de push en Android

Panel mostrando la Suscripción con estado 'Never Subscribed'.

Panel mostrando la Suscripción con estado 'Never Subscribed'

Después de permitir los permisos de push, actualice el panel para ver el estado de la Suscripción actualizado a 'Subscribed'.

Después de permitir los permisos de push, actualice el panel para ver el estado de la Suscripción actualizado a 'Subscribed'

Una Suscripción móvil se crea cuando el usuario abre su aplicación por primera vez en un dispositivo, o si la desinstala y reinstala en el mismo dispositivo. Después de que acepte el aviso de permisos, el estado en el panel debería mostrar Subscribed.

Cree un usuario de prueba y un segmento

  1. Junto a la Suscripción, seleccione Options > Add as test user e ingrese un nombre.
  2. Vaya a Audience > Segments > New Segment.
  3. Nombre: Test Users, agregue el filtro Test Users > Create Segment.
Menú Options en un registro de suscripción con Add as test user resaltado

Agregue un usuario de prueba

Cree un segmento 'Test Users' con el filtro Test Users.

Cree un segmento 'Test Users' con el filtro Test Users

Ahora puede enviar mensajes de prueba a este dispositivo y al segmento Test Users.

Envíe una notificación push de prueba vía API

  1. Navegue a Settings > Keys & IDs.
  2. En 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 utiliza el segmento Test Users que creamos anteriormente.
Las imágenes en las notificaciones push aparecen pequeñas en la vista de notificación contraída. Expanda la notificación para ver la imagen completa.

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

Estadísticas de entrega mostrando recepción confirmada (no disponible en planes gratuitos).

Estadísticas de entrega mostrando recepción confirmada (no disponible en planes gratuitos)

Confirme que el dispositivo de prueba recibió una notificación con su icono personalizado (si fue configurado) y la imagen grande al expandirla. En los planes de pago, Dashboard > Delivery > Sent Messages puede mostrar la recepción confirmada.
  • ¿No recibió la notificación? Consulte Push móvil no mostrado.
  • ¿No aparece el icono personalizado? Verifique que el nombre del icono sea ic_stat_onesignal_default y que esté en las carpetas drawable correctas.
  • ¿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.

Pruebe los mensajes dentro de la aplicación

  1. Cierre la aplicación durante más de 30 segundos
  2. Panel > Messages > In-App > New In-App > seleccione la plantilla Welcome
  3. Audiencia: segmento Test Users
  4. Disparador: On app open
  5. Programación: Every time trigger conditions are satisfied
  6. Haga clic en Make Message Live
  7. Abra la aplicación
Segmentando el segmento 'Test Users' con un mensaje dentro de la aplicación.

Segmentando el segmento 'Test Users' con un mensaje dentro de la aplicación

Ejemplo de personalización del mensaje de bienvenida dentro de la aplicación.

Ejemplo de personalización del mensaje de bienvenida dentro de la aplicación

Opciones de programación de mensajes dentro de la aplicación.

Opciones de programación de mensajes dentro de la aplicación

Mensaje de bienvenida dentro de la aplicación mostrado en dispositivos.

Mensaje de bienvenida dentro de la aplicación mostrado en dispositivos

El dispositivo de prueba debería mostrar el mensaje de bienvenida dentro de la aplicación. Consulte Configuración de mensajes dentro de la aplicación para más detalles.
¿No ve el mensaje?
  • Inicie una nueva sesión
    • Fuerce el cierre y vuelva a abrir la aplicación, o ciérrela/envíela a segundo plano durante al menos 30 segundos antes de volver a abrirla. Cualquiera de las dos opciones asegura que se inicie una nueva sesión. Consulte Sesiones.
    • Para más información, consulte cómo se muestran los mensajes dentro de la aplicación.
  • ¿Sigue en el segmento Test Users?
    • Si reinstaló o cambió de dispositivo, vuelva a agregar el dispositivo a Usuarios de prueba y confirme que forma parte del segmento Test Users.
  • ¿Tiene problemas?
    • Siga la guía Obtener un registro de depuración mientras reproduce los pasos anteriores. Esto generará registros adicionales que puede compartir con support@onesignal.com y le ayudaremos a investigar lo que está sucediendo.
Ahora tiene Suscripciones, Usuarios de prueba y un Segmento. Envió push con una imagen a través de la API de Crear mensaje y un mensaje dentro de la aplicación. Continúe a continuación para identificar usuarios y agregar más funciones.
Ha configurado exitosamente el SDK de OneSignal y aprendido conceptos importantes como:Continúe con esta guía para identificar usuarios en su aplicación y configurar funciones adicionales.

Errores comunes y soluciones

Gestión de usuarios

Anteriormente, demostramos cómo crear Suscripciones móviles. Ahora expandiremos a la identificación de Usuarios a través de todas sus Suscripciones (incluyendo push, correo electrónico y SMS) usando el SDK de OneSignal.

Asigne un External ID (recomendado)

Use un External ID para identificar usuarios de manera consistente entre dispositivos, direcciones de correo electrónico y números de teléfono usando el identificador de usuario de su backend. Esto mantiene la mensajería unificada entre canales y sistemas de terceros.
OneSignal genera IDs únicos de solo lectura para las Suscripciones (Subscription ID) y los Usuarios (OneSignal ID).Se recomienda encarecidamente configurar el External ID a través de nuestro SDK para identificar usuarios en todas sus suscripciones, independientemente de cómo se hayan creado.Obtenga más información sobre el método login en la referencia del SDK.

Agregue Tags y Custom Events

Los Tags y Custom Events agregan datos a los usuarios. Los Tags son cadenas de key-value para propiedades del usuario (como username, role o status). Los Custom Events usan JSON y generalmente representan acciones (como new_purchase o abandoned_cart). Ambos pueden potenciar la Personalización de mensajes y Journeys.
Consulte Tags y Custom Events para más detalles.

Agregue suscripciones de correo electrónico y/o SMS

Puede llegar a los usuarios a través de correo electrónico y SMS además de push. Si la dirección de correo electrónico o el número de teléfono ya existen en la aplicación de OneSignal, el SDK los agrega al usuario existente y no crea duplicados. Llame primero a login() para que la dirección se adjunte al usuario identificado.
Un perfil de usuario con suscripciones de push, correo electrónico y SMS unificadas por External ID.

Un perfil de usuario con suscripciones de push, correo electrónico y SMS unificadas por External ID

Mejores prácticas para la comunicación multicanal
  • Obtenga consentimiento explícito antes de agregar suscripciones de correo electrónico 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 del usuario, use los métodos de control de consentimiento del SDK. Llame a consentRequired antes de initWithContext.

Solicitar permisos de push

En lugar de llamar a requestPermission() inmediatamente al abrir la aplicación, adopte un enfoque más estratégico. Use un mensaje dentro de la aplicación para explicar el valor de las notificaciones push antes de solicitar el permiso. Para mejores prácticas y detalles de implementación, consulte nuestra guía de Solicitar permisos de push.

Escuchar eventos de push, usuario y mensajes dentro de la aplicación

Use los listeners del SDK para reaccionar a las acciones del usuario y cambios de estado. Agréguelos en su clase Application después de OneSignal.initWithContext().

Eventos de notificaciones push

Cambios de estado del usuario

Este ejemplo usa el observador de suscripción push. El observador de estado del usuario y el observador de permisos de notificación están en la Referencia del SDK móvil.

Eventos de mensajes dentro de la aplicación

Los métodos adicionales de mensajes dentro de la aplicación están en la Referencia del SDK móvil.

Configuración avanzada y capacidades

Funciones específicas de Android

Funciones universales

Para la documentación completa de los métodos del SDK, consulte la Referencia del SDK móvil.

Preguntas frecuentes

¿Por qué Android Studio no puede resolver OneSignal?

Falta la dependencia del SDK o Gradle no se ha sincronizado. Agregue com.onesignal:OneSignal:[5.6.1, 5.99.99] al build.gradle de su módulo de aplicación y use File > Sync Project with Gradle Files.

¿Por qué no se encuentra mi clase Application?

La clase no está registrada en el manifiesto. Agregue android:name=".ApplicationClass" (o el nombre de su clase) a la etiqueta <application> en AndroidManifest.xml.

¿Por qué el emulador dice que Google Play Services no está disponible?

La imagen del emulador no incluye Play Services. Use un dispositivo con Play Store, o una imagen de sistema de emulador que incluya Google APIs.

¿Por qué la notificación muestra el icono predeterminado de Android?

El icono pequeño falta o tiene un nombre incorrecto. Agregue ic_stat_onesignal_default a cada carpeta de densidad res/drawable-*. Consulte Iconos de notificación.

¿Por qué mi dispositivo de prueba no recibió una notificación push?

Las credenciales de FCM no están configuradas, o el dispositivo no está suscrito. Complete el Paso 0 y confirme que el estado de la Suscripción sea Subscribed. Luego consulte Push móvil no mostrado.

¿Por qué no se muestran los mensajes dentro de la aplicación?

Los mensajes dentro de la aplicación requieren una nueva sesión. Fuerce el cierre de la aplicación, o envíela a segundo plano durante al menos 30 segundos, y luego vuelva a abrirla. Confirme que el dispositivo sigue en el segmento Test Users. Consulte Sesiones y cómo se muestran los mensajes dentro de la aplicación.

¿Qué causa Manifest merger failed?

Valores de android:name de <application> en conflicto o permisos duplicados. Busque en su manifiesto fusionado una segunda clase Application y mantenga un único android:name.

¿Por qué las optimizaciones de batería bloquean las notificaciones?

Algunos fabricantes (OEM) restringen el trabajo en segundo plano. Pida a los usuarios que deshabiliten la optimización de batería para su aplicación si las notificaciones dejan de llegar después de que el dispositivo entra en reposo.

¿Cómo obtengo más información de registro?

Configure OneSignal.Debug.logLevel = LogLevel.VERBOSE (Kotlin) o OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE) (Java), reproduzca el problema y capture logcat. Consulte Obtener un registro de depuración.
¿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!