Guides
Log InSign Up

Mobile push setup

Setup push notifications for your mobile app with OneSignal.

Suggest Edits

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! Follow the below migration steps and continue on with the setup guide.

Migration steps (click to expand)
  1. Evaluate your current provider setup.
    1. Audit your current push provider’s setup (e.g., platforms supported, messaging history, API usage).
  2. Configure your app to replace the current provider's code with OneSignal.
    1. Having multiple push notification related SDKs in your app may cause unexpected behavior like duplicate notifications or regenerating push tokens unnecessarily.
      1. We have a "custom" object in our push payload our SDK checks first before displaying the notification, but your other push provider may not and try to display notifications sent from OneSignal.
  3. Migrate User and Subscription data.
    1. Once you implement the steps in this guide, your mobile push Subscriptions will automatically start showing up in OneSignal once those Users update the app.
    2. You can import user and subscription data with the Create user API, but please review the Subscriptions doc 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:


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.

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.

3. Icon

The best way for users to recognize your app.

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.

5. Action buttons

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

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

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.

Remove 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.
  • 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.

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!

Updated about 1 month ago