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

iOS SDK Setup

Instructions for adding the OneSignal SDK to your iOS native app with Swift or Objective-C

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. Details see: Generate an iOS Push Certificate.

πŸ“˜

Installation via the OneSignal CLI

The OneSignal CLI is now available in beta with a command to automate most steps of the iOS SDK setup process.

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
        self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
        
        if let bestAttemptContent = bestAttemptContent {
            //If your SDK version is < 3.5.0 uncomment and use this code:
            /*
            OneSignal.didReceiveNotificationExtensionRequest(self.receivedRequest, with: self.bestAttemptContent)
            contentHandler(bestAttemptContent)
            */
            
            /* DEBUGGING: Uncomment the 2 lines below to check this extension is excuting
                          Note, this extension only runs when mutable-content is set
                          Setting an attachment or action buttons automatically adds this */
            //OneSignal.setLogLevel(.LL_VERBOSE, visualLevel: .LL_NONE)
            //bestAttemptContent.body = "[Modified] " + bestAttemptContent.body
            
            OneSignal.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
        }
    }
    
    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];
    
    //If your SDK version is < 3.5.0 uncomment and use this code:
    /*
    [OneSignal didReceiveNotificationExtensionRequest:self.receivedRequest
                       withMutableNotificationContent:self.bestAttemptContent];
    self.contentHandler(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];
    [OneSignal didReceiveNotificationExtensionRequest:self.receivedRequest
                       withMutableNotificationContent:self.bestAttemptContent
                                   withContentHandler:self.contentHandler];
}

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

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 and Send Yourself a Notification

Run your app on a physical iOS device to make sure it builds correctly. Note that the iOS Simulator does not support receiving remote push notifications.

You should be prompted to subscribe to push notifications. Check your OneSignal Dashboard Audience > All Users to see your Device Record.

Then head over to Messages > New Push to Send your first Push Notification from OneSignal.

πŸ“˜

Troubleshooting

If running into issues, see our iOS troubleshooting guide.

Try the example project on our Github repository.

If stuck, feel free to contact [email protected] for assistance.

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

Optional

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.

πŸ‘

Setup Complete!

Visit Mobile Push Tutorials for next steps.

Updated 6 days ago



iOS SDK Setup


Instructions for adding the OneSignal SDK to your iOS native app with Swift or Objective-C

Suggested Edits are limited on API Reference Pages

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