> ## 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 do OSNotification
> Referência para o objeto OSNotification do OneSignal, incluindo todos os campos de payload, propriedades específicas do Android e iOS, dados personalizados e ações de clique.
A classe `OSNotification` representa o payload de notificação push nos SDKs do OneSignal. Use-a para acessar o título da notificação, corpo, dados personalizados e propriedades específicas da plataforma ao lidar com notificações no seu aplicativo.
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 fornecem um listener de evento de notificação que retorna um objeto `OSNotification`:
* **Android**: Use o [notification lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push)
* **iOS**: Use o [notification lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push) ou um `UNNotificationServiceExtension`
### 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 = public`, `0 = private`, `-1 = secret`. |
| `getFromProjectNumber()` | `String` | Número do projeto remetente. |
| `getGroupedNotifications()` | `List` | 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` | 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:
```json theme={null}
{
"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 você enviar pushes de outro serviço para dispositivos que também usam o OneSignal, filtre por esta chave para evitar processamento duplicado. Consulte [Push payload handling](./migrating-to-onesignal#push-payload-handling) para mais informações.
***
## Mover additionalData para a raiz do APNS
Para aplicativos iOS, você pode colocar campos `additionalData` na raiz do payload do APNS em vez de dentro do dicionário `custom`. Isso simplifica o acesso em manipuladores de notificação personalizados.
**1. Habilite via API**
Use a [Update an app API](/reference/update-an-app) e defina:
```json theme={null}
{
"additional_data_is_root_payload": true
}
```
**2. Envie um push com `data`**
Os campos `data` aparecerão na raiz do payload do APNS:
```json theme={null}
{
"aps": {
"alert": { "title": "Sale", "body": "20% off all items!" }
},
"promo_code": "SPRING20"
}
```
Agora você pode acessar `promo_code` diretamente sem verificar o dicionário `custom`.
***
## Notificações restauradas (Android)
O SDK Android restaura notificações após uma reinicialização do dispositivo ou do aplicativo.
| Property | Type | Description |
| ----------- | :-------: | -------------------------------------------------------------------------------------- |
| `restoring` | `boolean` | `true` se a notificação foi restaurada após reinicialização do dispositivo/aplicativo. |
Verifique a flag `restoring` para ignorar notificações restauradas. Para evitar que notificações antigas sejam restauradas por completo, defina um TTL (tempo de vida) curto ou `0` ao enviar.
***
## Formatos de push token
* **iOS Push (APNS)**: 64 caracteres, apenas hexadecimal (0-9, a-f). `deviceToken.map {String(format: "%02x", $0)}.joined()`
* **Android Push (FCM)**: Normalmente 163 caracteres, alfanumérico, pode conter hifens, dois-pontos e sublinhados.
***
## FAQ
### Qual é o tamanho máximo do payload?
Os payloads de notificação push são limitados a 4096 bytes no total. O campo `additionalData` é limitado a 2048 bytes. Para evitar truncamento, mantenha seu payload total abaixo de 3500 bytes.
### Como identifico uma notificação do OneSignal no payload bruto?
Todas as notificações do OneSignal incluem um objeto `"custom"` com uma chave `"i"` contendo o ID da notificação. Verifique essa chave para distinguir notificações do OneSignal daquelas enviadas por outros provedores.
### Posso acessar additionalData na raiz do payload do APNS?
Sim. Habilite `additional_data_is_root_payload` via [Update an app API](/reference/update-an-app) para colocar campos `additionalData` na raiz do APNS em vez de dentro do dicionário `custom`. Consulte [Mover additionalData para a raiz do APNS](#move-additionaldata-to-apns-root) para mais detalhes.
***
Configure canais de notificação para dispositivos Android 8.0+.
Adicione mídia rica, badges e rastreamento de entrega confirmada.
Referência completa dos métodos e listeners do SDK móvel do OneSignal.