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

Instructions for adding the OneSignal Unity SDK to your Unity app for iOS, Windows Phone 8.1, Android, and derivatives like Amazon

Step 1 - Requirements

  • A OneSignal Account if you do not already have one
  • Your OneSignal App ID, available in Keys & IDs
  • iOS - A Mac with a new version of Xcode (Required)

Step 2 - 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 Firebase Server API Key

Amazon Fire - Generate an Amazon API Key

Step 3 - Import the OneSignal Unity Plugin

3.1 Download the latest OneSignal unitypackage file

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

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

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.INFO, OneSignal.LOG_LEVEL.INFO);
  
  // Replace 'YOUR_ONESIGNAL_APP_ID' with your OneSignal App ID.
  OneSignal.StartInit("YOUR_ONESIGNAL_APP_ID")
    .HandleNotificationOpened(HandleNotificationOpened)
    .Settings(new Dictionary<string, bool>() {
      { OneSignal.kOSSettingsAutoPrompt, false },
      { OneSignal.kOSSettingsInAppLaunchURL, false } })
    .EndInit();
  
  OneSignal.inFocusDisplayType = OneSignal.OSInFocusDisplayOption.Notification;
  
  // The promptForPushNotifications function code will show the iOS push notification prompt. We recommend removing the following code and instead using an In-App Message to prompt for notification permission.
  OneSignal.PromptForPushNotificationsWithUserResponse(OneSignal_promptForPushNotificationsResponse);
  
  private void OneSignal_promptForPushNotificationsResponse(bool accepted) {
    Debug.Log("OneSignal_promptForPushNotificationsResponse: " + accepted);
  }
}

// Gets called when the player opens the notification.
private static void HandleNotificationOpened(OSNotificationOpenedResult result) {
}

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

Step 5 - Add Support for Android Notifications (Skip if your app is iOS only)

5.1 - Run Assets > Play Services Resolver > Android Resolver > Force Resolve from the menu bar.

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

🚧

Unity AndroidX Compatibility

If you have any plugins using AndroidX, follow these steps in the troubleshooting guide

You may need to do this if you see errors like Execution failed for task ':checkDebugDuplicateClasses'.

Step 6 - Amazon ADM Setup (Skip if you are not distributing your app for 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 6.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. 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" >

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 - iOS Setup (Skip if your app is Android-only)

7.1 Build your game from Unity and open the Xcode project.
7.2 Select the root project. Under Capabilities enable "Push Notifications".
7.3 Next, enable "Background Modes" and check "Remote notifications".

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

7.5 Add iOS App Groups
In order for your application to use Confirmed Deliveries and increment/decrement Badges through push notifications, you need to setup an App Group for your application.

Please follow the iOS SDK App Groups setup guide to add the OneSignal App Group in your app.

7.6 Add a Notification Service Extension (Required only for versions of Unity, 5.6.X and lower)

For newer versions of Unity, our SDK automatically adds the Notification Service Extension to your iOS app. These steps are only necessary if you are running an older version of Unity.

7.6.1 Select File > New > Target...
7.6.2 Select Notification Service Extension then press Next.

7.6.3 Enter the product name as OneSignalNotificationServiceExtension and ensure that the Language is set to Objective-C. Then press Finish. Do not select Activate on the dialog that is shown after selecting Finish.

7.6.4 Press Cancel on the Active scheme prompt.

By canceling, you are keeping Xcode debugging your app, instead of just the extension. If you activated by accident, you can switch back to debug your app within Xcode (next to the play button).

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

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

7.6.12 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

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 run into any issues please see our Unity troubleshooting guide, or our general Troubleshooting section.

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

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

Step 10 - 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 a month ago



Unity SDK Setup


Instructions for adding the OneSignal Unity SDK to your Unity app for iOS, Windows Phone 8.1, Android, and derivatives like Amazon

Suggested Edits are limited on API Reference Pages

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