Payload do OSNotification

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
iOS: Use o notification lifecycle listener 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<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 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 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 e defina:

{
  "additional_data_is_root_payload": true
}

2. Envie um push com data Os campos data aparecerão na raiz do payload do APNS:

{
  "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 para colocar campos additionalData na raiz do APNS em vez de dentro do dicionário custom. Consulte Mover additionalData para a raiz do APNS para mais detalhes.

Categorias de notificação do Android

Configure canais de notificação para dispositivos Android 8.0+.

Mobile Service Extensions

Adicione mídia rica, badges e rastreamento de entrega confirmada.

Referência do SDK móvel

Referência completa dos métodos e listeners do SDK móvel do OneSignal.

Documentação de desenvolvedor

SDKs móveis

SDKs web

Atividades ao Vivo

Configuração de Desktop & Watch

Payload do OSNotification

Acessando `OSNotification` no seu aplicativo

Campos do Android

Campos do iOS

`OSNotificationAction` (eventos de clique)

Estrutura de payload personalizado do OneSignal

Mover additionalData para a raiz do APNS

Notificações restauradas (Android)

Formatos de push token

FAQ

Qual é o tamanho máximo do payload?

Como identifico uma notificação do OneSignal no payload bruto?

Posso acessar additionalData na raiz do payload do APNS?

Categorias de notificação do Android

Mobile Service Extensions

Referência do SDK móvel

​Acessando OSNotification no seu aplicativo

​Campos do Android

​Campos do iOS

​OSNotificationAction (eventos de clique)

​Estrutura de payload personalizado do OneSignal

​Mover additionalData para a raiz do APNS

​Notificações restauradas (Android)

​Formatos de push token

​FAQ

​Qual é o tamanho máximo do payload?

​Como identifico uma notificação do OneSignal no payload bruto?

​Posso acessar additionalData na raiz do payload do APNS?

Categorias de notificação do Android

Mobile Service Extensions

Referência do SDK móvel

Acessando `OSNotification` no seu aplicativo

Campos do Android

Campos do iOS

`OSNotificationAction` (eventos de clique)

Estrutura de payload personalizado do OneSignal

Mover additionalData para a raiz do APNS

Notificações restauradas (Android)

Formatos de push token

FAQ

Qual é o tamanho máximo do payload?

Como identifico uma notificação do OneSignal no payload bruto?

Posso acessar additionalData na raiz do payload do APNS?