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

iOS SDK Setup

For Developers

Before proceeding, you must generate an iOS Push Certificate.

1. Import OneSignal into your Xcode project

Option A: Use CocoaPods (Recommended)

Setting up CocoaPods on your system if you don't have it already.

  • Make sure you have version 1.1.0 or newer by running pod --version from the terminal.
  • Run the following to upgrade sudo gem install cocoapods

1.1 Make sure your current Xcode project is closed.
1.2 Run the following set of commands in the terminal from your project's root directory.

pod init
echo "pod 'OneSignal'" >> Podfile
pod repo update
pod install

1.3 Open the newly created .xcworkspace file.
Make sure to always open the workspace from now on.
1.4 Continue to Steps 2 and 3 below

-- OR --

Option B: Use Carthage

You can also use Carthage for setting up and upgrading the OneSignal SDK.

1.1 Make sure your current Xcode project is closed.
1.2 Run echo 'github "OneSignal/OneSignal-iOS-SDK"' >> Cartfile
1.3 Run carthage update.
1.4 Open your Xcode project.
1.5 On your application targets’ “General” settings tab, in the “Linked Frameworks and Libraries” section, drag and drop OneSignal.framework from the $(PROJECT_DIR)/Carthage/Build/iOS folder on disk.
1.6 On your application targets’ “Build Phases” settings tab, click the “+” icon and choose “New Run Script Phase”. Create a Run Script in which you specify your shell (ex: bin/sh), add the following contents to the script area below the shell:
/usr/local/bin/carthage copy-frameworks
1.7 add the path to the OneSignal framework under “Input Files”:
1.8 Continue to Steps 2 and 3 below

This script works around an App Store submission bug triggered by universal binaries and ensures that necessary bitcode-related files and dSYMs are copied when archiving.

2. Add Required Capabilities

2.1 Select the root project and Under Capabilities Enable "Push Notifications".
2.2 Next Enable "Background Modes" and check "Remote notifications".

3. Add Required Code

Add following code to your AppDelegate.

#import "AppDelegate.h"

//Add this line
#import <OneSignal/OneSignal.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions {
  //Add this line. Replace '5eb5a37e-b458-11e3-ac11-000c2940e62c' with your OneSignal App ID.
   [OneSignal initWithLaunchOptions:launchOptions appId:@"5eb5a37e-b458-11e3-ac11-000c2940e62c"];
  // Call syncHashedEmail anywhere in your iOS app if you have the user's email.
  // This improves the effectiveness of OneSignal's "best-time" notification scheduling feature.
  // [OneSignal syncHashedEmail:userEmail];
   return YES;
import OneSignal

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
   //Add this line. Replace '5eb5a37e-b458-11e3-ac11-000c2940e62c' with your OneSignal App ID.
   OneSignal.initWithLaunchOptions(launchOptions, appId: "5eb5a37e-b458-11e3-ac11-000c2940e62c")
  // Sync hashed email if you have a login system or collect it.
  //   Will be used to reach the user at the most optimal time of day.
  // OneSignal.syncHashedEmail(userEmail)
   return true

Make sure OneSignal initWithLaunchOptions is called from your didFinishLaunchingWithOptions.

Done! The Xcode simulator doesn't support push notifications so you must test on a device.

Optional: Notification Opened Callback

If you need to process any information on the notification (such as deep linking to to a specific screen in your app) you can add a notification action callback that will fire when the user reacts to a notification received.

Replace the code you added in step 3 in your didFinishLaunchingWithOptions method with the code below.*

[OneSignal initWithLaunchOptions:launchOptions appId:@"b2f7f966-d8cc-11e4-bed1-df8f05be55ba" handleNotificationAction:^(OSNotificationOpenedResult *result) {
        // This block gets called when the user reacts to a notification received
        OSNotificationPayload* payload = result.notification.payload;
        NSString* messageTitle = @"OneSignal Example";
        NSString* fullMessage = [payload.body copy];
        if (payload.additionalData) {
                messageTitle = payload.title;
            NSDictionary* additionalData = payload.additionalData;
            if (additionalData[@"actionSelected"])
                fullMessage = [fullMessage stringByAppendingString:[NSString stringWithFormat:@"\nPressed ButtonId:%@", additionalData[@"actionSelected"]]];
        UIAlertView* alertView = [[UIAlertView alloc] initWithTitle:messageTitle
                                                  otherButtonTitles:nil, nil];
        [alertView show];

OneSignal.initWithLaunchOptions(launchOptions, appId: "b2f7f966-d8cc-11e4-bed1-df8f05be55ba") { (result) in
		// This block gets called when the user reacts to a notification received
		let payload = result.notification.payload
		let messageTitle = "OneSignal Example"
		var fullMessage = payload.title
		//Try to fetch the action selected
		if let additionalData = payload.additionalData, actionSelected = additionalData["actionSelected"] as? String {
			fullMessage =  fullMessage + "\nPressed ButtonId:\(actionSelected)"
		let alertView = UIAlertView(title: messageTitle, message: fullMessage, delegate: nil, cancelButtonTitle: "Close")
OneSignal.initWithLaunchOptions(launchOptions, appId: "b2f7f966-d8cc-11e4-bed1-df8f05be55ba", handleNotificationReceived: { (notification) in
            print("Received Notification - \(notification?.payload.notificationID)")
        }, handleNotificationAction: { (result) in
            let payload: OSNotificationPayload? = result?.notification.payload
            var fullMessage: String? = payload?.body
            if payload?.additionalData != nil {
                var additionalData: [AnyHashable: Any]? = payload?.additionalData
                if additionalData!["actionSelected"] != nil {
                    fullMessage = fullMessage! + "\nPressed ButtonId:\(additionalData!["actionSelected"])"
        }, settings: [kOSSettingsKeyAutoPrompt : true])

Optional: Custom notification sounds

Drag and drop the custom notification sounds you want available into the root of the XCode project.

Read more in Customize Notification Sounds for information on file formats, differences between platforms, and how to send notifications with custom sounds.


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

Additional Documentation

To see all available methods, see our iOS Native SDK documentation.

iOS SDK Setup

For Developers