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

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