> ## 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.
# Mobile push setup
> End-to-end checklist for setting up mobile push notifications with OneSignal across iOS, Android, Huawei, and Amazon.
Push notifications re-engage Users when they're not actively using your app. They can display text and rich content like images, buttons, and sounds.
For push to work on mobile:
* Users must have your mobile app installed
* You must configure the correct platform credentials (FCM for 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.
***
## SDK setup and migration
Integrate the OneSignal SDK into your app to register devices and enable push messaging. If you're migrating from another provider, OneSignal supports migration from Firebase, Airship, Braze, and others.
Integrate the OneSignal SDK into your app to register devices and enable push messaging.
Migrate from Firebase, Airship, Braze, or other push providers.
***
## Push permission prompts
Mobile platforms require Users to opt in before they can receive push notifications. Apple's [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/ios/system-capabilities/notifications) recommend describing what types of information you want to send and giving Users a clear way to opt in or out.
You can build a pre-permission prompt using OneSignal's in-app messages to explain the value before triggering the system prompt.
Build a custom pre-permission prompt using in-app messages.
Programmatically trigger permission requests in the SDK.
Show silent notifications in the notification center before prompting.
***
## Users and Subscriptions
Once the SDK is active, OneSignal automatically creates User and Subscription records as people open your app.
Mobile Subscriptions are created when Users:
* Open the app for the first time on a device
* Uninstall and reinstall the app, then open it again
Each device creates a separate Subscription. Subscriptions remain anonymous until you assign them an [External ID](./users#external-id) via `OneSignal.login`.
Manage Users, assign External IDs, and understand anonymous vs. identified Users.
How Subscriptions are created and managed across devices and channels.
Group Users into dynamic segments for targeted messaging.
***
## Design push notifications
Crafting effective push notifications involves more than text. Watch how to make every push notification count, then explore the design elements below.
1. [Title](./push#title): Attention-grabbing headline (recommended: under 50 characters)
2. [Message](./push#message): Main notification content (recommended: under 120 characters)
3. [Icons](./notification-icons): Your brand icon or notification-specific image
4. [Large image](./push#image): Eye-catching visual content
5. [Action buttons](./action-buttons): Call-to-action buttons
6. Timestamp when push was received
7. [App name](./push#app-name): The name of your app
Full overview of push notification creation, options, and delivery behavior.
Save time with reusable templates for consistent messaging.
### Personalization and localization
Watch how to turn generic push notifications into high-performing messages, then explore the personalization options below.
Insert dynamic variables like name or preferences to tailor messages.
Automatically deliver messages in each User's preferred language.
***
## Configure push behavior
Control how notifications behave after delivery, including timing, display settings, and User interactions.
### Delivery, display, and dismiss settings
Control notification delivery speed for large audiences.
Set limits to prevent over-sending notifications to the same User.
Define how long push services retain messages when the device is offline.
Replace previous messages with newer ones to reduce notification clutter.
Control importance level (banner, silent) and other display aspects.
Control priority level (passive, time-sensitive) for iOS.
Configure notification audio for each platform.
Manage app icon badge count behavior on iOS.
### Data and background notifications
Include custom data in push payloads that your app can handle without displaying a visible notification.
Send custom payloads without a visual notification.
Attach key-value data to push payloads for in-app handling.
### Click behavior and deep linking
Control what happens when a User taps a notification.
Route Users to relevant content or pages using deep links and tracking URLs.
Platform-specific deep linking implementation details.
Let Users take immediate actions from your notification.
Listen for click events and trigger in-app behavior with custom code.
***
## Analytics and troubleshooting
Measure notification performance and resolve common delivery issues.
View delivery, open rate, and click-through metrics for each message.
Explore engagement and User behavior metrics across channels.
Troubleshooting checklist if messages aren't appearing on devices.
Fix image rendering issues across platforms.
Troubleshoot why duplicate notifications are being displayed.
***
## Next steps
Optimize messages with experiments to find what drives engagement.
Build automated, multi-step messaging flows triggered by User behavior.
Add User-level data for personalization and targeting.
Reach Users with rich, interactive messages inside your app.
***
## FAQ
### Do Users need to opt in for push notifications?
Yes. Both iOS and Android require Users to grant permission before they can receive push notifications. On iOS, you must show the system prompt. On Android 13+, the `POST_NOTIFICATIONS` permission is required. Use a [pre-permission prompt](./prompt-for-push-permissions) to explain the value before triggering the system dialog.
### What are FCM, APNs, HMS, and ADM?
These are platform-specific push delivery services. **FCM** (Firebase Cloud Messaging) delivers to Android and web. **APNs** (Apple Push Notification service) delivers to iOS and macOS. **HMS** (Huawei Mobile Services) delivers to Huawei devices. **ADM** (Amazon Device Messaging) delivers to Amazon Fire devices. You configure credentials for each in the OneSignal dashboard during [SDK setup](./mobile-sdk-setup).
### Why aren't my push notifications showing?
Common causes include missing or expired platform credentials, Users not granting permission, or device-level settings like Do Not Disturb or Focus modes. See [Notifications not shown or delayed](./notifications-show-successful-but-are-not-being-shown) for a full troubleshooting checklist.
### Can I send push notifications without a visible notification?
Yes. Use [data and background notifications](./data-notifications) to send custom payloads that your app handles silently. These are useful for triggering background syncs, updating local data, or refreshing content without interrupting the User.
For push to work on mobile:
* Users must have your mobile app installed
* You must configure the correct platform credentials (FCM for 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.
***
## SDK setup and migration
Integrate the OneSignal SDK into your app to register devices and enable push messaging. If you're migrating from another provider, OneSignal supports migration from Firebase, Airship, Braze, and others.
1. [Title](./push#title): Attention-grabbing headline (recommended: under 50 characters)
2. [Message](./push#message): Main notification content (recommended: under 120 characters)
3. [Icons](./notification-icons): Your brand icon or notification-specific image
4. [Large image](./push#image): Eye-catching visual content
5. [Action buttons](./action-buttons): Call-to-action buttons
6. Timestamp when push was received
7. [App name](./push#app-name): The name of your app