Setting up push notifications for your Unity app using OneSignal

Integrating push notifications into your Unity app is a powerful way to enhance user engagement and keep your audience connected with timely updates. This guide walks you through setting up OneSignal's Unity SDK, which provides seamless support for Unity3d push notifications across major platforms like APNS (Apple Push Notification Service) and Firebase Cloud Messaging (FCM). By adding push notifications, you can drive deeper user retention and engagement in your Unity apps, ensuring your messages reach users reliably and in real-time.

Why add push notifications to your Unity app?
Push notifications play a crucial role in creating a direct communication channel with users, whether for Unity games or other interactive experiences built on Unity3d. OneSignal’s SDK makes it easy to add Unity push notifications to Unity apps for iOS, Android, Amazon, and Huawei and gives you access to advanced delivery, targeting, and customization options.

Requirements

• Unity 2021.3 or newer
• iOS: iOS 11+ or iPadOS 11+ device (iPhone, iPad, iPod Touch) to test on. Xcode 14+ simulator works running iOS 16+
• iOS: mac with Xcode 12+
• Android: Android 5.0+ device or emulator with "Google Play Store (Services)" installed
• Configured OneSignal App and Platform

Preparing your Unity app for push notifications

Before you can enable push notifications, it's crucial to ensure that your app is correctly configured to work with either Apple Push Notification Service (APNS), Firebase Cloud Messaging (FCM), Huawei Pushkit, or Amazon Fire (ADM). If you have not done so already, follow the configuration steps below to set up your OneSignal account, configure necessary permissions in OneSignal, and register any necessary device-specific certificates.

Configure your OneSignal app and platform

If your team already created an account with OneSignal, ask to be invited as an admin role so you can setup the app. Otherwise, sign up for a free account at onesignal.com to get started!

Details on configuring your OneSignal app (click to expand)

You can setup multiple platforms (iOS, Android, Web, Email, SMS) within the same OneSignal App under Settings > Platforms. If you want to create a new app select New App/Website. If this is your first OneSignal app, you will see the next page.

Name your app and organization something recognizable, then select the platform to setup. You can always set up more platforms in this OneSignal App later within Settings > Platforms.

Click Next: Configure Your Platform.

To configure your app, follow the prompts based on the platforms you support.

• Android: Set up your Android Firebase Credentials
• iOS: p8 Authentication Token or p12 Push Notification Certificate
• Amazon: Generate an Amazon API Key
• Huawei: Authorize OneSignal to send Huawei Push

After you setup your credentials, click Save & Continue.

Choose your Apps Target SDK, the click Save & Continue.

Finally, you will be directed to install the SDK and provided your OneSignal App ID. Make sure to save your App ID as you will need it later.

If you need a teammate or your developer to assist, you can click Invite them to the app and select Done when finished.

Continue through the documentation to finish adding OneSignal to your app.

Setup

1. Add SDK

There are two methods available for installation of the OneSignal Unity SDK.

📘

Upgrading from 2.13.4 or older

It is recommended to use the Asset Store path for installation if you are upgrading from a version of the OneSignal Unity SDK 2.13.4 or older.

2. iOS setup

After building in Unity open the Xcode Workspace and follow these setups.

Click on "Unity-iPhone" on the left and select the "Signing & Capabilities" tab.

If you'd like to make provisioning your app easier, you can check "Automatically manage signing", on the prompt click "Enable Automatic", and select your Team. Otherwise you can do this manually.

Scroll down to "App Groups" and click on the refresh button.
- NOTE: You may have to press this a few times as it will ask you for each signing type.

Repeat the same steps above but for the "OneSignalNotificationServiceExtension" target this time.

"App Groups" should now be provisioned for you going forward for your iOS bundle id, even on clean builds.

3. Android setup

From the Unity Editor, navigate to Edit > Project Settings > Player and click the Android settings tab.

Expand Publishing Settings and enable:

• Custom Main Gradle Template
• Custom Gradle Properties Template

Navigate to Assets > External Dependency Manager > Android Resolver > Force Resolve and resolve your Android dependencies.

• In versions 5.0.6 and higher, Android builds must have a Target API Level of 33 or higher.
• Android builds with Minify enabled only work with OneSignalConfig.androidlib available in versions 5.0.3 and higher. Run the "Copy Android plugin to Assets" step in Window > OneSignal SDK Setup to create OneSignalConfig.androidlib.

