For a full reference of the notification payload structure, see OSNotification payload.
Android notification service extension
The Android notification service extension allows you to process notifications before they are shown to the user. Common use cases include:- Receiving data in the background with or without displaying a notification
- Overriding notification settings based on client-side app logic, such as custom accent color, vibration pattern, or other
NotificationCompatoptions
Step 1: Create a class for the service extension
Create a class that implementsINotificationServiceExtension and its onNotificationReceived method.
The onNotificationReceived method receives an event parameter of type INotificationReceivedEvent.
The
@Keep annotation is required in both Java and Kotlin to prevent code shrinking tools (R8 or ProGuard) from renaming or removing your class when minification is enabled.Step 2: Customize the notification
Add your customization logic inside theonNotificationReceived method before registering the extension. The following tabs show common patterns.
- Prevent display
- Add a custom field
- Change color and icon
Use
event.preventDefault() to suppress automatic display, then call display() after performing async work.Step 3: Add the service extension to your AndroidManifest.xml
Add the class name and value asmeta-data within the <application> tag of your AndroidManifest.xml file. Ignore any “unused” warnings.
XML
com.onesignal.example.NotificationServiceExtension with your class’s fully qualified name.
iOS notification service extension
TheUNNotificationServiceExtension allows you to modify push notification content before it is displayed. It is required for:
- Images & rich media
- Confirmed receipt
- Badges
- Action buttons
- Influenced opens with Firebase Analytics
Getting the iOS push payload
Inside yourdidReceive(_:withContentHandler:) override, you call OneSignalExtension.didReceiveNotificationExtensionRequest to let OneSignal process the notification and invoke the content handler. Read or modify bestAttemptContent before calling this method.
In this example, a notification is sent with the following data:
JSON
data within the OneSignalNotificationServiceExtension via the a key inside the custom dictionary of userInfo:
Troubleshooting the iOS notification service extension
Use this section to debug issues with images, action buttons, or confirmed deliveries not showing on iOS.Check your Xcode settings
In General > Targets, verify that your main app target and OneSignalNotificationServiceExtension target have the same:- Supported Destinations
- Minimum Deployment (iOS 14.5 or higher)


NSExtension key and verify it contains:
XML

Turn off “Copy only when installing”
Select your main app target > Build Phases > Embed App Extensions. Ensure “Copy only when installing” is not checked:
Debugging the iOS notification service extension
Follow these steps to verify the notification service extension is set up correctly.1. Update the OneSignalNotificationServiceExtension code
OpenNotificationService.m or NotificationService.swift and replace the file contents with the code below. This adds logging to help verify the extension is running.
Replace YOUR_BUNDLE_ID with your actual Bundle ID.
Debug log types need to be enabled in Console via Action > Include Debug Messages.
2. Change your active scheme
Set your Active Scheme toOneSignalNotificationServiceExtension.

3. Build and run the project
Build and run the project in Xcode on a real device.4. Open the console
In Xcode, select Window > Devices and Simulators.

5. Check the console
In the Console:- Select Action > Include Debug Messages
- Search for
OneSignalNotificationServiceExtensionas the CATEGORY - Select Start

contents property if sending from the Create notification API). Example payload:
cURL

FAQ
Why isn’t my notification service extension running on iOS?
The extension only runs whenmutable-content is set in the push payload. OneSignal sets this automatically when you include an attachment or action buttons. Verify your Xcode settings match the requirements in the troubleshooting section.
Can I prevent a notification from displaying on Android?
Yes. Callevent.preventDefault() in your onNotificationReceived method to suppress automatic display. You can then call event.getNotification().display() to show it later, or never call display() to silently drop the notification without displaying it. See Duplicated notifications for details on avoiding duplicates when using this pattern.
Do I need the @Keep annotation on Android?
Yes. The@Keep annotation prevents ProGuard or R8 from renaming or removing your class that implements INotificationServiceExtension during minification. Without it, OneSignal cannot find the class at runtime.
Related pages
Mobile SDK setup
Install and configure the OneSignal SDK for iOS and Android.
Images & rich media
Attach images, GIFs, and video to push notifications.
Confirmed receipt
Track confirmed notification delivery to devices.
Duplicated notifications
Troubleshoot duplicate push notifications on all platforms.