Referência do payload OSNotification
Esta página explica a estrutura e campos do payload de notificação push do OneSignal por meio da classe OSNotification. Use esta referência ao receber ou manipular notificações em seu aplicativo móvel.
Os payloads de notificação push são limitados a 4096 bytes. Para evitar truncamento, mantenha payloads abaixo de 3500 bytes. O campo additionalData é limitado a 2048 bytes.
Acessando OSNotification no seu aplicativo
Todos os SDKs do OneSignal acionam um listener de evento de notificação que retorna um objeto OSNotification.
- Android:
OneSignal.setNotificationWillShowInForegroundHandler(...)
- iOS:
notificationReceivedBlock ou UNNotificationServiceExtension
Use este objeto para acessar o título, corpo, dados e outras propriedades da notificação.
A classe OSNotification fornece todos os dados de payload de notificação acessíveis dentro dos listeners de evento de notificação do SDK. Ela mescla as classes originais OSNotification e OSNotificationPayload em uma única interface baseada em getters.
Campos do Android
| Property | Type | Description |
|---|
getBody() | String | Texto do corpo da notificação. |
getTitle() | String | Título da notificação. |
getLaunchURL() | String | URL aberto quando a notificação é clicada. |
getNotificationId() | String | UUID da notificação do OneSignal. |
getAdditionalData() | JSONObject | Dados personalizados chave-valor definidos via painel ou REST API. Máx. 2048 bytes. |
getTemplateId() | String | UUID do template, se enviado usando templates. |
getAndroidNotificationId() | int | ID de notificação nativa do Android. |
getLargeIcon() | String | URL ou nome do recurso do ícone grande. |
getSmallIcon() | String | Nome do recurso do ícone pequeno. |
getSmallIconAccentColor() | String | Cor de destaque do ícone no formato ARGB. |
getSound() | String | Nome do recurso de som reproduzido. |
getCollapseId() | String | Chave de colapso para substituição de notificação. |
getPriority() | int | Prioridade do Android (-2 a 2). |
getLedColor() | String | Cor do LED no formato ARGB. |
getLockScreenVisibility() | int | Visibilidade na tela de bloqueio: 1 = público, 0 = privado, -1 = secreto. |
getFromProjectNumber() | String | Número do projeto remetente. |
getGroupedNotifications() | List<OSNotification> | Notificações incluídas em um resumo. |
getGroupKey() | String | Chave de grupo usada em resumos. |
getGroupMessage() | String | Texto do resumo. |
getBackgroundImageLayout() | BackgroundImageLayout | Objeto para layout de imagem de fundo e cores de texto. |
getActionButtons() | List<ActionButton> | Botões de ação com ícone, texto e ID. |
getRawPayload() | String | String JSON bruto completo do payload. |
Campos do iOS
| Property | Type | Description |
|---|
body | NSString | Texto do corpo da notificação. |
title | NSString | Título da notificação. |
launchURL | NSString | URL aberto quando a notificação é clicada. |
notificationId | NSString | UUID da notificação do OneSignal. |
additionalData | Dictionary | data personalizado chave-valor definido via painel ou REST API. Máx. 2048 bytes. |
templateId | NSString | UUID do template, se enviado usando templates. |
subtitle | NSString | Texto do subtítulo. |
category | NSString | Identificador de categoria do iOS. |
threadId | NSString | Usado para agrupar notificações em threads (iOS 10+). |
badge | NSInteger | Valor absoluto do badge. |
badgeIncrement | NSInteger | Quantidade para incrementar o badge. |
contentAvailable | BOOL | Se content-available=1, aciona busca em segundo plano. |
mutableContent | BOOL | Se mutable-content=1, aciona uma Notification Service Extension. |
actionButtons | NSArray | Botões de ação do iOS. |
rawPayload | NSDictionary | JSON bruto completo do payload. |
parseWithApns | Method | Converte payload APNS bruto em um OSNotification. Use em extensões de serviço. |
OSNotificationAction (eventos de clique)
Descreve a interação do usuário com a notificação.
| Property | Type | Description |
|---|
actionId | String | O ID do botão de ação clicado. |
type | enum | Opened (toque padrão) ou ActionTaken (toque no botão). |
Estrutura de payload personalizado do OneSignal
Todas as notificações do OneSignal incluem um objeto especial "custom" no payload:
{
"custom": {
"i": "the-notification-id"
}
}
Esta chave é necessária para que os SDKs do OneSignal processem a notificação. Se estiver ausente, as notificações não acionarão eventos de clique ou análises.Se estiver enviando um push de um serviço diferente para um dispositivo que já usa o OneSignal, evite duplicar notificações.
Opcional: mover additionalData para a raiz do APNS
Para aplicativos iOS, você pode disponibilizar additionalData na raiz do payload do APNS para facilitar o acesso em manipuladores personalizados.
- Habilite nas configurações do aplicativo
Use a API Update an app e defina:
{
"additional_data_is_root_payload": true
}
- Envie push com
data
Ele estará disponível na raiz do payload do APNS. Exemplo:
{
"aps": {
"alert": { "title": "Sale", "body": "20% off all items!" }
},
"promo_code": "SPRING20"
}
promo_code sem verificar o dicionário personalizado.
Notificações restauradas
As notificações serão restauradas pelo SDK Android após uma reinicialização ou reinicialização do aplicativo.
| Property | Type | Description |
|---|
restoring | boolean | true se a notificação foi restaurada após reinicialização do dispositivo/aplicativo. |
As notificações restauradas podem ser ignoradas usando a flag restoring. Para evitar restaurar conteúdo antigo, defina um TTL (tempo de vida) curto ou 0 em suas notificações.
Tópicos relacionados
