> ## 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.
# Payload OSNotification
> Referencia del objeto OSNotification de OneSignal, incluyendo todos los campos del payload, propiedades específicas de Android e iOS, datos personalizados y acciones de clic.
La clase `OSNotification` representa el payload de notificación push en los SDKs de OneSignal. Úsala para acceder al título de la notificación, cuerpo, datos personalizados y propiedades específicas de la plataforma al manejar notificaciones en tu app.
Los payloads de notificaciones push están limitados a `4096` bytes. Para evitar truncamiento, mantén los payloads por debajo de `3500` bytes. El campo `additionalData` está limitado a `2048` bytes.
***
## Acceder a `OSNotification` en tu app
Todos los SDKs de OneSignal proporcionan un listener de eventos de notificación que devuelve un objeto `OSNotification`:
* **Android**: Usa el [notification lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push)
* **iOS**: Usa el [notification lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push) o un `UNNotificationServiceExtension`
### Campos de Android
| Property | Type | Descripción |
| ---------------------------- | :---------------------: | --------------------------------------------------------------------------------------------------- |
| `getBody()` | `String` | Texto del cuerpo de la notificación. |
| `getTitle()` | `String` | Título de la notificación. |
| `getLaunchURL()` | `String` | URL abierta cuando se hace clic en la notificación. |
| `getNotificationId()` | `String` | UUID de notificación de OneSignal. |
| `getAdditionalData()` | `JSONObject` | Datos clave-valor personalizados establecidos a través del dashboard o REST API. Máximo 2048 bytes. |
| `getTemplateId()` | `String` | UUID de plantilla, si se envió usando plantillas. |
| `getAndroidNotificationId()` | `int` | ID de notificación nativa de Android. |
| `getLargeIcon()` | `String` | URL o nombre de recurso del ícono grande. |
| `getSmallIcon()` | `String` | Nombre de recurso del ícono pequeño. |
| `getSmallIconAccentColor()` | `String` | Color de acento del ícono en formato ARGB. |
| `getSound()` | `String` | Nombre de recurso de sonido reproducido. |
| `getCollapseId()` | `String` | Clave de colapso para reemplazo de notificación. |
| `getPriority()` | `int` | Prioridad de Android (-2 a 2). |
| `getLedColor()` | `String` | Color LED en formato ARGB. |
| `getLockScreenVisibility()` | `int` | Visibilidad en pantalla de bloqueo: `1 = public`, `0 = private`, `-1 = secret`. |
| `getFromProjectNumber()` | `String` | Número de proyecto del remitente. |
| `getGroupedNotifications()` | `List` | Notificaciones incluidas en un resumen. |
| `getGroupKey()` | `String` | Clave de grupo usada en resúmenes. |
| `getGroupMessage()` | `String` | Texto de resumen. |
| `getBackgroundImageLayout()` | `BackgroundImageLayout` | Objeto para diseño de imagen de fondo y colores de texto. |
| `getActionButtons()` | `List` | Botones de acción con ícono, texto e ID. |
| `getRawPayload()` | `String` | Cadena JSON completa sin procesar del payload. |
### Campos de iOS
| Property | Type | Descripción |
| ------------------ | :------------: | -------------------------------------------------------------------------------------------------- |
| `body` | `NSString` | Texto del cuerpo de la notificación. |
| `title` | `NSString` | Título de la notificación. |
| `launchURL` | `NSString` | URL abierta cuando se hace clic en la notificación. |
| `notificationId` | `NSString` | UUID de notificación de OneSignal. |
| `additionalData` | `Dictionary` | `data` clave-valor personalizado establecido a través del dashboard o REST API. Máximo 2048 bytes. |
| `templateId` | `NSString` | UUID de plantilla, si se envió usando plantillas. |
| `subtitle` | `NSString` | Texto del subtítulo. |
| `category` | `NSString` | Identificador de categoría de iOS. |
| `threadId` | `NSString` | Usado para agrupar notificaciones en hilos (iOS 10+). |
| `badge` | `NSInteger` | Valor absoluto de insignia. |
| `badgeIncrement` | `NSInteger` | Cantidad para incrementar la insignia. |
| `contentAvailable` | `BOOL` | Si `content-available=1`, activa recuperación en segundo plano. |
| `mutableContent` | `BOOL` | Si `mutable-content=1`, activa una Notification Service Extension. |
| `actionButtons` | `NSArray` | Botones de acción de iOS. |
| `rawPayload` | `NSDictionary` | JSON completo sin procesar del payload. |
| `parseWithApns` | *Method* | Convierte payload APNS sin procesar en un OSNotification. Usar en service extensions. |
***
## `OSNotificationAction` (eventos de clic)
Describe la interacción del usuario con la notificación.
| Property | Type | Descripción |
| ---------- | :------: | ----------------------------------------------------------------- |
| `actionId` | `String` | El ID del botón de acción al que se hizo clic. |
| `type` | `enum` | `Opened` (toque predeterminado) o `ActionTaken` (toque de botón). |
***
## Estructura de payload personalizado de OneSignal
Todas las notificaciones de OneSignal incluyen un objeto especial `"custom"` en el payload:
```json theme={null}
{
"custom": {
"i": "the-notification-id"
}
}
```
Esta clave es requerida para que los SDKs de OneSignal procesen la notificación. Si falta, las notificaciones no activarán eventos de clic ni analíticas. Si envías pushes desde otro servicio a dispositivos que también usan OneSignal, filtra por esta clave para evitar procesamiento duplicado. Consulta [Push payload handling](./migrating-to-onesignal#push-payload-handling) para más información.
***
## Mover additionalData a la raíz de APNS
Para apps de iOS, puedes colocar los campos de `additionalData` en la raíz del payload de APNS en lugar de dentro del diccionario `custom`. Esto simplifica el acceso en manejadores de notificaciones personalizados.
**1. Habilitar a través de la API**
Usa el [API Update an app](/reference/update-an-app) y establece:
```json theme={null}
{
"additional_data_is_root_payload": true
}
```
**2. Enviar un push con `data`**
Los campos de `data` aparecen en la raíz del payload de APNS:
```json theme={null}
{
"aps": {
"alert": { "title": "Sale", "body": "20% off all items!" }
},
"promo_code": "SPRING20"
}
```
Ahora puedes acceder directamente a `promo_code` sin verificar el diccionario `custom`.
***
## Notificaciones restauradas (Android)
El SDK de Android restaura las notificaciones después de un reinicio del dispositivo o de la app.
| Property | Type | Descripción |
| ----------- | :-------: | ---------------------------------------------------------------------------------- |
| `restoring` | `boolean` | `true` si la notificación fue restaurada después del reinicio del dispositivo/app. |
Verifica la bandera `restoring` para omitir notificaciones restauradas. Para evitar que notificaciones antiguas se restauren por completo, establece un TTL (time-to-live) corto o `0` al enviar.
***
## Formatos de push token
* **iOS Push (APNS)**: 64 caracteres, solo hexadecimal (0-9, a-f). `deviceToken.map {String(format: "%02x", $0)}.joined()`
* **Android Push (FCM)**: Típicamente 163 caracteres, alfanumérico, puede contener guiones, dos puntos y guiones bajos.
***
## Preguntas frecuentes
### ¿Cuál es el tamaño máximo del payload?
Los payloads de notificaciones push están limitados a 4096 bytes en total. El campo `additionalData` está limitado a 2048 bytes. Para evitar truncamiento, mantén tu payload total por debajo de 3500 bytes.
### ¿Cómo identifico una notificación de OneSignal en el payload sin procesar?
Todas las notificaciones de OneSignal incluyen un objeto `"custom"` con una clave `"i"` que contiene el ID de la notificación. Verifica esta clave para distinguir las notificaciones de OneSignal de las enviadas por otros proveedores.
### ¿Puedo acceder a additionalData en la raíz del payload de APNS?
Sí. Habilita `additional_data_is_root_payload` a través del [API Update an app](/reference/update-an-app) para colocar los campos de `additionalData` en la raíz de APNS en lugar de dentro del diccionario `custom`. Consulta [Mover additionalData a la raíz de APNS](#move-additionaldata-to-apns-root) para más detalles.
***
Configura canales de notificación para dispositivos Android 8.0+.
Añade contenido enriquecido, insignias y seguimiento de entrega confirmada.
Referencia completa de los métodos y listeners del SDK móvil de OneSignal.