> ## 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.
# Charge utile OSNotification
> Référence pour l'objet OSNotification de OneSignal, incluant tous les champs de charge utile, les propriétés spécifiques Android et iOS, les données personnalisées et les actions de clic.
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](./mobile-sdk-reference#addforegroundlifecyclelistener-push)
* **iOS** : Utilisez le [notification lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push) 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` | 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` | 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 :
```json theme={null}
{
"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](./migrating-to-onesignal#push-payload-handling) 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](/reference/update-an-app) et définissez :
```json theme={null}
{
"additional_data_is_root_payload": true
}
```
**2. Envoyer un push avec `data`**
Les champs `data` apparaissent à la racine de la charge utile APNS :
```json theme={null}
{
"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](/reference/update-an-app) pour placer les champs `additionalData` à la racine APNS plutôt qu'à l'intérieur du dictionnaire `custom`. Consultez [Déplacer additionalData à la racine APNS](#move-additionaldata-to-apns-root) pour plus de détails.
***
Configurez les canaux de notification pour les appareils Android 8.0+.
Ajoutez des médias enrichis, des badges et le suivi de livraison confirmée.
Référence complète des méthodes et écouteurs du SDK mobile OneSignal.