Step 1. Requirements
- A OneSignal Account.
- Your OneSignal App ID, available in Settings > Keys & IDs.
- Unity 2018.4 or newer.
iOS Requirements
- An iOS device (iPhone, iPad, iPod Touch) to test on. The Xcode simulator doesn't support push notifications so you must test on a real device.
- A Mac with Xcode 12+.
- An iOS Push Certificate.
Android Requirements
- An Android 4.0.3+ device or emulator with "Google Play Store (Services)" installed.
- A Google/Firebase Server API Key.
Amazon & Huawei Requirements
Follow these instructions if your app is distributed on the Amazon AppStore and/or the Huawei AppGallery.
Step 2. Import the OneSignal Unity Plugin
2.1 Download the latest OneSignal release and extract OneSignalSDK.unitypackage.
2.2 Open your Unity project, double click on OneSignalSDK.unitypackage, and press "Import".
Step 3. Initialize OneSignal in your Unity scene
3.1 In the first scene that is loaded when your game is opened, add the following code to an object that is enabled in the scene.
- You can create a new Script file or add it to an existing Script like your own GameController or TitlescreenController that you may have already created.
using System.Collections.Generic;
void Start () {
// Uncomment this method to enable OneSignal Debugging log output
// OneSignal.SetLogLevel(OneSignal.LOG_LEVEL.VERBOSE, OneSignal.LOG_LEVEL.NONE);
// Replace 'YOUR_ONESIGNAL_APP_ID' with your OneSignal App ID.
OneSignal.StartInit("YOUR_ONESIGNAL_APP_ID")
.HandleNotificationOpened(OneSignalHandleNotificationOpened)
.Settings(new Dictionary<string, bool>() {
{ OneSignal.kOSSettingsAutoPrompt, false },
{ OneSignal.kOSSettingsInAppLaunchURL, false } })
.EndInit();
OneSignal.inFocusDisplayType = OneSignal.OSInFocusDisplayOption.Notification;
// iOS - Shows the iOS native notification permission prompt.
// - Instead we recomemnd using an In-App Message to prompt for notification
// permission to explain how notifications are helpful to your users.
OneSignal.PromptForPushNotificationsWithUserResponse(OneSignalPromptForPushNotificationsReponse);
}
// Gets called when the player opens a OneSignal notification.
private static void OneSignalHandleNotificationOpened(OSNotificationOpenedResult result) {
// Place your app specific notification opened logic here.
}
// iOS - Fires when the user anwser the notification permission prompt.
private void OneSignalPromptForPushNotificationsReponse(bool accepted) {
// Optional callback if you need to know when the user accepts or declines notification permissions.
}
3.2 Replace "YOUR_ONESIGNAL_APP_ID" with your OneSignal app id.
3.3 Follow one or more of the platform specific guides below to support iOS, Android, and / or FireOS push
Step 4. iOS Setup
After building in Unity open the Xcode Project and follow these setups.
4.1. Click on "Unity-iPhone" on the left and select the "Signing & Capabilities" tab.
4.2 From here check "Automatically manage signing", on the prompt click "Enable Automatic", and select your Team.
4.3 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.
4.4 Repeat the same steps above but for the "OneSignalNotificationServiceExtension" target this time.
4.5 "App Groups" should now be provisioned for you going forward for your iOS bundle id, even on clean builds.
Step 5. Android Setup
5.1 Go to Assets > External Dependency Manager > Android Resolver > Settings and check the following:
- Use Jetifier
- Patch gradleTemplate.properties
- Use project settings
5.2 Scroll down and press "OK" to save these settings.
5.3 Go to File > Build Settings... then click on the "Player Settings..." button
5.4 From here go to Publishing Settings and check "Custom Gradle Properties Template".
5.5 Replace the example icons located in Assets/Plugins/Android/OneSignalConfig/res with your own.
The file names must be lowercase and cannot contain anything else except underscores and numbers.
See our Customize Notification Icons page for more details.
Step 6. Amazon FireOS (ADM) Setup
Only required if you plan to release your app on the Amazon App Store to support Kindle Fire devices.
6.1 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.ADMMessageHandler" android:exported="false" />
<receiver android:name="com.onesignal.ADMMessageHandler$Receiver"
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>
6.2 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" >
6.3 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" />
6.4 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.ADMMessageHandler" android:exported="false" />
<receiver android:name="com.onesignal.ADMMessageHandler$Receiver"
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>
6.5 Replace all 3 of instances of COM.YOUR.PACKAGE_NAME with your package name in AndroidManifest.xml.
6.6 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.
Step 7. Run Your App and Send Yourself a Notification
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 devices should be subscribed to push notifications immediately upon opening the app.
- iOS devices should be prompted to subscribe to push notifications if you used the example setup code provided.
Check your OneSignal Dashboard Audience > All Users to see your Device Record.
Then head over to Messages > New Push to Send your first Push Notification from OneSignal.
Troubleshooting
If you run into any issues please see our Unity troubleshooting guide.
Try the example project on our Github repository.
If stuck, feel free to contact [email protected] for assistance.
Step 8. Implement a Soft-Prompt In-App Message for iOS
Optional
Android devices are subscribed to notifications automatically when your app is installed, so this section only applies to your iOS release.
Apple's Human Interface Guidelines recommend 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 an easy option for a "soft-prompt" using In-App Messages to meet this recommendation and have a better user experience. This also permits you to ask for permission again in the future, since the native permission prompt can no longer be shown in your app if the user clicks deny.
See our iOS Push Opt-In Prompt for details on implementing this.
Setup Complete!
Visit Mobile Push Tutorials for next steps.
Updated 6 days ago
What's Next
| Mobile Push Tutorials |