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.Pasos para configurar su aplicación de OneSignal.
Pasos para configurar su aplicación de OneSignal.
- Inicie sesión en https://onesignal.com y cree o seleccione su aplicación.
- Navegue a Settings > Push & In-App.
- Seleccione Google Android (FCM) y haga clic en Continue para avanzar por el asistente de configuración.
- Suba su JSON de FCM Service Account.
- Continúe por el asistente de configuración para obtener su App ID. Este se usará para inicializar el SDK.
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
Paso 1. Agregue el SDK de OneSignal
- En Android Studio, abra su archivo
build.gradle.kts (Module: app)obuild.gradle (Module: app) - Agregue OneSignal a su sección
dependencies:

El ejemplo muestra cómo agregar OneSignal al archivo build.gradle.kts de su aplicación.
- Sincronice Gradle: Haga clic en Sync Now en el banner que aparece o vaya a File > Sync Project with Gradle Files
Paso 2. Cree y configure la clase Application
Es una práctica recomendada inicializar OneSignal en el métodoonCreate 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:
- File > New > Kotlin Class/File (o Java Class)
- Nombre:
ApplicationClass(o el nombre que prefiera)

El ejemplo muestra la creación de una nueva clase Kotlin llamada ApplicationClass.
YOUR_APP_ID con su App ID real de OneSignal desde el Dashboard > Settings > Keys & IDs.

Ejemplo del archivo ApplicationClass.kt.
- Abra el archivo
AndroidManifest.xmlde su aplicación - En su etiqueta
<application>agregueandroid:name=".ApplicationClass"(reemplace.ApplicationClasscon el nombre real de su clase si lo configuró de manera diferente).

AndroidManifest.xml con el nombre .ApplicationClass.
Paso 3. Configure los iconos de notificación predeterminados (recomendado)
Reemplace el icono de campana predeterminado con un icono pequeño llamadoic_stat_onesignal_default. Use una silueta monocromática sobre fondo transparente, o Android renderizará un cuadrado blanco.
- Genere las densidades con Android Asset Studio.
- Coloque
ic_stat_onesignal_defaulten cada carpeta de densidad: desderes/drawable-mdpi/(24×24) hastares/drawable-xxxhdpi/(96×96).
Paso 4. Pruebe la integración
Verifique la creación de la Suscripción:- Inicie la aplicación en un dispositivo o emulador con Google Play Services.
- Verifique en Dashboard > Audience > Subscriptions. El estado muestra Never Subscribed.
- Acepte el aviso de permisos cuando aparezca.
- Actualice el panel. El estado cambia a Subscribed.

Aviso de permisos de push en Android

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'
Cree un usuario de prueba y un segmento
- Junto a la Suscripción, seleccione Options > Add as test user e ingrese un nombre.
- Vaya a Audience > Segments > New Segment.
- Nombre:
Test Users, agregue el filtro Test Users > Create Segment.

Agregue un usuario de prueba

Cree un segmento 'Test Users' con el filtro Test Users
Envíe una notificación push de prueba vía API
- Navegue a Settings > Keys & IDs.
- En el código proporcionado, reemplace
YOUR_APP_API_KEYyYOUR_APP_IDen el código a continuación con sus claves reales. Este código utiliza el segmentoTest Usersque creamos anteriormente.

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)
Pruebe los mensajes dentro de la aplicación
- Cierre la aplicación durante más de 30 segundos
- Panel > Messages > In-App > New In-App > seleccione la plantilla Welcome
- Audiencia: segmento Test Users
- Disparador: On app open
- Programación: Every time trigger conditions are satisfied
- Haga clic en Make Message Live
- Abra 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

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

Mensaje de bienvenida dentro de la aplicación mostrado en dispositivos
- Recopilar Suscripciones, configurar Usuarios de prueba y crear Segmentos.
- Enviar Push con imágenes usando Segmentos y nuestra API de Crear mensaje.
- Enviar Mensajes dentro de la aplicación.
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.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 dekey-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.
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 alogin() 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
- 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 aconsentRequired antes de initWithContext.
Solicitar permisos de push
En lugar de llamar arequestPermission() 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 deOneSignal.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
- Canales de notificación: Organice las notificaciones en categorías (Android 8.0+)
- Extensiones de servicio: Personalización avanzada de notificaciones
- Huawei/HMS: Alternativa a Google Play Services
Funciones universales
- Deep linking: Navegue a los usuarios a pantallas específicas desde las notificaciones
- Botones de acción: Agregue botones interactivos a las notificaciones
- Verificación de identidad: Identificación segura de usuarios
- Seguimiento de ubicación: Segmentación basada en ubicación
- Integraciones: Conecte con plataformas de análisis y datos
- Mensajería multilingüe: Notificaciones localizadas
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. Agregueandroid: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. Agregueic_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?
ConfigureOneSignal.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.
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