Charge utile OSNotification

La classe OSNotification représente la charge utile de notification push dans les SDK OneSignal. Utilisez-la pour accéder au titre, au corps, aux données personnalisées et aux propriétés spécifiques à la plateforme lors de la gestion des notifications dans votre application.

Les charges utiles de notification push sont limitées à 4096 octets. Pour éviter la troncation, gardez les charges utiles sous 3500 octets. Le champ additionalData est limité à 2048 octets.

Accès à `OSNotification` dans votre application

Tous les SDK OneSignal fournissent un écouteur d’événement de notification qui renvoie un objet OSNotification :

Android : Utilisez le notification lifecycle listener
iOS : Utilisez le notification lifecycle listener ou un UNNotificationServiceExtension

Champs Android

Property	Type	Description
`getBody()`	`String`	Texte du corps de la notification.
`getTitle()`	`String`	Titre de la notification.
`getLaunchURL()`	`String`	URL ouverte lorsque la notification est cliquée.
`getNotificationId()`	`String`	UUID de notification OneSignal.
`getAdditionalData()`	`JSONObject`	Données clé-valeur personnalisées définies via le tableau de bord ou l’API REST. Max 2048 octets.
`getTemplateId()`	`String`	UUID de modèle, si envoyé en utilisant des modèles.
`getAndroidNotificationId()`	`int`	ID de notification Android natif.
`getLargeIcon()`	`String`	URL ou nom de ressource de la grande icône.
`getSmallIcon()`	`String`	Nom de ressource de la petite icône.
`getSmallIconAccentColor()`	`String`	Couleur d’accentuation de l’icône au format ARGB.
`getSound()`	`String`	Nom de ressource du son joué.
`getCollapseId()`	`String`	Clé de regroupement pour le remplacement de notification.
`getPriority()`	`int`	Priorité Android (-2 à 2).
`getLedColor()`	`String`	Couleur LED au format ARGB.
`getLockScreenVisibility()`	`int`	Visibilité de l’écran de verrouillage : `1 = public`, `0 = private`, `-1 = secret`.
`getFromProjectNumber()`	`String`	Numéro de projet de l’expéditeur.
`getGroupedNotifications()`	`List<OSNotification>`	Notifications incluses dans un résumé.
`getGroupKey()`	`String`	Clé de groupe utilisée dans les résumés.
`getGroupMessage()`	`String`	Texte du résumé.
`getBackgroundImageLayout()`	`BackgroundImageLayout`	Objet pour la mise en page de l’image de fond et les couleurs de texte.
`getActionButtons()`	`List<ActionButton>`	Boutons d’action avec icône, texte et ID.
`getRawPayload()`	`String`	Chaîne JSON brute complète de la charge utile.

Champs iOS

Property	Type	Description
`body`	`NSString`	Texte du corps de la notification.
`title`	`NSString`	Titre de la notification.
`launchURL`	`NSString`	URL ouverte lorsque la notification est cliquée.
`notificationId`	`NSString`	UUID de notification OneSignal.
`additionalData`	`Dictionary`	`data` clé-valeur personnalisées définies via le tableau de bord ou l’API REST. Max 2048 octets.
`templateId`	`NSString`	UUID de modèle, si envoyé en utilisant des modèles.
`subtitle`	`NSString`	Texte du sous-titre.
`category`	`NSString`	Identifiant de catégorie iOS.
`threadId`	`NSString`	Utilisé pour regrouper les notifications en fils (iOS 10+).
`badge`	`NSInteger`	Valeur absolue du badge.
`badgeIncrement`	`NSInteger`	Montant pour incrémenter le badge.
`contentAvailable`	`BOOL`	Si `content-available=1`, déclenche une récupération en arrière-plan.
`mutableContent`	`BOOL`	Si `mutable-content=1`, déclenche une Extension de Service de Notification.
`actionButtons`	`NSArray`	Boutons d’action iOS.
`rawPayload`	`NSDictionary`	JSON brut complet de la charge utile.
`parseWithApns`	Method	Convertit la charge utile APNS brute en OSNotification. À utiliser dans les extensions de service.

`OSNotificationAction` (événements de clic)

Décrit l’interaction de l’utilisateur avec la notification.

Property	Type	Description
`actionId`	`String`	L’ID du bouton d’action cliqué.
`type`	`enum`	`Opened` (appui par défaut) ou `ActionTaken` (appui sur bouton).

Structure de charge utile OneSignal personnalisée

Toutes les notifications OneSignal incluent un objet spécial "custom" dans la charge utile :

{
  "custom": {
    "i": "the-notification-id"
  }
}

