Step 1 - Requirements

• Create A OneSignal Account if you do not already have one
• Your OneSignal App ID, available in Settings > Keys & IDs in the OneSignal dashboard
• An iOS device (iPhone, iPad, iPod Touch) to test on. The Xcode simulator doesn't support push notifications so you must test on a real device.
• A Mac with a new version of Xcode.
• An iOS Push Certificate. Generate one here using our Provisionator tool.

Step 2 - Add a Notification Service Extension

The OneSignalNotificationServiceExtension allows your iOS application to receive rich notifications with images, buttons, and badges. It's also required for OneSignal's analytics features.

2.1 In Xcode Select File > New > Target...
2.2 Select Notification Service Extension then press Next.

2.3 Enter the product name as OneSignalNotificationServiceExtension and press Finish.

Do not select Activate on the dialog that is shown after selecting Finish.

2.4 Press Cancel on the Activate scheme prompt.

By canceling, you are keeping Xcode debugging your app, instead of the extension you just created.

If you activated by accident, you can switch back to debug your app within Xcode (next to the play button).

2.5 In the project navigator, select the top-level project directory and select the OneSignalNotificationServiceExtension target in the project and targets list.

Unless you have a specific reason not to, you should set the Deployment Target to be iOS 10 which is the version of iOS that Apple released Rich Media for push. iOS versions under 10 will not be able to get Rich Media.

2.6 In the project navigator, click the OneSignalNotificationServiceExtension folder and open the NotificationService.m or NotificationService.swift and replace the whole file's contents with the following code.

import UserNotifications

import OneSignal

class NotificationService: UNNotificationServiceExtension {
    
    var contentHandler: ((UNNotificationContent) -> Void)?
    var receivedRequest: UNNotificationRequest!
    var bestAttemptContent: UNMutableNotificationContent?
    
    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        self.receivedRequest = request;
        self.contentHandler = contentHandler
        bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
        
        if let bestAttemptContent = bestAttemptContent {
            OneSignal.didReceiveNotificationExtensionRequest(self.receivedRequest, with: self.bestAttemptContent)
            contentHandler(bestAttemptContent)
        }
    }
    
    override func 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.
        if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
            OneSignal.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
            contentHandler(bestAttemptContent)
        }
    }
    
}

#import <OneSignal/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];
    
    // Uncomment this line to set the default log level of NSE to VERBOSE so we get all logs from NSE logic
    //[OneSignal setLogLevel:ONE_S_LL_VERBOSE visualLevel:ONE_S_LL_NONE];
    
    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

Ignore any build errors at this point. We will import OneSignal which will resolve any errors.

Step 3 - Import the OneSignal SDK into your Xcode project

📘

Now Supporting Swift Package Manager

The OneSignal SDK is now available as a Swift Package (works with Objective-C as well).

See Instructions on how to import the SDK directly from Xcode.

CocoaPods Support

If using M1 Apple Silicon Mac or supporting Mac Catalyst see instructions for using the OneSignal XCFramework.

If using Carthage, see Carthage setup guide.

Regular CocoaPods setup (not for M1 Mac or Mac Catalyst):

3.1 Make sure your current Xcode project is closed and in the project root, run sudo gem install cocoapods.

3.2 Run pod init from the terminal in your project directory.

3.3 Open the newly created Podfile with your favorite code editor such as Sublime.

3.4 Add the OneSignal dependency under your project name target as well as
OneSignalNotificationServiceExtension target like below.

target 'your_project_name' do
  #only copy below line
  pod 'OneSignal', '>= 3.0.0', '< 4.0'
end

target 'OneSignalNotificationServiceExtension' do
  #only copy below line
  pod 'OneSignal', '>= 3.0.0', '< 4.0'
end

3.5 Run the following commands in your terminal in your project directory.

pod repo update
pod install

3.6 Open the newly created <project-name>.xcworkspace file.

Make sure to always open the workspace from now on. You can also do this automatically by running xed . from the root of your project.

Step 4 - Add Required Capabilities

This step will make sure your project is able to receive remote notifications,

Only do this for the main application target.
Do not do this for the Notification Service Extension.

4.1 Select the root project, your main app target and "Signing & Capabilities"

4.2 Select "All", then under "Background Modes" check "Remote notifications". You should see Push Notifications already provided.

4.3 If you do not see Push Notifications enabled, click "+ Capability" and double click "Push Notifications" to add it.

Step 5 - Add the OneSignal Initialization Code

Navigate to your AppDelegate file and add the OneSignal initialization code to didFinishLaunchingWithOptions.

Make sure to import the OneSignal headers:

• Swift: import OneSignal
• Objective-C: #import <OneSignal/OneSignal.h>

import UIKit
import OneSignal

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: 
[UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  
  // Remove this method to stop OneSignal Debugging 
  OneSignal.setLogLevel(.LL_VERBOSE, visualLevel: .LL_NONE)

  // OneSignal initialization
  OneSignal.initWithLaunchOptions(launchOptions)
  OneSignal.setAppId("YOUR_ONESIGNAL_APP_ID")

  // promptForPushNotifications will show the native iOS notification permission prompt.
  // We recommend removing the following code and instead using an In-App Message to prompt for notification permission (See step 8)
  OneSignal.promptForPushNotifications(userResponse: { accepted in
    print("User accepted notifications: \(accepted)")
  })

   return true
}
  
// Remaining contents of your AppDelegate Class...
}

#import <OneSignal/OneSignal.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  
  // Remove this method to stop OneSignal Debugging  
  [OneSignal setLogLevel:ONE_S_LL_VERBOSE visualLevel:ONE_S_LL_NONE];
  
  // OneSignal initialization
  [OneSignal initWithLaunchOptions:launchOptions];
  [OneSignal setAppId:@"YOUR_ONESIGNAL_APP_ID"];

  // promptForPushNotifications will show the native iOS notification permission prompt.
  // We recommend removing the following code and instead using an In-App Message to prompt for notification permission (See step 8)
  [OneSignal promptForPushNotificationsWithUserResponse:^(BOOL accepted) {
    NSLog(@"User accepted notifications: %d", accepted);
  }];
  
  return YES;
}

Replace YOUR_ONESIGNAL_APP_ID with your OneSignal App ID.

Step 6 - Add App Groups

App Groups allow your app to execute code when a notification is recieved, even if your app is not active. This is required for features including notification Badges, and Confirmed Deliveries.

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

Step 7 - Run your app on a device and send yourself a notification.

Test your app on a physical iOS device to make sure it builds correctly. You should be prompted to subscribe to notifications and you should be able to send yourself a notification from the OneSignal dashboard.

See Sending Push Messages for more details on sending push.

Note that the iOS Simulator does not support receiving remote push notifications.

📘

Troubleshooting

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

You can see a fully implemented example project on our Github repository.

Step 8 - Implement a Soft-Prompt In-App Message

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

• iOS SDK API - Explore other methods available in our iOS SDK in iOS Native 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..