Push (aka remote) notifications are the standard for getting your user's attention and sharing important information when they are not actively using your mobile app or website. They can display text, images, buttons, play sounds, and more!

Get started by add our Mobile SDK to your mobile app. Share this with your developer!

Native SDKs

Google Android Native

iOS Native

Huawei Android Native

Cross-platform SDKs

Unity

React Native & Expo

Cordova

Ionic & Ionic Capacitor

Flutter

.NET MAUI

Ask permission to send push notifications

Users need to subscribe (aka "opt-in") to receive push notifications.

You can explicitly request permission using OneSignal's requestPermission method in our Mobile SDK and Web SDK. However, 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." To meet this recommendation, OneSignal provides In-App Messages which you can use to provide a better user experience. See How to Prompt for Push Permissions with In-App Messages for details on implementing this.

iOS also provides Provisional Push Notifications which do not require the user to subscribe to push notifications but have limitations like 1) they cannot play a sound, 2) cannot "pop-up" or display anywhere besides within the device's Notification Center and more.

Identify your users & subscriptions

As users subscribe to push notification, they are assigned a OneSignal ID (OneSignal's User ID) and Subscription ID (OneSignal's unique channel/device ID). The user is considered anonymous until you set your own External ID to identify the user across all their subscriptions.

See Users and Subscriptions for more details.

Push notification design

Customize the look of your notifications including the icons, images, action buttons, and more following these guides:

1. Title

The top-most customizable text of the notification. Push notifications do not support custom fonts or styling such as bold, italics or underlines. The style is set by the operating system.

Around 25-50 character limit.
Supports: Emojis 👍, Message Personalization, Language & Localization
API: headings

2. Message

The localized text the provides the notification's main content. Push notifications do not support custom fonts or styling such as bold, italics or underlines. The style is set by the operating system.

Around 150 characters limit.
Supports: Emojis 👍, Message Personalization, Language & Localization
API: contents

3. Icons

The best way for users to recognize your app.

Android, Amazon, Huawei provides Small and Large Icons. See Notification Icons.
- API: small_icon & large_icon
iOS sets the icon based on your app's default icon.
- Android and iOS also support Conversation Notifications (Android) and Communication Notifications (iOS) that allow you to change the icon to the user's profile image.

4. Large image

Show an image that expands with the notification. See Images & Rich Media for details.

Recommended image size: 1440x720 pixels or 2:1 aspect ratio.
Filetype support: PNG, JPG, GIF*
- Only iOS supports animated GIF. Android, Amazon, Huawei GIF frozen on first frame.
API: ios_attachment (iOS) & big_picture (Android)

5. Action Buttons

Customizable buttons to perform a custom action. See Action Buttons for details.

API: buttons

6. Timestamp

Set by the device when the message was received.

7. App Name

iOS: The Display Name in Xcode. If updated, users must restart the device to see this change take effect.
Android, Amazon, Huawei: The <application android:label="YOUR APP NAME"> in the AndroidManifest.xml

Notification properties and behavior

You can control some aspects of the notification's display behavior such as how long the push will be held by FCM/APNS when the device is offline, collapsing notifications, and more.

Display behavior

Set a recommended behavior for how the notification should visually show up while the user is looking at the device. You can also control Notification Sounds.

Android: Notification Channel Categories sets the Importance of the notification to display as a "heads up" or "banner" type or go straight to Notification Center.
iOS: Focus Modes and Interruption Levels sets the Interruption level of the notification to display as a "heads up" or "banner" type or go straight to Notification Center.

Removing notifications from view

Time To Live: How long the push is saved on the FCM/APNS/WNS servers if the subscriber's device is offline. See Remove Notifications and TTL for details.
- API: ttl
Collapse ID: Replaces Notifications already present on the subscriber's device if the current notification contains the same collapse_id. See Remove Notifications and TTL for details.
- API: collapse_id

Click behavior

By default, clicking a notification will open your app. You can customize where you send the subscriber to a customer URL or view within the app. See URLs, Links and Deep Links for details.

Notification payload, background and data notifications

Push notification payloads cannot exceed 4096 bytes of data. Additional data cannot exceed 2048 bytes of the 4096 bytes allowed. Each platform has different data limits. The total character limit is based on the body, title, and any images or custom data you add. Generally, the limit can be 3500 characters. See OSNotification Payload for all properties.

Also known as "silent notifications", data/background notifications do not appear visually or audibly to the user and are generally used for background data refresh. See Data & Background Notifications for more details.

Additional Data : Non-visible data that may accompany a message payload and accessed within the SDK.
- API: data

FAQ

Why are notifications not displaying correctly?

If notifications are not displaying at all, see Notifications Not Shown - Mobile Push.