Unity SDK Setup

Instructions for adding the OneSignal Unity SDK to your Unity app for iOS, Android, Amazon, and Huawei

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

Configure your OneSignal App and Platform

Details on configuring your OneSignal App and Platform (click to expand)

If you haven't already, sign up for a free account on onesignal.com.

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.

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.

Unity Asset Store (click to expand)
  1. Add the OneSignal Unity SDK as an available asset to your account by clicking Add to My Assets from our listing on the Unity Asset Store.

  2. Find the package waiting for you to download by clicking Open in Unity from that same page. This will open the Unity Editor and its Package Manager window.

  3. On the SDK's listing in the Editor click the Download button. When it finishes click Import.

    onesignal unity sdk in my assets

  4. A prompt to import all of the files of the OneSignal Unity SDK will appear. Click Import to continue and compile the scripts into your project.

  5. Navigate to Window > OneSignal SDK Setup (or follow the popup if upgrading) in the Unity Editor which will bring up a window with some final steps which need to be completed in order to finalize the installation. The most important of these steps is Import OneSignal packages.

    Depending on your project configuration and if you are upgrading from a previous version, some of these steps may already be marked as "completed"

    sdk setup steps window

  6. After importing the packages Unity will notify you that a new registry has been added and the OneSignal SDK Setup window will have refreshed with a few additional
    steps. Following these will finalize your installation of the OneSignal Unity SDK.

Unity Package Manager (click to expand)
  1. From within the Unity Editor navigate to Edit > Project Settings and then to the Package Manager settings tab.

    unity registry manager

  2. Create a New Scoped Registry by entering

    Name        npmjs
    URL         https://registry.npmjs.org
    Scope(s)    com.onesignal
    

    and click Save.

  3. Open the Window > Package Manager and switch to My Registries via the Packages: dropdown menu. You will see all of the OneSignal Unity SDK packages available
    on which you can then click Install for the platforms you would like to include. Dependencies will be added automatically.

  4. Once the packages have finished importing you will find a new menu under Window > OneSignal SDK Setup. Open it and you will find some final steps which need to be completed
    in order to finalize the installation.

    Depending on your project configuration and if you are upgrading from a previous version, some of these steps may already be marked as "completed"

    my registries menu selection

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 in a new folder named assets under Assets/Plugins/Android/

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. Note that the iOS Simulator does not support receiving remote push notifications.

  • Android and iOS devices should be prompted to subscribe to push notifications if you used the example setup code provided.

Check your OneSignal Dashboard Audience > All Subscriptions to see your Device Record.

Then head over to Messages > New Push to Send your first Push Notification from OneSignal.

Please note that Identity Verification is coming soon to v5 of the Unity SDK.

📘

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

Recommended

Push permission with In-App Message

You can continue to opt-in users to push via the requestPermission method. 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."

OneSignal provides In-App Messages to meet this recommendation and create a better user experience. This also permits you to ask for permission again in the future, since the native permission prompt is limited to how many times it can show and cannot be shown again if the user clicks deny.

See How to Prompt for Push Permissions with In-App Messages for details on implementing this.

Identify Users

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

OneSignal creates subscription-level records under a unique ID called the subscription_id. A single user can have multiple subscription_id records based on how many devices, email addresses, and phone numbers they use to interact with your app.

If your app has its own login system to track users, call login at any time to link all channels to a single user. For more details, see Aliases & External ID.

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

OneSignal.Login(externalUserId);

Set Email & Phone Number

Recommended for messaging across multiple channels (push, email, sms).

Use the provided SDK methods to capture one or more email/phone numbers for the user. Follow the channel quickstart guides for setup:

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

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

Add Data Tags

Optional

Tags are custom key : value pairs of String data used for tracking user events and properties. Setting tags is required for more complex segmentation and message personalization.

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

👍

Setup Complete!

Visit Mobile Push Tutorials for next steps.