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 Native - 3.0.0 API Changes

OneSignal iOS SDK Major Release Updates & Deprecations

New & Changed Methods

Reference

Details

initWithLaunchOptions()

1/2 of initialization process. Now only takes launchOptions as an argument.

setAppId()

1/2 of initialization process. Sets the OneSignal app id.

setLaunchURLsInApp()

Set to true to launch all notifications with a URL in an In App WebView

getDeviceState()

Gets information about the device.

disablePush()

Use this method to opt users out of receiving all notifications through OneSignal.
Replaces: setSubscription

setNotificationWillShowInForegroundHandler()

Use this method to handle notifications received in the foreground. For silent notifications use the Notification Service Extension. Replaces: OSHandleNotificationReceivedBlock


Initialization

In version 3, initialization is now a two step process requiring both initWithLaunchOptions and setAppId to be called. Note that you can call setAppId at any point in your app's flow. This allows full initialization to be delayed until say, a user logs in.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  // OneSignal initialization
  OneSignal.initWithLaunchOptions(launchOptions)
  OneSignal.setAppId("YOUR_ONESIGNAL_APP_ID")
}
- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions {
    [OneSignal initWithLaunchOptions:launchOptions];
    [OneSignal setAppId:@"########-####-####-####-############"];
}

initWithLaunchOptions Method

Parameter Type

Description

NSDictionary

Launch options from AppDelegate's didFinishLaunchingWithOptions

setAppId Method

Sets the app id OneSignal should use in the application.

Parameter Type

Description

NSString

String app id associated with the OneSignal dashboard app.

setLaunchURLsInApp Method

This method can be used to set if launch URLs should be opened in safari or within the application

Parameter Type

Description

Bool

Boolean indicating if launch URLs should be opened in safari or within the application.


Removed Methods

❗️

In version 3, there are several removed methods you should replace.

Removed Methods

Replacement

idsAvailable

Replaced by three observers:

  • getPermissionSubscriptionState
  • addPermissionObserver
  • addSubscriptionObserver
  • addEmailSubscriptionObserver

presentAppSettings

Replaced by promptForPushNotificationsWithUserResponse:fallBack

syncHashedEmail

No longer providing this functionality. Use setEmail instead.

setNotificationDisplayType

Notification foreground display is now controlled using notificationWillShowInForegroundHandler.
Note that the Alert notification display type has been removed.

setSubscription

Replaced by disablePush

kOSSettingsKeyAutoPrompt

Replaced by promptForPushNotificationsWithUserResponse:fallBack

kOSSettingsKeyInAppLaunchURL

SDK version 3.2.1+
Replaced by setting OneSignal_suppress_launch_urls in the Info.plist

  • YES will not show the launch url in an in-app browser.
  • NO will show the launch url in an in-app browser.
    Example Suppress Launch URLs

New Methods

Foreground Notification Control

In version 3, you can now specifically read notification data that will display while the app is in focus as well as change the display type dynamically. This allows developers to have even greater control over the notification experience.

setNotificationWillShowInForegroundHandler Method

Runs before displaying a notification while the app is in focus. Use this handler to decide if the notification should show or not. To silence the notification pass nil to the completion handler and to show the notification pass the notification to the completion handler. If the completion handler is not called within 25 seconds the notification will be shown.

Note: this runs after the Notification Service Extension which can be used to modify the notification content before showing it.

Parameter

OSNotificationWillShowInForegroundBlock

Block

The block is provided with an OSNotification instance and a completion block. OSNotificationPayload has been removed and combined with OSNotification.

let notifWillShowInForegroundHandler: OSNotificationWillShowInForegroundBlock = { notification, completion in
    print("Received Notification: ", notification.notificationId ?? "no id")
    print("launchURL: ", notification.launchURL ?? "no launch url")
    print("content_available = \(notification.contentAvailable)")
    if notification.notificationId == "example_silent_notif" {
        completion(nil)
    } else {
        completion(notification)
    }
}

