OneSignal Push Notification Service Documentation

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    Discussions

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.

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

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;
}

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

Unity Firebase Compatibility

If you are using any Firebase Unity plugins such as Analytics or Auth then make sure you are using version 5.3.1 (released Oct. 3 2018) or newer.
Firebase Unity SDK package.

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 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 - Add App Groups (Required for Badge Increase Feature)

In order for your application to be able to let push notifications increment/decrement the badge count, you need to set up an App Group for your application.

Please follow this guide to set up a OneSignal app group in your app.

7. iOS Setup - Part 3 (For Older versions of Unity, 5.6.X and above)

iOS

This step is optional but needed to use Notification Action Buttons and Media Attachments on iOS 10+. Please note that for versions of Unity 2017+, our SDK will now automatically add the Notification Service Extension to your iOS app. These steps are only necessary if you are running an older version of Unity.

7.1 Select File > New > Target...
7.2 Select Notification Service Extension then press Next.

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

7.4 Press Cancel on the Active scheme prompt.

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

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

7.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];
  
    // DEBUGGING: Uncomment the 2 lines below and comment out the one above to ensure this extension is excuting
    //            Note, this extension only runs when mutable-content is set
    //            Setting an attachment or action buttons automatically adds this
    // NSLog(@"Running NotificationServiceExtension");
    // self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];
    
    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

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

What's Next

Features Setup
Unity SDK

Unity SDK Setup

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

For Developers

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.