Aperçu
Les extensions de service de notification vous permettent d’intercepter et de modifier les notifications push avant qu’elles ne soient affichées à l’utilisateur. Cela permet :
- Gestion des données en arrière-plan
- Styles personnalisés (couleurs, icônes, vibration)
- Pièces jointes de médias enrichis (images, vidéos)
- Livraison confirmée/analytiques
- Options de boutons d’action
Vous pouvez accéder aux données de vos notifications push envoyées depuis OneSignal via la classe OSNotification
Extension de service de notification Android
Vous permet de traiter la notification avant qu’elle ne soit affichée à l’utilisateur. Les cas d’usage courants incluent :
- Recevoir des données en arrière-plan avec ou sans affichage de notification.
- Remplacer des paramètres de notification spécifiques en fonction de la logique d’application côté client, comme la couleur d’accentuation personnalisée, le motif de vibration ou toute autre option
NotificationCompat disponible.
Pour plus de détails, consultez la documentation d’Android sur les options NotificationCompat.
1. Créer une classe pour l’extension de service
Créez une classe qui étend INotificationServiceExtension et implémentez la méthode onNotificationReceived.
Le paramètre de la méthode onNotificationReceived est event de type INotificationReceivedEvent .
package your.package.name
import androidx.annotation.Keep;
import com.onesignal.notifications.IActionButton;
import com.onesignal.notifications.IDisplayableMutableNotification;
import com.onesignal.notifications.INotificationReceivedEvent;
import com.onesignal.notifications.INotificationServiceExtension;
@Keep // Keep is required to prevent minification from renaming or removing your class
public class NotificationServiceExtension implements INotificationServiceExtension {
@Override
public void onNotificationReceived(INotificationReceivedEvent event) {
IDisplayableMutableNotification notification = event.getNotification();
if (notification.getActionButtons() != null) {
for (IActionButton button : notification.getActionButtons()) {
// you can modify your action buttons here
}
}
/* Add customizations here. See examples below for additional methods to modify the notification*/
}
}
2. Exemples de cas d’usage
Voici des exemples courants que vous pouvez implémenter dans la classe de modèle d’extension de service de notification ci-dessus.
Empêcher l'affichage de la notification
Ajouter un champ personnalisé
Changer la couleur et l'icône de la notification
event.preventDefault();
//Do some async work, then decide to show or dismiss
new Thread(() -> {
try {
Thread.sleep(1000);
} catch (InterruptedException ignored) {}
//Manually show the notification
event.getNotification().display();
}).start();
3. Ajouter l’extension de service à votre AndroidManifest.xml
Ajoutez le nom de la classe et la valeur en tant que meta-data dans le fichier AndroidManifest.xml dans la balise application. Ignorez les avertissements “unused”.
<application>
<!-- Keep android:name as shown, set android:value toyour class fully name spaced-->
<meta-data
android:name="com.onesignal.NotificationServiceExtension"
android:value="com.onesignal.example.NotificationServiceExtension" />
</application>
Extension de service de notification iOS
L’UNNotificationServiceExtension vous permet de modifier le contenu des notifications push avant qu’elles ne soient affichées à l’utilisateur et est requis pour d’autres fonctionnalités importantes comme :
Vous avez probablement déjà configuré cela si vous avez suivi nos instructions de configuration du SDK mobile pour votre application, mais cette section expliquera comment accéder aux données de charge utile de notification OneSignal et résoudre les problèmes que vous pourriez rencontrer.
Obtenir la charge utile push iOS
Lorsque vous suivez la configuration du SDK mobile, vous arriverez à la section sur l’ajout du code à la OneSignalNotificationServiceExtension.
Dans ce code, il y a la méthode OneSignalExtension.didReceiveNotificationExtensionRequest. C’est là que nous transmettons le bestAttemptContent de la notification à l’application avant qu’elle ne soit affichée à l’utilisateur. Avant que cette méthode ne soit appelée, vous pouvez obtenir la charge utile de notification et (si désiré) la mettre à jour avant qu’elle ne soit affichée à l’utilisateur.
Dans cet exemple, nous envoyons une notification avec les données suivantes :
{
"app_id": "YOUR_APP_ID",
"target_channel": "push",
"headings": {"en": "The message title"},
"contents": {"en": "The message contents"},
"data":{
"additional_data_key_1":"value_1",
"additional_data_key_2":"value_2"
},
"include_subscription_ids": ["SUBSCRIPTION_ID_1"]
}
Nous pouvons accéder à ces data supplémentaires dans la OneSignalNotificationServiceExtension via l’objet custom en utilisant le paramètre a.
// Check if `bestAttemptContent` exists
if let bestAttemptContent = bestAttemptContent {
// Try to retrieve the "custom" data from the notification payload
if let customData = bestAttemptContent.userInfo["custom"] as? [String: Any],
let additionalData = customData["a"] as? [String: Any] {
// Convert the `additionalData` dictionary to a JSON string for logging
if let jsonData = try? JSONSerialization.data(withJSONObject: additionalData, options: .prettyPrinted),
let jsonString = String(data: jsonData, encoding: .utf8) {
// Successfully converted to JSON; log the formatted JSON string
print("The additionalData dictionary in JSON format:\n\(jsonString)")
} else {
// Failed to convert the `additionalData` dictionary to JSON
print("Failed to convert additionalData to JSON format.")
}
}
// Try to retrieve the "aps" data from the notification payload
if let messageData = bestAttemptContent.userInfo["aps"] as? [String: Any],
let apsData = messageData["alert"] as? [String: Any],
let body = apsData["body"] as? String, // Extract the "body" of the alert
let title = apsData["title"] as? String { // Extract the "title" of the alert
// Successfully retrieved the body and title; log the values
print("The message contents is: \(body), message headings is: \(title)")
} else {
// Failed to retrieve the "aps" data or its contents
print("Unable to retrieve apsData")
}
// Pass the notification to OneSignal for further processing
OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest,
with: bestAttemptContent,
withContentHandler: self.contentHandler)
}
Example console output:
The additionalData dictionary in JSON format:
{
"additional_data_key_1" : "value_1",
"additional_data_key_2" : "value_2"
}
The message contents is: The message contents, message headings is: The message title
Dépannage de l’extension de service de notification iOS
Ce guide est destiné au débogage des problèmes avec les images, les boutons d’action ou les livraisons confirmées qui ne s’affichent pas sur les applications mobiles iOS.
Vérifiez vos paramètres Xcode
Dans General > Targets, assurez-vous que votre cible d’application principale et la cible OneSignalNotificationServiceExtension ont les mêmes paramètres corrects :
- Supported Destinations
- Minimum Deployment (iOS 14.5 ou supérieur)
Si vous utilisez Cocoapods, assurez-vous que ceux-ci correspondent à votre cible principale dans le Podfile pour éviter les erreurs de compilation.
Exemple de cible d'application principale dans Xcode
Exemple de cible OneSignalNotificationServiceExtension dans Xcode
En continuant dans l’onglet OneSignalNotificationServiceExtension > Info, développez la clé NSExtension. Assurez-vous de voir :
<dict>
<key>NSExtensionPointIdentifier</key>
<string>com.apple.usernotifications.service</string>
<key>NSExtensionPrincipalClass</key>
<string>$(PRODUCT_MODULE_NAME).NotificationService</string>
</dict>
Exemple :
Exemple de clé NSExtension dans l'onglet Info
Si vous utilisez Objective-C, au lieu de $(PRODUCT_MODULE_NAME).NotificationService, utilisez NotificationService.
Désactiver “Copy only when installing”
Sélectionnez votre cible d’application principale > Build Phases > Embed App Extensions. Assurez-vous que “Copy only when installing” n’est PAS coché. Décochez-le s’il l’est :
Paramètres de phase de compilation de la cible d'application principale
Débogage de l’extension de service de notification iOS
Suivez ces étapes pour vérifier que l’extension de service de notification est correctement configurée.
1. Mettre à jour le code OneSignalNotificationServiceExtension
Ouvrez le fichier NotificationService.m ou NotificationService.swift et remplacez tout le contenu du fichier par le code ci-dessous. (Le code est le même que notre code de configuration d’origine, en ajoutant simplement quelques journalisations supplémentaires.
Assurez-vous de remplacer YOUR_BUNDLE_ID par votre ID de bundle réel.
import UserNotifications
import OneSignalExtension
import os.log
class NotificationService: UNNotificationServiceExtension {
var contentHandler: ((UNNotificationContent) -> Void)?
var receivedRequest: UNNotificationRequest!
var bestAttemptContent: UNMutableNotificationContent?
override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
self.receivedRequest = request
self.contentHandler = contentHandler
self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
let userInfo = request.content.userInfo
let custom = userInfo["custom"]
print("Running NotificationServiceExtension: userInfo = \(userInfo.description)")
print("Running NotificationServiceExtension: custom = \(custom.debugDescription)")
//debug log types need to be enabled in Console > Action > Include Debug Messages
//Replace YOUR_BUNDLE_ID with your actual Bundle ID
os_log("%{public}@", log: OSLog(subsystem: "YOUR_BUNDLE_ID", category: "OneSignalNotificationServiceExtension"), type: OSLogType.debug, userInfo.debugDescription)
if let bestAttemptContent = bestAttemptContent {
/* DEBUGGING: Uncomment the 2 lines below to check this extension is executing
Note, this extension only runs when mutable-content is set
Setting an attachment or action buttons automatically adds this */
print("Running NotificationServiceExtension")
bestAttemptContent.body = "[Modified] " + bestAttemptContent.body
OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
}
}
override func serviceExtensionTimeWillExpire() {
// Called just before the extension will be terminated by the system.
// Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
contentHandler(bestAttemptContent)
}
}
}
2. Changer votre schéma actif
Définissez votre schéma actif sur OneSignalNotificationServiceExtension.
Sélection du schéma actif Xcode
3. Compiler et exécuter le projet
Compilez et exécutez le projet dans Xcode sur un appareil réel.
4. Ouvrir la console
Dans Xcode, sélectionnez Window > Devices and Simulators.
Fenêtre Devices and Simulators de Xcode
Vous devriez voir votre appareil connecté. Sélectionnez Open Console.
Bouton d'accès à la console de l'appareil
5. Vérifier la console
Dans la console :
- Sélectionnez Action > Include Debug Messages
- Recherchez
OneSignalNotificationServiceExtension comme CATEGORY
- Sélectionnez Start
Configuration du débogage de la console
Envoyez une notification avec un message à cet appareil (utilisez la propriété contents si vous envoyez depuis l’API Create message). Dans cet exemple, la charge utile est :
//Replace with your own app data:
//YOUR_API_KEY, YOUR_APP_ID, SUBSCRIPTION_ID_1
curl --request POST \
--url 'https://api.onesignal.com/notifications' \
--header 'Authorization: Key YOUR_API_KEY' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"app_id": "YOUR_APP_ID",
"target_channel": "push",
"headings": {"en": "The message title"},
"contents": {"en": "The message contents"},
"data":{"additional_data_key_1":"value_1","additional_data_key_2":"value_2"},
"include_subscription_ids": [
"SUBSCRIPTION_ID_1"
]
}'
Vous devriez voir un message enregistré avec l’application en cours d’exécution et non en cours d’exécution.
Exemple de sortie de débogage de la console
Si vous ne voyez pas de message, supprimez OneSignal de votre application et suivez à nouveau notre Configuration du SDK mobile pour vérifier que vous avez correctement configuré OneSignal.