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.
- 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.
Unity Asset Store (click to expand)
-
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.
-
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.
-
On the SDK's listing in the Editor click the Download button. When it finishes click Import.
-
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.
-
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"
-
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)
-
From within the Unity Editor navigate to Edit > Project Settings and then to the Package Manager settings tab.
-
Create a New Scoped Registry by entering
Name npmjs URL https://registry.npmjs.org Scope(s) com.onesignal
and click Save.
-
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. -
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"
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 createOneSignalConfig.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 toOneSignalConfig.androidlib
. Custom notification icons are now located inAssets/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.
- See Data Tags for more details.
OneSignal.User.AddTag("tagName", "tagValue");
Setup Complete!
Visit Mobile Push Tutorials for next steps.
Updated 13 days ago