The only thing remaining is to setup your own notification icons. You can do this be replacing the example icons located at Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res with your own. The file names must be lowercase and cannot contain anything else except underscores and numbers. See our Customize Notification Icons for more details.

• In versions 5.0.2 and lower, custom notification icons are located in Assets/Plugins/Android/OneSignalConfig.plugin/res.
  In versions 5.0.3 and higher, OneSignalConfig.plugin has been changed to OneSignalConfig.androidlib. Custom notification icons are now located in Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res. Run the "Copy Android plugin to Assets" step in Window > OneSignal SDK Setup to migrate.

Amazon FireOS (ADM) setup

Only required if you plan to release your app on the Amazon App Store to support Kindle Fire devices.

Open Plugins/Android/AndroidManifest.xml.

If you don't have one, create this file with the following contents and then skip to step 7.5.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<manifest xmlns:amazon="http://schemas.amazon.com/apk/res/android" xmlns:android="http://schemas.android.com/apk/res/android" android:installLocation="auto" package="COM.YOUR.PACKAGE_NAME" platformBuildVersionCode="23" >
    <supports-screens android:anyDensity="true" android:largeScreens="true" android:normalScreens="true" android:smallScreens="true" android:xlargeScreens="true"/>
    <application android:debuggable="false" android:icon="@drawable/app_icon" android:isGame="true" android:label="@string/app_name" android:theme="@style/UnityThemeSelector">
        <activity android:configChanges="locale|fontScale|keyboard|keyboardHidden|mcc|mnc|navigation|orientation|screenLayout|screenSize|smallestScreenSize|touchscreen|uiMode" android:label="@string/app_name" android:launchMode="singleTask" android:name="com.unity3d.player.UnityPlayerActivity" android:screenOrientation="fullSensor">
            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
                <category android:name="android.intent.category.LEANBACK_LAUNCHER"/>
            </intent-filter>
            <meta-data android:name="unityplayer.UnityActivity" android:value="true"/>
        </activity>
        
        <amazon:enable-feature android:name="com.amazon.device.messaging" android:required="false"/>
        <service android:name="com.onesignal.notifications.services.ADMMessageHandler" android:exported="false" />
        <service android:name="com.onesignal.notifications.services.ADMMessageHandlerJob"
           android:permission="android.permission.BIND_JOB_SERVICE"
           android:exported="false" />
        <receiver android:name="com.onesignal.notifications.receivers.ADMMessageReceiver"
                  android:permission="com.amazon.device.messaging.permission.SEND" >
          <intent-filter>
            <action android:name="com.amazon.device.messaging.intent.REGISTRATION" />
            <action android:name="com.amazon.device.messaging.intent.RECEIVE" />
            <category android:name="COM.YOUR.PACKAGE_NAME" />
          </intent-filter>
        </receiver>
    </application>
    <uses-feature android:glEsVersion="0x20000"/>
    <uses-feature android:name="android.hardware.touchscreen" android:required="false"/>
    <uses-feature android:name="android.hardware.touchscreen.multitouch" android:required="false"/>
    <uses-feature android:name="android.hardware.touchscreen.multitouch.distinct" android:required="false"/>
    
    <uses-permission android:name="com.amazon.device.messaging.permission.RECEIVE" />
    <permission android:name="COM.YOUR.PACKAGE_NAME.permission.RECEIVE_ADM_MESSAGE" android:protectionLevel="signature" />
    <uses-permission android:name="COM.YOUR.PACKAGE_NAME.permission.RECEIVE_ADM_MESSAGE" />
</manifest>

Add xmlns:amazon="http://schemas.amazon.com/apk/res/android" in the manifest tag right after the xmlns:android property.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:amazon="http://schemas.amazon.com/apk/res/android"
    package="COM.YOUR.PACKAGE_NAME"
    android:versionCode="1"
    android:versionName="1.0" >

Add the following permissions.

<uses-permission android:name="com.amazon.device.messaging.permission.RECEIVE" />
<permission android:name="COM.YOUR.PACKAGE_NAME.permission.RECEIVE_ADM_MESSAGE" android:protectionLevel="signature" />
<uses-permission android:name="COM.YOUR.PACKAGE_NAME.permission.RECEIVE_ADM_MESSAGE" />

In the application tag add the following.

