OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Support

Unity SDK Setup

OneSignal Unity SDK Setup Guide. Works with iOS, Android (and derivatives like Amazon) and Windows Phone 8.1.

For Developers

Required For Setup

  • A OneSignal Account if you do not already have one
  • Your OneSignal App ID, available in Keys & IDs
  • iOS - You MUST have a Mac with a new version of Xcode. Cloud Build is not supported.

Generate Credentials

Before setting up the Unity SDK, you must generate the appropriate credentials for the platform(s) you are releasing on:

iOS - Generate an iOS Push Certificate

Android - Generate a Google Server API Key

Amazon Fire - Generate an Amazon API Key

Windows Phone 8.1 - Generate a Windows Phone Package SID and Secret

1. Import the plugin

1.1 Download the latest unitypackage file

1.2 Open your Unity project, then open the downloaded unitypackage file for the version of Unity you're using.

1.3 The following import package screen will come up. Press import.

2. Adding the required code

2.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 () {
    // Enable line below to enable logging if you are having issues setting up OneSignal. (logLevel, visualLogLevel)
    // OneSignal.SetLogLevel(OneSignal.LOG_LEVEL.INFO, OneSignal.LOG_LEVEL.INFO);
  
  OneSignal.StartInit("b2f7f966-d8cc-11e4-bed1-df8f05be55ba")
    .HandleNotificationOpened(HandleNotificationOpened)
    .EndInit();
  
  OneSignal.inFocusDisplayType = OneSignal.OSInFocusDisplayOption.Notification;
  
  // Call syncHashedEmail anywhere in your app if you have the user's email.
  // This improves the effectiveness of OneSignal's "best-time" notification scheduling feature.
  // OneSignal.syncHashedEmail(userEmail);
}

// Gets called when the player opens the notification.
private static void HandleNotificationOpened(OSNotificationOpenedResult result) {
}
import System.Collections.Generic;
function Start () {
   OneSignal.StartInit("b2f7f966-d8cc-11e4-bed1-df8f05be55ba", "703322744261")
      .HandleNotificationOpened(HandleNotificationOpened)
      .EndInit();
}
// Gets called when the player opens the notification.
private static function HandleNotificationOpened(result : OSNotificationOpenedResult) : void {
}

2.2 Replace "b2f7f966-d8cc-11e4-bed1-df8f05be55ba" with your OneSignal app id.

3. Android Setup

Android

3.1 - Run Assets > Play Services Resolver > Android Resolver > Resolve Client Jars from the menu bar.

3.2 Replace the example icons located in Assets/Plugins/Android/OneSignalConfig/res with your own.
File names must be lowercase and cannot contain anything else except underscores and numbers.
See our Customize Notification Icons page for more details.

Facebook SDK Conflict

The Facebook Unity SDK doesn't use the Play Services Resolver as OneSignal does so it is know to conflict with a number of plugins. Please follow our Build error with Facebook SDK section to fix any build errors.

4. Amazon ADM Setup

Amazon

4.1. Open Plugins/Android/AndroidManifest.xml. If you don't have one create this file with the following contents and skip to step 4.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>

4.2. Open Plugins/Android/AndroidManifest.xml file and add xmlns:amazon="http://schemas.amazon.com/apk/res/android" in the manifest tag right after the xmlns:android property. See example below.

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

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

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

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

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

5. iOS Setup - Part 1

iOS

5.1 Build from Unity and open the Xcode project.
5.2 Select the root project. Under Capabilities enable "Push Notifications".
5.3 Next, enable "Background Modes" and check "Remote notifications".

5.5 Select Unity-iPhone target and go to Build Phases then select Link Binary With Libraries below.
5.6 Click the + plus and add UserNotifications.framework.

5.7 In future builds from Unity, always pick the "Append" option on the folder warning so you do not have to repeat the steps. If you click "Replace" you must re-add notification capabilities.

6. iOS Setup - Part 2 (Recommend)

iOS

This step is optional but needed to use Notification Action Buttons and Media Attachments on iOS 10.

6.1 Select File > New > Target...
6.2 Select Notification Service Extension then press Next.

6.3 Enter the product name as OneSignalNotificationServiceExtension and ensure that the Language is set to Objective-C. Then press Finish.

6.4 Press Cancel on the Active scheme prompt.

6.5 Select the new OneSignalNotificationServiceExtension target and go to Build Settings.
6.6 Select Architectures and change this to Standard architectures (armv7, arm64)
6.7 Do the same for the Unity-IPhone target.

6.8 Select the new OneSignalNotificationServiceExtension target and go to Build Phases then select Link Binary With Libraries below.
6.9 Click the + plus and add SystemConfiguration.framework and UIKit.framework.
6.10 Drag and drop libOneSignal.a under Libraries/OneSignal/Platform/iOS to this section as well.

6.11 Open NotificationService.m and replace the whole file contents with the below code.

#import "OneSignal.h"

#import "NotificationService.h"

@interface NotificationService ()

@property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property (nonatomic, strong) UNNotificationRequest *receivedRequest;
@property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;

@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.receivedRequest = request;
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];
    
    [OneSignal didReceiveNotificationExtensionRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];
    
    self.contentHandler(self.bestAttemptContent);
}

- (void)serviceExtensionTimeWillExpire {
    // Called just before the extension will be terminated by the system.
    // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
    
    [OneSignal serviceExtensionTimeWillExpireRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];
    
    self.contentHandler(self.bestAttemptContent);
}

@end

7. Windows Phone 8.1 (WP8.1)

Windows Phone 8.1

Your app does not have to be published however, you must have it created on the Windows Dev Center. Follow our Windows Phone Project SID & Secret setup if you have not done this yet.

7.1 Build from Unity and open the solution file .sln from the created build folder.
7.2 Double click on Package.appxmanifest then select the "Application" tab and scroll down to the "Notifications:" section. Change "Toast capable:" to Yes.

7.3 Under the Capabilities tab make sure "Internet (Client & Server)" is checked. Lastly make sure to save.

7.4 Right click on your VS project and select Store>Associate App with the Store...

7.5 Click Next and sign into your Microsoft account.

7.6 Select your app and press Next.

7.7. Lastly press Associate.

Troubleshooting

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

You're Done!

Next up: Send your first push notification via the OneSignal Dashboard


Unity SDK Setup

OneSignal Unity SDK Setup Guide. Works with iOS, Android (and derivatives like Amazon) and Windows Phone 8.1.

For Developers