OneSignal.setNotificationWillShowInForegroundHandler(notifWillShowInForegroundHandler)
id notifWillShowInForegroundHandler = ^(OSNotification *notification, OSNotificationDisplayResponse completion) {
        NSLog(@"Received Notification - %@", notification.notificationId);
        if ([notification.notificationId isEqualToString:@"silent_notif"]) {
            completion(nil);
        } else {
            completion(notification);
        }
    };

[OneSignal setNotificationWillShowInForegroundHandler:notifWillShowInForegroundHandler];

OSNotification properties:

Type

Property/Method

Description

NSString

notificationId

OneSignal notification UUID.

NSString

title

The message title.

NSString

subtitle

The message subtitle.

NSString

body

The message body.

NSString

templateId

Unique Template Identifier

NSString

templateName

Name of Template

NSString

launchURL

Web address to launch within the app via WKWebView

NSString

category

Notification category key previously registered to display with.

NSString

threadId

iOS 10+ only. Groups notifications into threads

NSDictionary

attachments

iOS 10+ only. Attachments sent as part of the rich notification

NSDictionary

additionalData

Additional key value properties set within the payload.

BOOL

contentAvailable

True when the key content-available is set to 1 in the APNS payload. Used to wake your app when the payload is received.

See Apple's documenation for more details.

BOOL

mutableContent

True when the key mutable-content is set to 1 in the APNS payload.

See Apple's documenation for more details.

NSInteger

badge

The badge number assigned to the application icon.

NSInteger

badgeIncrement

The amount to increment the badge icon number.

NSArray

actionButtons

Action buttons set on the notification.

NSDictionary

rawPayload

Holds the raw APS payload received.

Method

parseWithApns

Parses an APS push payload into a OSNotificationPayload object. Useful to call from your NotificationServiceExtension when the didReceiveNotificationRequest:withContentHandler: method fires.

Click/Open Handlers

OSHandleInAppMessageActionClickBlock has been renamed to OSInAppMessageClickBlock. It still takes an OSInAppMessageAction parameter

OSInAppMessageAction fields:

Type

Field

Description

NSString

clickName

An optional click name entered defined by the app developer when creating the IAM.

NSURL

clickUrl

An optional URL that opens when the action takes place.

BOOL

closesMessage

Determines if tapping on the element should close the In-App Message.

BOOL

firstClick

Determines if this was the first action taken on the in app message.

NSArray<OSInAppMessageOutcome *>

outcomes

Outcome for action.

OSInAppMessagePrompt

prompts

Prompts for action.

OSInAppMessageTag

tags

Tags for action.

OSInAppMessageActionUrlType

urlTarget

Determines where the URL is opened, ie.

setNotificationOpenedHandler Method

Parameter

OSNotificationOpenedBlock

Block

This block was renamed from OSHandleNotificationActionBlock to OSNotificationOpenedBlock. It is provided with a result object of type OSNotificationOpenedResult.

let notificationOpenedBlock: OSNotificationOpenedBlock = { result in
    // This block gets called when the user reacts to a notification received
    let notification: OSNotification = result.notification
    print("Message: ", notification.body ?? "empty body")
    print("badge number: ", notification.badge)
    print("notification sound: ", notification.sound ?? "No sound")
            
    if let additionalData = notification.additionalData {
        print("additionalData: ", additionalData)
        if let actionSelected = notification.actionButtons {
            print("actionSelected: ", actionSelected)
        }
        if let actionID = result.action.actionId {
            //handle the action
        }
    }
}