Cette clé est requise pour que les SDK OneSignal traitent la notification. Si elle est manquante, les notifications ne déclencheront pas d’événements de clic ou d’analyses. Si vous envoyez des notifications push depuis un autre service vers des appareils qui utilisent également OneSignal, filtrez par cette clé pour éviter un traitement en double. Consultez Gestion de la charge utile push pour plus d’informations.

Déplacer additionalData à la racine APNS

Pour les applications iOS, vous pouvez placer les champs additionalData à la racine de la charge utile APNS plutôt qu’à l’intérieur du dictionnaire custom. Cela simplifie l’accès dans les gestionnaires de notifications personnalisés. 1. Activer via l’API Utilisez l’API Mettre à jour une application et définissez :

{
  "additional_data_is_root_payload": true
}

2. Envoyer un push avec data Les champs data apparaissent à la racine de la charge utile APNS :

{
  "aps": {
    "alert": { "title": "Sale", "body": "20% off all items!" }
  },
  "promo_code": "SPRING20"
}

Vous pouvez maintenant accéder directement à promo_code sans vérifier le dictionnaire custom.

Notifications restaurées (Android)

Le SDK Android restaure les notifications après un redémarrage de l’appareil ou de l’application.

Property	Type	Description
`restoring`	`boolean`	`true` si la notification a été restaurée après un redémarrage de l’appareil/application.

Vérifiez le flag restoring pour ignorer les notifications restaurées. Pour empêcher entièrement la restauration des anciennes notifications, définissez un TTL (time-to-live) court ou à 0 lors de l’envoi.

Formats de token push

iOS Push (APNS) : 64 caractères, hexadécimal uniquement (0-9, a-f). deviceToken.map {String(format: "%02x", $0)}.joined()
Android Push (FCM) : Généralement 163 caractères, alphanumérique, peut contenir des tirets, des deux-points et des tirets bas.

FAQ

Quelle est la taille maximale de la charge utile ?

Les charges utiles de notification push sont limitées à 4096 octets au total. Le champ additionalData est limité à 2048 octets. Pour éviter la troncation, gardez votre charge utile totale sous 3500 octets.

Comment identifier une notification OneSignal dans la charge utile brute ?

Toutes les notifications OneSignal incluent un objet "custom" avec une clé "i" contenant l’ID de notification. Vérifiez cette clé pour distinguer les notifications OneSignal de celles envoyées par d’autres fournisseurs.

Puis-je accéder à additionalData dans la racine de la charge utile APNS ?

Oui. Activez additional_data_is_root_payload via l’API Mettre à jour une application pour placer les champs additionalData à la racine APNS plutôt qu’à l’intérieur du dictionnaire custom. Consultez Déplacer additionalData à la racine APNS pour plus de détails.

Catégories de notification Android

Configurez les canaux de notification pour les appareils Android 8.0+.

Extensions de service mobile

Ajoutez des médias enrichis, des badges et le suivi de livraison confirmée.

Référence du SDK mobile

Référence complète des méthodes et écouteurs du SDK mobile OneSignal.

Documentation développeur

SDK mobiles

SDK web

Activités en direct

Configuration desktop et montre

Charge utile OSNotification

Accès à `OSNotification` dans votre application

Champs Android

Champs iOS

`OSNotificationAction` (événements de clic)

Structure de charge utile OneSignal personnalisée

Déplacer additionalData à la racine APNS

Notifications restaurées (Android)

Formats de token push

FAQ

Quelle est la taille maximale de la charge utile ?

Comment identifier une notification OneSignal dans la charge utile brute ?

Puis-je accéder à additionalData dans la racine de la charge utile APNS ?

Catégories de notification Android

Extensions de service mobile

Référence du SDK mobile

​Accès à OSNotification dans votre application

​Champs Android

​Champs iOS

​OSNotificationAction (événements de clic)

​Structure de charge utile OneSignal personnalisée

​Déplacer additionalData à la racine APNS

​Notifications restaurées (Android)

​Formats de token push

​FAQ

​Quelle est la taille maximale de la charge utile ?

​Comment identifier une notification OneSignal dans la charge utile brute ?

​Puis-je accéder à additionalData dans la racine de la charge utile APNS ?

Catégories de notification Android

Extensions de service mobile

Référence du SDK mobile

Accès à `OSNotification` dans votre application

Champs Android

Champs iOS

`OSNotificationAction` (événements de clic)

Structure de charge utile OneSignal personnalisée

Déplacer additionalData à la racine APNS

Notifications restaurées (Android)

Formats de token push

FAQ

Quelle est la taille maximale de la charge utile ?

Comment identifier une notification OneSignal dans la charge utile brute ?

Puis-je accéder à additionalData dans la racine de la charge utile APNS ?