Référence de la charge utile OSNotification
Cette page explique la structure et les champs de la charge utile de notification push OneSignal via la classe OSNotification. Utilisez cette référence lors de la réception ou de la gestion des notifications dans votre application mobile.
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 déclenchent un écouteur d’événement de notification qui renvoie un objet OSNotification.
- Android:
OneSignal.setNotificationWillShowInForegroundHandler(...)
- iOS:
notificationReceivedBlock ou UNNotificationServiceExtension
Utilisez cet objet pour accéder au titre, au corps, aux données et aux autres propriétés de la notification.
La classe OSNotification fournit toutes les données de charge utile de notification accessibles dans les écouteurs d’événement de notification du SDK. Elle fusionne les classes originales OSNotification et OSNotificationPayload en une seule interface basée sur des getters.
Champs Android
| Propriété | 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 = privé, -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
| Propriété | 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 | Méthode | 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.
| Propriété | 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 un push depuis un service différent vers un appareil utilisant déjà OneSignal, évitez de dupliquer les notifications.
Optionnel : déplacer additionalData à la racine APNS
Pour les applications iOS, vous pouvez rendre additionalData disponible à la racine de la charge utile APNS pour un accès plus facile dans les gestionnaires personnalisés.
- Activer dans les paramètres de l’application
Utilisez l’API Mettre à jour une application et définissez :
{
"additional_data_is_root_payload": true
}
- Envoyer un push avec
data
Il sera disponible à la racine de la charge utile APNS. Exemple :
{
"aps": {
"alert": { "title": "Sale", "body": "20% off all items!" }
},
"promo_code": "SPRING20"
}
promo_code sans vérifier le dictionnaire personnalisé.
Notifications restaurées
Les notifications seront restaurées par le SDK Android après un redémarrage ou un redémarrage de l’application.
| Propriété | Type | Description |
|---|
restoring | boolean | true si la notification a été restaurée après un redémarrage de l’appareil/application. |
Les notifications restaurées peuvent être ignorées en utilisant le flag restoring. Pour éviter de restaurer du contenu ancien, définissez un TTL (time-to-live) court ou à 0 sur vos notifications.
Sujets connexes
