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!

For push notifications to work, your users need your mobile app, a unique device identifier for each user, and proper configuration with platforms like Firebase (for Android) or APNs (for iOS). Additionally, users must grant permission to receive your notifications on their devices.

This guide will walk you through setting up mobile push notifications with OneSignal, including integrating our SDK into your app, configuring necessary settings for iOS and Android, and testing your setup to ensure everything works seamlessly. Whether you’re new to push notifications or transitioning from another provider, this documentation provides all the resources and steps needed to get started quickly and effectively.

By the end of this setup process, you'll be able to send personalized and targeted push notifications to your users, helping to improve retention, boost user engagement, and achieve your business goals.

---

Migration to OneSignal from other provider

If you are moving to OneSignal from another service and already have mobile push notifications setup, then migration should be quick! See Migrating to OneSignal from another service for details.

---

Add our SDK to your app

Add the OneSignal code into your mobile app to start getting push subscribers and handle notifications. This may require some developer assistance.

🔨

Developers: Mobile SDK setup guides

Follow our Mobile SDK setup docs to add our code to your mobile app.

If you are not a developer, see Manage Team Members to invite them as admins to your app and share this guide!

You can continue following the steps below to configure notifications while your developer sets up the SDK.

---

Ask permission to send push notifications

Your users need to 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 create custom views using our In-App Messages and style them to fit your app or use our out-of-the-box templates. Navigate to Messages > In-App.

Then click the Push Permission Prompt or New Message to get started.

📘

How to prompt for push permissions

Follow this guide to start designing your Prompt for Push Permissions.

Developers, you can explicitly request permission with code using our requestPermission method in our Mobile SDK and Web SDK.

iOS also provides Provisional Push Notifications which do not require prompting the user 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.

---

Users & mobile push subscriptions

As users download and open your mobile app with the OneSignal SDK active, a Subscription record and a User record is created for that device.

Mobile push subscriptions are created when users install your app on a new device and when they uninstall and re-install your app on the same device.

Users are considered anonymous until you set your own External ID to identify the user across all their subscriptions.

📘

Users, subscriptions, & segments

Please review our Users and Subscriptions docs for more details.

Once you start accumulating users, you can group them into Segments.

---

Design push notifications

Start building reusable push Templates or just start sending push to your subscribers. This section details the designing of push notifications.

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

📘

Sending push notifications

See our Messages > Push guide for details on sending and designing push notifications or Templates for details on creating reusable push designs.

---

Configure notification behavior

You can control some aspects of the notification's display and click behavior such as how long the push will be held by the push services (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.

Remove notifications from view

• Badges: Our SDK provides automatic badge management on iOS which also removes notifications. Follow our Badges guide to update Badge and notification clearing behavior on iOS.
• Time To Live (TTL): The amount of time a push notification will be held by the push services (FCM, APNS, HMS, etc) if the user's device is offline. Defaults to 3 days. Range: 0–2,419,200 seconds (28 days).
• Collapse ID: Replaces Notifications already present on the subscriber's device if the current notification contains the same collapse_id.

Data & background notifications

Push notifications can be sent with custom additional data that can be accessed and handled within the app. Commonly used to pass data with Data & background notifications or customizations in displayable notifications.

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.

🔨

Developers: Setup your deep links to work with push!

Deep linking allows you to direct users to specific pages of your app to take action, such as making a purchase on a checkout page!

Deep linking can be complicated because there are multiple ways to set it up. For details, see our Deep Linking guide.

---

👍

Send your push messages!

You should now be setup and ready to send push notifications to your mobile app subscribers.

See our Push guide to get started!