Mobile push setup
Use this end-to-end checklist to set up mobile push notifications in your app with OneSignal. From SDK integration to user permissions and delivery configuration, this guide ensures a complete and successful push implementation across iOS and Android.
Overview
Push (also called remote) notifications are essential for re-engaging users when they’re not actively using your app. They can display text and rich content like images, buttons, and sounds.
Push notification examples.
For push to work on mobile:
- Your users must have your mobile app installed
- You must configure the correct platform credentials (e.g., FCM for Google Android, APNs for iOS, HMS for Huawei, ADM for Amazon)
- Users must grant permission to receive notifications
This guide walks through every step—from SDK setup to sending personalized push messages—to help you successfully implement OneSignal push notifications.
Mobile push developer guides
Before you can send mobile push notifications, your developer needs to complete the following steps.
Not a developer? See Manage Team Members to invite a teammate with developer access to your OneSignal project.
Mobile SDK setup
Integrate the OneSignal SDK into your app to register devices and enable push messaging.
Migration from another provider
Migrate from providers like Firebase, Airship, or Braze. Setup is fast and straightforward.
Ask users for permission to send push
Mobile platforms have users subscribe (aka “opt-in”) to receive push notifications. This involves displaying a prompt to users asking for permission. Apple’s Human Interface Guidelines recommends that apps “Create an alert, modal view, or other interface that describes the types of information they want to send and gives people a clear way to opt in or out.”
You can build this experience using OneSignal’s In-App Messages.
Create Push Prompt
Prompt for Push Permissions
Build a custom pre-permission prompt using In-App Messages.
Mobile SDK reference
Programmatically trigger permission requests in the SDK.
iOS Provisional Push
Show silent notifications in the notification center before prompting.
Understanding users and subscriptions
Once our SDK is active, OneSignal automatically creates user and subscription records as visitors open your app.
Mobile subscriptions are created when users:
- Open the app for the first time on a device
- Uninstall and reinstall the app on the same device, then open the app again
Important notes:
- Each device creates a separate subscription
- Mobile subscriptions remain anonymous until you assign them an External ID
Audience > Subscriptions
Users
How to manage users and assign External IDs.
Subscriptions
Understand how subscriptions are created and managed.
Segments
Group users into segments for personalized targeting.
Design push notifications
Crafting a good push notification involves more than writing text. Design matters. Learn what elements are customizable and how to use them effectively.
Mobile Push Anatomy
- Title: Attention-grabbing headline (recommended: under
50
characters) - Message: Main notification content (recommended: under
120
characters) - Icons: Your brand icon or notification-specific image
- Large Image: Eye-catching visual content
- Action Buttons: Call-to-action buttons
- Timestamp when push was received
- App name: The name of your app
Push overview
Full overview of push notification creation, options, and delivery behavior.
Templates
Save time with reusable templates for consistent messaging.
Message personalization and localization
You can customize push messages to match each user’s preferences and language.
Message Personalization
Insert dynamic variables (like name or preferences) to tailor messages.
Multi-Language Messaging
Automatically deliver messages in each user’s preferred language.
Configure mobile push behavior
Control how your notifications behave after being sent, including delivery timing, display/dismiss behavior, and user interactions.
Delivery, display, and dismiss settings
Throttling
Control notification delivery speed.
Frequency Capping
Set limits to prevent over-sending notifications to the same user.
Time To Live (TTL)
Define how long push services retain messages when the device is offline.
Collapse ID
Replace previous messages with newer ones.
Android: Notification Categories
Control importance (e.g. banner, silent) and other aspects.
iOS: Focus Modes and Interruption Levels
Control priority (e.g. passive, time-sensitive).
Notification Sounds
Configure notification audio for each platform.
Badges
Manage app icon badge behavior on iOS. Can automatically clear notifications on iOS.
Data & background notifications
Include custom data that can be accessed and handled within the app whether sending displayable or data/background notifications.
Data & background notifications
Send custom payloads without a visual notification.
Additional data
Learn how to use additional key-value data in push payloads.
Click behavior & deep linking
Control what happens when a user clicks a notification.
URLs, Links, & Deep Linking
Route users to relevant content or pages using deep links and tracking.
Deep linking
Detailed information about deep linking.
Action buttons
Let users take immediate actions from your notification.
SDK Notification Event Observer
Listen for click events and trigger in-app behavior with custom code.
Push analytics and troubleshooting
Measure and improve notification performance:
Push message reports
View delivery, open rate, and click-through metrics for each message.
Analytics overview
Explore engagement and user behavior metrics across channels.
Notifications not shown or delayed
Troubleshooting checklist if messages aren’t appearing.
Notification images not showing
Fix image rendering issues across different browsers.
Duplicate notifications
Troubleshoot why duplicate notifications are being displayed.
Congratulations! Your mobile push notification setup is complete.
Next steps:
- A/B Testing: Optimize messages with experiments
- Journeys: Build automated messaging flows
- Tags: Add user-level data for targeting
- Analytics: Track engagement and conversion metrics
- In-app messages: Reach users in your app