> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuración del SDK de Android
> Agregue notificaciones push y mensajes dentro de la aplicación a su app Android usando el SDK de Android de OneSignal.
export const SdkReleasesIframe = ({sdkFilter = undefined, viewMode = undefined, height, ...frameProps}) => {
const baseUrl = 'https://onesignal.github.io/sdk-releases';
const buildUrl = (theme, sdkFilter, viewMode) => {
const url = new URL(baseUrl);
const params = new URLSearchParams();
if (theme) {
params.set('theme', theme);
}
if (sdkFilter) {
params.set('sdk', sdkFilter);
}
if (viewMode) {
params.set('viewMode', viewMode);
}
if (params.toString()) {
url.search = params.toString();
}
return url.toString();
};
const detectTheme = () => {
if (document.documentElement.classList.contains('dark')) {
return 'dark';
}
return 'light';
};
const [theme, setTheme] = useState('light');
const [iframeSrc, setIframeSrc] = useState(() => {
const initialTheme = detectTheme();
return buildUrl(initialTheme, sdkFilter, viewMode);
});
useEffect(() => {
const currentTheme = detectTheme();
setTheme(currentTheme);
setIframeSrc(buildUrl(currentTheme, sdkFilter, viewMode));
const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
const handleThemeChange = () => {
const newTheme = detectTheme();
setTheme(newTheme);
setIframeSrc(buildUrl(newTheme, sdkFilter, viewMode));
};
if (mediaQuery.addEventListener) {
mediaQuery.addEventListener('change', handleThemeChange);
} else {
mediaQuery.addListener(handleThemeChange);
}
window.addEventListener('storage', handleThemeChange);
const observer = new MutationObserver(handleThemeChange);
observer.observe(document.documentElement, {
attributes: true,
attributeFilter: ['class', 'data-theme']
});
return () => {
if (mediaQuery.removeEventListener) {
mediaQuery.removeEventListener('change', handleThemeChange);
} else {
mediaQuery.removeListener(handleThemeChange);
}
window.removeEventListener('storage', handleThemeChange);
observer.disconnect();
};
}, [sdkFilter, viewMode]);
const getIframeHeight = () => {
if (viewMode === 'table') {
return '450';
}
if (viewMode === 'mini') {
return '170';
}
return '800';
};
const iframeHeight = height || getIframeHeight();
return
;
};
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:
```
Integrate the OneSignal Android SDK into this codebase.
Follow the instructions at:
https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md
```
## Paso 0. Configure FCM en OneSignal (requerido para enviar 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](./manage-team-members) para configurar la aplicación. De lo contrario, [regístrese para una cuenta gratuita](https://onesignal.com) 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](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. Ingrese los detalles de su [Firebase Server Key o Service Account](./android-firebase-credentials).
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](./mobile-push-setup).
***
## 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](https://github.com/OneSignal/OneSignal-Android-SDK/releases))
* **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.2.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.9.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 el Panel de OneSignal > 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 habrá:
* Instalado e inicializado el SDK de OneSignal en su aplicación Android
* Configurado correctamente la solicitud de permisos de notificaciones push en un dispositivo real
* Entregado exitosamente una notificación push de prueba y un mensaje dentro de la aplicación
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`:
```kotlin app/build.gradle.kts theme={null}
implementation("com.onesignal:OneSignal:[5.6.1, 5.9.99]")
```
```groovy app/build.gradle theme={null}
implementation 'com.onesignal:OneSignal:[5.6.1, 5.9.99]'
```
3. **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)
**Agregue el siguiente código de OneSignal a la clase Application.**
Reemplace `YOUR_APP_ID` con su App ID real de OneSignal desde el Panel > Settings > [Keys & IDs](./keys-and-ids).
```kotlin ApplicationClass.kt theme={null}
// FILE: ApplicationClass.kt
// PURPOSE: Initialize OneSignal when your app launches
// REQUIREMENT: Must be registered in AndroidManifest.xml
package com.your.package.name // Replace with your actual package name
import android.app.Application
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import com.onesignal.OneSignal
import com.onesignal.debug.LogLevel
class ApplicationClass : Application() {
override fun onCreate() {
super.onCreate()
// Enable verbose logging to debug issues (remove in production)
OneSignal.Debug.logLevel = LogLevel.VERBOSE
// Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
OneSignal.initWithContext(this, "YOUR_APP_ID")
// Prompt user for push notification permission
// In production, consider using an in-app message instead for better opt-in rates
CoroutineScope(Dispatchers.IO).launch {
OneSignal.Notifications.requestPermission(false)
}
}
}
```
```java ApplicationClass.java theme={null}
// FILE: ApplicationClass.java
// PURPOSE: Initialize OneSignal when your app launches
// REQUIREMENT: Must be registered in AndroidManifest.xml
package com.your.package.name; // Replace with your actual package name
import android.app.Application;
import com.onesignal.Continue;
import com.onesignal.OneSignal;
import com.onesignal.debug.LogLevel;
public class ApplicationClass extends Application {
@Override
public void onCreate() {
super.onCreate();
// Enable verbose logging to debug issues (remove in production)
OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE);
// Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
OneSignal.initWithContext(this, "YOUR_APP_ID");
// Prompt user for push notification permission
// In production, consider using an in-app message instead for better opt-in rates
OneSignal.getNotifications().requestPermission(false, Continue.none());
}
}
```
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 `` agregue `android:name=".ApplicationClass"` (reemplace `.ApplicationClass` con el nombre real de su clase si lo configuró de manera diferente).
```xml AndroidManifest.xml theme={null}
```
Verifique que la aplicación se compile y ejecute sin errores.
### Paso 3. Configure los iconos de notificación predeterminados (recomendado)
Personalice los [iconos de notificación](./notification-icons) para que coincidan con la identidad visual de su aplicación. Este paso es opcional pero se recomienda para una apariencia profesional.
### 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 el Panel > **Audience > Subscriptions** — el estado muestra "Never Subscribed"
3. Acepte el aviso de permisos cuando aparezca
4. Actualice el panel — el estado cambia a "Subscribed"
Ha creado exitosamente una [Suscripción móvil](./subscriptions).
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.
#### Cree una Suscripción de prueba y un segmento
1. Haga clic en **⋮** junto a la Suscripción > **Add to Test Users** > asígnele un nombre
2. Vaya a **Audience > Segments > New Segment**
3. Nombre: `Test Users`, agregue el filtro **Test Users** > **Create Segment**
Ha creado exitosamente un segmento de usuarios de prueba.
Ahora podemos probar el envío de mensajes a este dispositivo individual y a grupos de usuarios de prueba.
#### Envíe una notificación push de prueba vía API
1. Navegue a **Settings > [Keys & IDs](./keys-and-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.
```bash theme={null}
curl -X POST 'https://api.onesignal.com/notifications' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Key YOUR_APP_API_KEY' \
-d '{
"app_id": "YOUR_APP_ID",
"target_channel": "push",
"name": "Testing basic setup",
"headings": { "en": "👋" },
"contents": {"en": "Hello world!"},
"included_segments": ["Test Users"],
"big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'
```
Verifique que el dispositivo de prueba recibió una notificación con:
* Su icono personalizado (si fue configurado)
* Imagen grande al expandir
* Panel > **Delivery > Sent Messages** muestra el estado "Confirmed" (no disponible en planes gratuitos).
* ¿No recibió la notificación? Consulte [Push móvil no mostrado](./notifications-show-successful-but-are-not-being-shown).
* ¿No aparece el icono personalizado? Verifique que el nombre del icono sea `onesignal_small_icon_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
Verifique que el dispositivo de prueba recibió un mensaje dentro de la aplicación. Consulte la guía de [Configuración de mensajes dentro de la aplicación](./in-app-messages-setup) para más detalles.
¿No ve el mensaje?
* Inicie una nueva sesión
* Debe cerrar o enviar la aplicación a segundo plano durante al menos 30 segundos antes de volver a abrirla. Esto asegura que se inicie una nueva sesión.
* Para más información, consulte [cómo se muestran los mensajes dentro de la aplicación](./in-app-messages-setup#how-are-iams-displayed%3F).
* ¿Sigue en el segmento `Test Users`?
* Si reinstaló o cambió de dispositivo, vuelva a agregar el dispositivo a [Suscripciones de prueba](./test-users) y confirme que forma parte del segmento Test Users.
* ¿Tiene problemas?
* Siga la guía [Obtener un registro de depuración](./capturing-a-debug-log) 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.
Ha configurado exitosamente el SDK de OneSignal y aprendido conceptos importantes como:
* Recopilar [Suscripciones](./subscriptions), configurar [Suscripciones de prueba](./test-users) y crear [Segmentos](./segmentation).
* Enviar [Push](./push) con imágenes usando Segmentos y nuestra API de [Crear mensaje](/reference/create-message).
* Enviar [Mensajes dentro de la aplicación](./in-app-messages-setup).
Continúe con esta guía para identificar usuarios en su aplicación y configurar funciones adicionales.
### Errores comunes y soluciones
| Error / Síntoma | Causa | Solución |
| ------------------------------------------------------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `Cannot resolve symbol 'OneSignal'` | Dependencia del SDK no agregada o Gradle no sincronizado | Agregue la dependencia a build.gradle y sincronice el proyecto |
| `Application class not found` | Clase Application no registrada en el manifiesto | Agregue `android:name=".ApplicationClass"` a la etiqueta `` |
| `Google Play Services not available` | Emulador/dispositivo sin Play Services | Use un dispositivo con Play Store o un emulador con Google APIs |
| Push recibido pero con icono predeterminado de Android | Icono personalizado no configurado o nombre incorrecto | Cree un recurso de icono de notificación llamado `onesignal_small_icon_default` |
| No se reciben notificaciones push | FCM no configurado en OneSignal | Complete el Paso 0: Configure las credenciales de FCM en el panel de OneSignal |
| Los mensajes dentro de la aplicación no se muestran | Sesión no iniciada o problemas de red | Cierre la aplicación más de 30 segundos, vuelva a abrir, verifique la conexión a internet |
| `Manifest merger failed` | Atributos del manifiesto en conflicto | Verifique si hay nombres de aplicación duplicados o conflictos de permisos |
| Optimización de batería bloqueando notificaciones | Gestión de energía del dispositivo | Guíe a los usuarios para deshabilitar la optimización de batería para su aplicación |
| No se puede diagnosticar el problema | Información de registro insuficiente | Agregue registro detallado y revise la salida de logcat en busca de errores |
***
## Gestión de usuarios
Anteriormente, demostramos cómo crear [Suscripciones](./subscriptions) móviles. Ahora expandiremos a la identificación de [Usuarios](./users) 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 asegura que sus mensajes se mantengan unificados entre canales y sistemas de terceros. Consulte nuestra [Referencia del SDK móvil](./mobile-sdk-reference) para más detalles y ejemplos de código en Java.
```kotlin Kotlin theme={null}
// Call when user logs in or is identified, safe to call multiple times
// Typically used in a login completion handler, or on app launch if already authenticated
fun onUserAuthenticated(userId: String) {
OneSignal.login(userId)
}
// If you want to remove the External ID from the Subscription, setting it to an anonymous user
fun onUserLoggedOut() {
OneSignal.logout()
}
```
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`](./mobile-sdk-reference#login-external-id) en la guía de referencia del SDK.
### Agregue Tags y Custom Events
Los Tags y Custom Events son formas de agregar datos a sus usuarios. Los Tags son cadenas de `key-value` y generalmente se asocian con propiedades del usuario (como `username`, `role` o `status`), mientras que los Custom Events tienen un formato JSON y generalmente se asocian con acciones (como `new_purchase`, `abandoned_cart` y propiedades asociadas). Ambos se pueden usar para potenciar la [Personalización de mensajes](./message-personalization) avanzada y Journeys. Consulte nuestra [Referencia del SDK móvil](./mobile-sdk-reference) para más detalles y ejemplos de código en Java.
```kotlin Kotlin theme={null}
// Add a tag when the user's name is set
OneSignal.User.addTag("username", "john_doe")
// Create a custom event when user abandoned a cart
val properties = mapOf(
"product_id" to "123456",
"product_name" to "Product Name",
"product_price" to 100,
"product_quantity" to 1
)
OneSignal.User.trackEvent("abandoned_cart", properties)
```
Más detalles sobre cómo usar Tags y Custom Events en las guías de [Tags](./add-user-data-tags) y [Custom Events](./custom-events).
### Agregue suscripciones de correo electrónico y/o SMS
Puede llegar a los usuarios a través de canales de correo electrónico y SMS además de las notificaciones push. 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. Consulte nuestra [Referencia del SDK móvil](./mobile-sdk-reference) para más detalles y ejemplos de código en Java.
```kotlin Kotlin theme={null}
// Add email subscription
// Call when user provides their email (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addEmail("user@example.com")
// Add SMS subscription
// Use E.164 format: + country code + number
// Call when user provides their phone number (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addSms("+15551234567")
```
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. Consulte nuestra [Referencia del SDK móvil](./mobile-sdk-reference) para más detalles y ejemplos de código en Java.
```kotlin Kotlin theme={null}
// In ApplicationClass onCreate(), BEFORE OneSignal.initWithContext()
// Use this if your app requires GDPR or other privacy consent before data collection
OneSignal.consentRequired = true
// Later, after user grants consent (e.g., taps "I Agree" on your consent screen)
OneSignal.consentGiven = true
```
Consulte nuestra documentación de Privacidad y seguridad para más información sobre:
* [Datos recopilados por el SDK](./data-collected-by-the-onesignal-sdk)
* [Manejo de datos personales](./handling-personal-data)
***
## 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](./prompt-for-push-permissions).
***
## 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
```kotlin Kotlin theme={null}
// Add click listener to handle when users tap notifications
val clickListener = object : INotificationClickListener {
override fun onClick(event: INotificationClickEvent) {
Log.d("OneSignal", "Notification clicked: ${event.notification.title}")
}
}
OneSignal.Notifications.addClickListener(clickListener)
```
### Cambios de estado del usuario
El ejemplo muestra cómo usar el observador de suscripción push. Otros eventos de estado del usuario como el observador de estado del usuario y el observador de permisos de notificación están disponibles en la [Referencia del SDK móvil](./mobile-sdk-reference).
```kotlin Kotlin theme={null}
// Add subscription observer to track push subscription changes
class MyObserver : IPushSubscriptionObserver {
init {
OneSignal.User.pushSubscription.addObserver(this)
}
override fun onPushSubscriptionChange(state: PushSubscriptionChangedState) {
if (state.current.optedIn) {
println("User is now opted-in with push token: ${state.current.token}")
}
}
}
```
### Eventos de mensajes dentro de la aplicación
Los métodos adicionales de mensajes dentro de la aplicación están disponibles en la [Referencia del SDK móvil](./mobile-sdk-reference).
```kotlin Kotlin theme={null}
// Add click listener for in-app message interactions
val clickListener = object : IInAppMessageClickListener {
override fun onClick(event: IInAppMessageClickEvent) {
print(event.result.actionId)
}
}
OneSignal.InAppMessages.addClickListener(clickListener)
```
***
## Configuración avanzada y capacidades
### Funciones específicas de Android
* **[Canales de notificación](./mobile-sdk-reference#notification-channels)** — Organice las notificaciones en categorías (Android 8.0+)
* **[Extensiones de servicio](./service-extensions)** — Personalización avanzada de notificaciones
* **[Soporte de Huawei/HMS](./huawei-sdk-setup)** — Alternativa a Google Play Services
### Funciones universales
* [Deep Linking](./deep-linking) — Navegue a los usuarios a pantallas específicas desde las notificaciones
* [Botones de acción](./action-buttons) — Agregue botones interactivos a las notificaciones
* [Verificación de identidad](./identity-verification) — Identificación segura de usuarios
* [Seguimiento de ubicación](./mobile-sdk-reference#location) — Segmentación basada en ubicación
* [Integraciones](./integrations) — Conecte con plataformas de análisis y datos
* [Mensajería multilingüe](./multi-language-messaging) — Notificaciones localizadas
Para la documentación completa de los métodos del SDK, visite la [Referencia del SDK móvil](./mobile-sdk-reference).
***
¿Necesita ayuda?
Chatee con nuestro equipo de Soporte o envíe un correo electrónico a `support@onesignal.com`
Por 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](/docs/es/capturing-a-debug-log) relevante
¡Estamos felices de ayudar!
***