OneSignal.setNotificationOpenedHandler(notificationOpenedBlock)
id notificationOpenedBlock = ^(OSNotificationOpenedResult *result) {
  OSNotification* notification = result.notification;
  if (notification.additionalData) {
    if (result.action.actionId) {
      fullMessage = [fullMessage stringByAppendingString:[NSString stringWithFormat:@"\nPressed ButtonId:%@", result.action.actionId]];
    }
  }

OSNotificationOpenResult fields:

Type

Field

Description

OSNotificationAction

action

The action the user took on the notification.

OSNotification

notification

The notification the user received.

Go to OSNotification reference.

OSNotificationActionType Enum:
The action type associated to an OSNotificationAction object.

Value

OSNotificationActionTypeOpened

OSNotificationActionTypeActionTaken

OSNotificationAction property actionID has been renamed to actionId.:


Other Methods

getDeviceState Method

Returns an OSDeviceState object with device info.

🚧

Do not cache OSDeviceState object

This method returns a "snapshot" of the device state for when it was called. To ensure fresh state, make sure to call getDeviceState each time you need to get one of the member fields.

OSDeviceState getters:

if let deviceState = OneSignal.getDeviceState() {
    let userId = deviceState.userId
    let pushToken = deviceState.pushToken
    let subscribed = deviceState.isSubscribed
 }
OSDeviceState *deviceState = [OneSignal getDeviceState];
NSString *userId = deviceState.userId;
NSString *pushToken = deviceState.pushToken;
BOOL subscribed = deviceState.isSubscribed;

Type

Property

Description

NSString

emailAddress

The user's email.

NSString

emailUserId

The user's email id.

NSString

pushToken

The device push token.

NSString

userId

The user id from registration.

BOOL

hasNotificationPermission

Get the app's notification permission.

BOOL

isSubscribed

Whether the user is subscribed

BOOL

isPushDisabled

Returns the value of what was sent to OneSignal.disablePush(bool).
False by default

disablePush Method

Use this method to opt users out of receiving all notifications through OneSignal.
Replaces: setSubscription

Parameter

disabled

BOOL


Other Changes

app_id has been renamed to appId
sdk_version_raw has been renamed to sdkVersionRaw
sdk_semantic_version has been renamed to sdkSemanticVersion

Nullability for Swift interface

Nullability annotations have been added to the OneSignal header to make the Swift interface easier to use.
Xcode will point these changes out as warning or errors to help you migrate however below outlines the changes.

func onOSPermissionChanged(_ stateChanges: OSPermissionStateChanges)
func onOSPermissionChanged(_ stateChanges: OSPermissionStateChanges!)

New Nonnull Annotations

Methods

  • deleteTag
    • deleteTags
    • deleteTagsWithJsonString
    • didReceiveNotificationExtensionRequest
    • getTags
    • handleMessageAction
    • onOSEmailSubscriptionChanged
    • onOSPermissionChanged
    • onOSSubscriptionChanged
    • onesignal_Log
    • parseNSErrorAsJsonString
    • postNotification
    • postNotification
    • postNotificationWithJsonString
    • sdkSemanticVersion
    • sdkVersionRaw
    • stringify
    • sendTag
    • sendTags
    • sendTagsWithJsonString
    • serviceExtensionTimeWillExpireRequest
    • setMSDKType
    • toDictionary

Properties

  • OSNotificationAction *action
    • OSNotification* notification
    • OSNotificationPayload* payload

New Nullable Annotations

Methods

  • didReceiveNotificationExtensionRequest
    • serviceExtensionTimeWillExpireRequest
    • setInAppMessageClickHandler
    • setLaunchOptions
    • setNotificationOpenedHandler
    • setNotificationWillShowInForegroundHandler

onSuccess & onFailure Block Parameters

  • deleteTag
    • deleteTags
    • getTag
    • getTags
    • sendTags
    • postNotification
    • postNotificationWithJsonString
    • sendOutcomeWithValue

Properties

  • OSEmailSubscriptionState *emailSubscriptionStatus;
    • OSEmailSubscriptionState* from;
    • OSEmailSubscriptionState* to;
    • OSPermissionState* from;
    • OSPermissionState* permissionStatus;
    • OSPermissionState* to;
    • OSSubscriptionState* from;
    • OSSubscriptionState* subscriptionStatus;
    • OSSubscriptionState* to;
    • NSDictionary* attachments;
    • NSString *threadId;
    • NSString* actionID;
    • NSString* body;
    • NSString* category;
    • NSString* launchURL;
    • NSString* notificationID;
    • NSString* sound;
    • NSString* subtitle;
    • NSString* templateID;
    • NSString* templateName;
    • NSString *title;
    • NSString *emailAddress;
    • NSString* emailUserId;
    • NSString* pushToken;
    • NSString* userId;

Updated 6 days ago


iOS Native - 3.0.0 API Changes


OneSignal iOS SDK Major Release Updates & Deprecations

Suggested Edits are limited on API Reference Pages

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