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

Step-by-Step iOS Native 2.x to 3.0.0 Upgrade Guide

Step 1 - Requirements

This guide assumes you already have setup the OneSignal-iOS-SDK 2.x.x and are migrating your app to the 3.x Major version.

Step 2 - Update the OneSignal SDK in your Xcode project

Depending on how you have OneSignal Imported today follow one of these sections

Cocoapods

  • Update your podfile version noted 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
  • Run pod update OneSignal

SwiftPM

Switch to branch 3.0.0

Step 3 - Update OneSignal Initialization Code

3.1 Navigate to your AppDelegate file and add the OneSignal initialization code to didFinishLaunchingWithOptions.
3.2 Replace the following

// START OneSignal initialization code
  let onesignalInitSettings = [kOSSettingsKeyAutoPrompt: false, kOSSettingsKeyInAppLaunchURL: false]
  
  // Replace 'YOUR_ONESIGNAL_APP_ID' with your OneSignal App ID.
  OneSignal.initWithLaunchOptions(launchOptions,
    appId: "YOUR_ONESIGNAL_APP_ID",
    handleNotificationAction: nil,
    settings: onesignalInitSettings)

  OneSignal.inFocusDisplayType = OSNotificationDisplayType.notification;
  //END OneSignal initializataion code
//START OneSignal initialization code
  [OneSignal initWithLaunchOptions:launchOptions
   appId:@"YOUR_ONESIGNAL_APP_ID"
   handleNotificationAction:nil
   settings:@{kOSSettingsKeyAutoPrompt: @false, kOSSettingsKeyInAppLaunchURL: @false}];
  OneSignal.inFocusDisplayType = OSNotificationDisplayTypeNotification;

3.3 To the match the new initialization

// OneSignal initialization
OneSignal.initWithLaunchOptions(launchOptions)
OneSignal.setAppId("YOUR_ONESIGNAL_APP_ID")
// OneSignal initialization
[OneSignal initWithLaunchOptions:launchOptions];
[OneSignal setAppId:@"YOUR_ONESIGNAL_APP_ID"];

3.4 Review your existing .inFocusDisplayType usage.

  • This was most likely set to OSNotificationDisplayType.notification which means no changes need as this is the default in 3.x.
  • If you didn't have inFocusDisplayType at all in your code or this was None the replacement for this is adding a setNotificationWillShowInForegroundHandler.

3.5. kOSSettingsKeyAutoPrompt has been removed, OneSignal no longer automatically prompts for notification permission on initialization.

  • Call OneSignal.promptForPushNotifications(userResponse:) to prompt when you want to show this.
  • Or See our iOS Push Opt-In Prompt for details prompting with an In-App Message.

3.6 setAppSettingshas been removed. Since the only setting used by that method in the 3.0 release is for launch URL handling It has been replaced by setLaunchURLsInApp. This method is used to have launch URLs opened within the app or with safari

3.7. Nullability annotations have been added to the OneSignal API to make it easier to use for Swift applications. These nullability changes may cause build errors for your app. Xcode's recommended fix is typically correct for these issues.

Step 4 - Review Full API Change List

:white-check-mark: You're setup with the new SDK!
Please review the full 3.0 API Reference - iOS Native for a full list of new features and other advanced features you may need to migrate as well.

Updated 6 months ago


Step-by-Step iOS Native 2.x to 3.0.0 Upgrade Guide


Suggested Edits are limited on API Reference Pages

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