Referencia del payload OSNotification
Esta página explica la estructura y campos del payload de notificación push de OneSignal a través de la clase OSNotification. Usa esta referencia al recibir o manejar notificaciones en tu app móvil.
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 activan un listener de eventos de notificación que devuelve un objeto OSNotification.
- Android:
OneSignal.setNotificationWillShowInForegroundHandler(...)
- iOS:
notificationReceivedBlock o UNNotificationServiceExtension
Usa este objeto para acceder al título de la notificación, cuerpo, datos y otras propiedades.
La clase OSNotification proporciona todos los datos del payload de notificación accesibles dentro de los listeners de eventos de notificación del SDK. Fusiona las clases originales OSNotification y OSNotificationPayload en una única interfaz basada en getters.
Campos de Android
| Propiedad | Tipo | 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 = público, 0 = privado, -1 = secreto. |
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
| Propiedad | Tipo | 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 | Método | 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.
| Propiedad | Tipo | 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 o analíticas.Si envías un push desde un servicio diferente a un dispositivo que ya usa OneSignal, evita duplicar notificaciones.
Opcional: mover additionalData a la raíz de APNS
Para apps de iOS, puedes hacer que additionalData esté disponible en la raíz del payload de APNS para un acceso más fácil en manejadores personalizados.
- Habilitar en configuración de app
Usa el API Update an app y establece:
{
"additional_data_is_root_payload": true
}
- Enviar push con
data
Estará disponible en la raíz del payload de APNS. Ejemplo:
{
"aps": {
"alert": { "title": "Sale", "body": "20% off all items!" }
},
"promo_code": "SPRING20"
}
promo_code sin verificar el diccionario personalizado.
Notificaciones restauradas
Las notificaciones serán restauradas por el SDK de Android después de un reinicio o reinicio de app.
| Propiedad | Tipo | Descripción |
|---|
restoring | boolean | true si la notificación fue restaurada después del reinicio del dispositivo/app. |
Las notificaciones restauradas pueden omitirse usando la bandera restoring. Para evitar restaurar contenido antiguo, establece un TTL (time-to-live) corto o 0 en tus notificaciones.
Temas relacionados