<application>
  <amazon:enable-feature android:name="com.amazon.device.messaging" android:required="false"/>

  <service android:name="com.onesignal.notifications.services.ADMMessageHandler" android:exported="false" />
  <service android:name="com.onesignal.notifications.services.ADMMessageHandlerJob"
           android:permission="android.permission.BIND_JOB_SERVICE"
           android:exported="false" />
  <receiver android:name="com.onesignal.notifications.receivers.ADMMessageReceiver"
            android:permission="com.amazon.device.messaging.permission.SEND" >
    <intent-filter>
      <action android:name="com.amazon.device.messaging.intent.REGISTRATION" />
      <action android:name="com.amazon.device.messaging.intent.RECEIVE" />
      <category android:name="COM.YOUR.PACKAGE_NAME" />
    </intent-filter>
  </receiver>
</application>

Replace all 3 of instances of COM.YOUR.PACKAGE_NAME with your package name in AndroidManifest.xml.

Place your api_key.txt under Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/assets

To create an api_key.txt for your app follow our Generate an Amazon API Key Guide.

4. Initialization

To get started add the following code in an appropriate place such as the Start method of a MonoBehaviour early in your application's lifecycle.

using OneSignalSDK;

void Start () {
  // Replace 'YOUR_ONESIGNAL_APP_ID' with your OneSignal App ID from app.onesignal.com
  OneSignal.Initialize("YOUR_ONESIGNAL_APP_ID");
}

Replace "YOUR_ONESIGNAL_APP_ID" with your OneSignal App ID.

5. Testing

Run your app on a physical device to make sure it builds correctly.

If you used the provided code, then the requestPermission method, should prompt you to subscribe to push notifications. You can always change this later but for now, click "Allow" to subscribe to push notifications.

Check your OneSignal Dashboard Audience > Subscriptions to see your Subscription and click the options button on the left to set yourself as a Test Subscription.

📘

Troubleshooting

If you run into any issues please see our Unity troubleshooting guide.

Try the example project on our Github repository.

If stuck, contact support directly or email [email protected] for help.

For faster assistance, please provide:

• Your OneSignal App Id
• Details, logs, and/or screenshots of the issue.
• Steps to reproduce

Users & subscriptions

Required if using integrations.
Recommended for messaging across multiple channels (push, email, sms).

If you need user consent before tracking their data. OneSignal provides user consent methods to help delay initialization of our SDK until consent is provided. See Handling Personal Data for details.

External ID & aliases

When a user downloads and opens your mobile app or uninstalls and re-installs your app on the same device, a Subscription and a User is created within the OneSignal app.

You can identify that user across multiple subscriptions by setting the External ID property. The External ID should be distinct user ID representing a single user. We recommend using the same user ID as in your Integrations or main analytics tool.

When you authenticate users in your app, call our login method at any time to link this subscription to a user.

string externalUserId = "123456789" // You will supply the external user id to the OneSignal SDK

OneSignal.Login(externalUserId);

Our mobile SDKs have methods for detecting User state changes that might be helpful for internal tracking.

📘

External ID & custom aliases

If your users have multiple user IDs, we do support additional custom Aliases. However, you should still always set the External ID as this is the main alias we use to identify users. See Users for details.

Add email and phone number subscriptions

Recommended if using email and SMS messaging.

Like push subscriptions, email addresses and phone numbers each are a new subscription within OneSignal. Your email and sms subscriptions will be tied to the same user if created using our SDK or if you setting the External ID. You can Import your current user data and use our APIs and/or SDK methods to capture new email addresses and phone numbers when provided to you by your users.

OneSignal.User.AddEmail("[email protected]");

OneSignal.User.AddSms("+12345556789");

📘

Users & subscriptions

See Users and Subscriptions for more details.

Property & event tags

Tags are custom key : value pairs of String data used for tracking any custom user events and properties. Setting tags is required for more complex Segments and Message Personalization.

For event triggered messages, use tags with Time Operators to note the date and time the event is/occurred and setup automations for sending to those users. See Abandoned Cart Example for details.

OneSignal.User.AddTag("tagName", "tagValue");

📘

Data tags

If you want to store custom data within OneSignal for segmentation, message personalization, and event triggered automation, see Tags for details.

Importing users and subscriptions

If you have a list of user data from a previous source, you can import it into OneSignal following our Import guides.

Message configuration

Common setup items to get the most of your integration.

Deep linking

See our Deep Linking guide to set those up for push and other messaging channels.

👍

Basic SDK setup complete!

For details on the above methods and other methods available, see our Mobile SDK reference.