Payload OSNotification

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
iOS: Usa el notification lifecycle listener 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<OSNotification>`	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<ActionButton>`	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:

{
  "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 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 y establece:

{
  "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:

{
  "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 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 para más detalles.

Categorías de notificación de Android

Configura canales de notificación para dispositivos Android 8.0+.

Service Extensions móviles

Añade contenido enriquecido, insignias y seguimiento de entrega confirmada.

Referencia del SDK móvil

Referencia completa de los métodos y listeners del SDK móvil de OneSignal.

Documentación del desarrollador

SDKs móviles

SDKs web

Actividades en directo

Configuración de Desktop & Watch

Payload OSNotification

Acceder a `OSNotification` en tu app

Campos de Android

Campos de iOS

`OSNotificationAction` (eventos de clic)

Estructura de payload personalizado de OneSignal

Mover additionalData a la raíz de APNS

Notificaciones restauradas (Android)

Formatos de push token

Preguntas frecuentes

¿Cuál es el tamaño máximo del payload?

¿Cómo identifico una notificación de OneSignal en el payload sin procesar?

¿Puedo acceder a additionalData en la raíz del payload de APNS?

Categorías de notificación de Android

Service Extensions móviles

Referencia del SDK móvil

​Acceder a OSNotification en tu app

​Campos de Android

​Campos de iOS

​OSNotificationAction (eventos de clic)

​Estructura de payload personalizado de OneSignal

​Mover additionalData a la raíz de APNS

​Notificaciones restauradas (Android)

​Formatos de push token

​Preguntas frecuentes

​¿Cuál es el tamaño máximo del payload?

​¿Cómo identifico una notificación de OneSignal en el payload sin procesar?

​¿Puedo acceder a additionalData en la raíz del payload de APNS?

Categorías de notificación de Android

Service Extensions móviles

Referencia del SDK móvil

Acceder a `OSNotification` en tu app

Campos de Android

Campos de iOS

`OSNotificationAction` (eventos de clic)

Estructura de payload personalizado de OneSignal

Mover additionalData a la raíz de APNS

Notificaciones restauradas (Android)

Formatos de push token

Preguntas frecuentes

¿Cuál es el tamaño máximo del payload?

¿Cómo identifico una notificación de OneSignal en el payload sin procesar?

¿Puedo acceder a additionalData en la raíz del payload de APNS?