​
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

  1. Title: Attention-grabbing headline (recommended: under 50 characters)
  2. Message: Main notification content (recommended: under 120 characters)
  3. Icons: Your brand icon or notification-specific image
  4. Large Image: Eye-catching visual content
  5. Action Buttons: Call-to-action buttons
  6. Timestamp when push was received
  7. 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: