Log InSign Up

Unity SDK Setup

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

Suggest Edits

Step 1 - Requirements

  • A OneSignal Account if you do not already have one
  • Your OneSignal App ID, available in Keys & IDs
  • Unity 2018.4 or newer
  • To test push notifications
    • An Android 4.0.3 or newer device or emulator with "Google Play services" installed.
    • An iOS 9 or newer device (iPhone, iPad, or iPod Touch).

Step 2 - Generate Credentials

You must generate the appropriate credentials for the platform(s) you are releasing on:

Step 3 - Import the OneSignal Unity Plugin

3.1 Download the latest OneSignal release and extract OneSignalSDK.unitypackage.

3.2 Open your Unity project, double click on OneSignalSDK.unitypackage, and press "Import".

407

Step 4 - Initialize OneSignal in your Unity scene

4.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.
}

4.2 Replace "YOUR_ONESIGNAL_APP_ID" with your OneSignal app id.
4.3 Follow one or more of the platform specific guides below to support iOS, Android, and / or FireOS push

Step 5 - iOS Setup

After building in Unity open the Xcode Project and follow these setups.
5.1. Click on "Unity-iPhone" on the left and select the "Signing & Capabilities" tab.
5.2 From here check "Automatically manage signing", on the prompt click "Enable Automatic", and select your Team.

1810

5.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.

1487

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

1816

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

Step 6 - Android Setup

6.1 - Go to Assets > External Dependency Manager > Android Resolver > Settings and check the following:

  • Use Jetifier
  • Patch gradleTemplate.properties
  • Use project settings
640

6.2. Scroll down and press "OK" to save these settings.
6.3. Go to File > Build Settings... then click on the "Player Settings..." button

632

6.4. From here go to Publishing Settings and check "Custom Gradle Properties Template".

850

6.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 7 - Amazon FireOS (ADM) Setup

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

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

7.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" >

7.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" />

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

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

7.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 8 - Build and test your game

Build and test your game to make sure your device is successfully subscribed to notifications and that you can receive notifications sent from the OneSignal dashboard.

🚧

Troubleshooting

If you run into any issues please see our Unity troubleshooting guide, or our general Troubleshooting section.

Step 9 - Other platforms

Step 10 - Implement a Soft-Prompt In-App Message for iOS

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.

1200

See our iOS Push Opt-In Prompt for details on implementing this.

Step 11 - Implement other OneSignal Features

  • Notification Delivery Settings - Learn about the many customizations and methods you can use to send notifications to your users in our Sending Push Messages guide.

  • Automated Messages - Set up Automated Messages to automatically re-engage app users who have lapsed or abandoned their cart. Learn more in our Automated Messages guide.

  • Segments and Tags - OneSignal supports simple and powerful tagging and segmentation to send messages to relevant users through our dashboard and API. Learn more in our Segments guide.

  • In-App Messages - OneSignal supports In-App Messaging in order to display rich content to your users or to present permission prompts, surveys, promotions, announcements, and more. Learn more in our In-App Messaging Overview.

  • E-Mail Support - OneSignal supports the delivery and automation of e-mail in addition to push notifications. Learn more in our Email Overview.

  • Unity SDK API - Explore other methods available in our Unity SDK in our Unity SDK API Documentation.

  • Remote API - Send notifications, import data, and export data using our simple and powerful API. Learn more in our OneSignal API overview..

Updated about 2 years ago

What’s Next