Hey! These docs are for version 7.0, which is no longer officially supported. Click here for the latest version, 9.0!

Just starting with iOS?

Check out our [iOS SDK Setup guide](🔗).

Latest API

This page is for the latest 3.0.0 version of the API, released Dec. 9, 2020.

**Still using the 2.x.x version?**

  • See our [Mobile SDKs API Migration Guides](🔗) to get updated to the latest SDK.

  • If you can't upgrade yet? See [the API 2.x.x reference.](🔗)

ParameterData TypeDescription

[setLogLevel](🔗)MethodEnable logging to help debug OneSignal implementation

[initWithLaunchOptions](🔗)MethodInitializes OneSignal. You should call from your AppDelegate's `didFinishLaunchingWithOptions`. You must also call `OneSignal.setAppId` to finish initialization.
[setAppId](🔗)MethodCall this to set or change the OneSignal appId required for initialization.
**Handling Notifications**

[setNotificationWillShowInForegroundHandler](🔗)MethodCalled when the app receives a notification while in focus only.
[setNotificationOpenedHandler](🔗)MethodCalled when the user opens or taps an action on a notification.

[setRequiresUserPrivacyConsent](🔗)MethodDelays initialization of the SDK until the user provides privacy consent
[consentGranted](🔗)MethodTells the SDK that the user has provided privacy consent (if required)
**iOS Prompting**

[promptForPushNotificationsWithUserResponse](🔗)MethodPrompt the user for notification permissions. Callback fires as soon as the user accepts or declines notifications.
[promptForPushNotificationsWithUserResponse:fallbackToSettings:](🔗)MethodPrompt the user for notification permissions. Use the fallbackToSettings parameter to prompt to open the settings app if a user has already declined push permissions
**User Status**

[getDeviceState](🔗)MethodReturns an `OSDeviceState` object with device info.
[addPermissionObserver](🔗)MethodObserver method for Current Device Record's Permission status changes.
[addSubscriptionObserver](🔗)MethodObserver method for Current Device Record's Subscription status changes.
[disablePush](🔗)MethodDisable OneSignal from sending notifications to current device.
**External User IDs**

[setExternalUserId](🔗)MethodAllows you to use your own system's user ID's to send push notifications to your users. To tie a user to a given user ID, you can use this method.
[removeExternalUserId](🔗)MethodRemoves whatever was set as the current user's external user ID.

[getTags](🔗)MethodView Tags from current device record.
[sendTag](🔗)MethodAdd a single [Data Tag](🔗) to current device record.
[sendTags](🔗)MethodAdd multiple [Data Tags](🔗) to current device record.
[deleteTag](🔗)MethodDelete a Tag from current device record.
[deleteTags](🔗)MethodDelete multiple Tags from current device record.
**Location Data**

[setLocationShared](🔗)MethodDisable or Enable SDK location collection. See [Handling Personal Data](🔗).
[isLocationShared](🔗)MethodReturns a boolean that indicates if location is shared
[promptLocation](🔗)MethodPrompt Users for Location <span class="label-all label-no">Not Recommended</span> <span class="label-all label-recommended">Recommended</span>: Use In-App Message [Location Opt-In Prompt](🔗).
**Sending Notifications**

[postNotification](🔗)MethodSend or schedule a notification to a OneSignal Player ID.
[clearAllNotifications](🔗)DocumentationAll Notifications cleared when badges are cleared
**In-App Messaging** 

[addTrigger](🔗)MethodAdd a trigger, may show an In-App Message if its triggers conditions were met.
[addTriggers](🔗)MethodAdd a map of triggers, may show an In-App Message if its triggers conditions were met.
[removeTriggerForKey](🔗)MethodRemoves a list of triggers based on a collection of keys, may show an In-App Message if its triggers conditions were met.
[getTriggerValueForKey](🔗)MethodGets a trigger value for a provided trigger key.
[pauseInAppMessages](🔗)MethodAllows you to temporarily pause all In App Messages.
[setInAppMessageClickHandler](🔗)MethodSets an In App Message opened block

[setEmail](🔗)MethodSet user's email. Creates a new user record for the email address. Use `sendTag` if you want to update a push user record with the email.
[logoutEmail](🔗)MethodLog user out to dissociate email from device
[addEmailSubscriptionObserver](🔗)MethodObserver for subscription changes to email

[setLaunchURLsInApp](🔗)MethodSet to `true` to launch all notifications with a URL in the app instead of the default web browser.
**Notification Objects**

[OSNotificationOpenedResult](🔗)ObjectInformation returned from a notification the user received.
[OSNotification](🔗)ObjectRepresents a received push notification
[OSNotificationAction](🔗)ObjectHow user opened notification
[OSNotificationPayload](🔗)ObjectData that comes with a notification

## Initialization

### `initWithLaunchOptions`

<div class="label-all label-type">Method</div>

Initialization is 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.

_Must be called from `didFinishLaunchingWithOptions` in `AppDelegate.m` / `AppDelegate.swift`._

`launchOptions`NSDictionary*<span class="label-all label-required">Required</span> launchOptions that you received from `didFinishLaunchingWithOptions`

### `setAppId`

Sets the app id OneSignal should use in the application.

Parameter TypeDescription
`NSString`String app id associated with the OneSignal dashboard app.

## Handling Notifications

### setNotificationWillShowInForegroundHandler

<div class="label-all label-type">Callback</div>

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.

`OSNotificationWillShowInForegroundBlock``Block`Call to block to complete the event

The block is provided with an `OSNotification` instance and a `completion` block.

### `setNotificationOpenedHandler`

<div class="label-all label-type">Callback</div>

Called when the user opens or taps an action on a notification.

`result`[OSNotificationOpenedResult](🔗)Data available within the OneSignal Notification Object when clicking the notification.

### `OSNotificationOpenedResult`

<div class="label-all label-type">Interface Element</div>

The information returned from a notification the user received. Resulting class passed to [OSHandleNotificationActionBlock](🔗).

[OSNotification](🔗)`notification`The notification the user received.
[OSNotificationAction](🔗)`action`The action the user took on the notification.

### `OSNotification`

<div class="label-all label-type">Interface Element</div>

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

#### `OSNotificationAction`

<div class="label-all label-type">Interface Element</div>

The action the user took on the notification.

Class PropertiesColumn Title
`actionID`(_NSString_);The ID associated with the button tapped. NULL when the `actionType` is `NotificationTapped`
`type`([OSNotificationActionType](🔗));The type of the notification action.

#### `OSNotificationActionType`

<div class="label-all label-type">Interface Element</div>

The action type (_NSUInteger Enum_) associated to an OSNotificationAction object.

NSUInteger Enum Properties

## Sending Notifications

### `postNotification`

<div class="label-all label-type">Method</div>

Allows you to send notifications from user to user or schedule ones in the future to be delivered to the current device.

See the [Create notification](🔗) REST API POST call for a list of all possible options. Note: You can only use `include_player_ids` as a targeting parameter from your app. Other target options such as `tags` and `included_segments` require your OneSignal App REST API key which can only be used from your server.

`parameters`NSDictionary*Dictionary of notification options, see our [Create notification](🔗) POST call for all options.
`onSuccess(Optional)`OneSignalResultSuccessBlockCalled if there were no errors sending the notification
`onFailure(Optional)`OneSignalFailureBlockCalled if there was an error

### getDeviceState

Returns an `OSDeviceState` object with device info.

## OSDeviceState

`NSString``userId`The OneSignal player / user id
`NSString``pushToken`The device iOS push token
`BOOL``hasNotificationPermission`Get the app's notification permission.
`BOOL``isSubscribed`Whether the user is subscribed for OneSignal Push notifications
`BOOL``isPushDisabled`Returns the value of what was sent to OneSignal.disablePush(bool). False by default
`NSString``emailAddress`The user's email.
`NSString``emailUserId`The user's email id.
`OSNotificationPermission`notificationPermissionStatusAn enumeration representing the current notification permission state.

### disablePush

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


### setLaunchURLsInApp

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

Parameter TypeDescription
`Bool`Boolean indicating if launch URLs should be opened in safari or within the application.

### clearAllNotifications

All Notifications are cleared when your badge count is set to 0. Thus there is no specific OneSignal API call for clearing notifications.

## Notification Service Extension

The notification service extension is used to add rich media to your notifications and change its content before being displayed to the user. OneSignal handles all of this for you by calling the following function from `didReceiveNotificationRequest`

### didReceiveNotificationExtensionRequest

**request**`UNNotificationRequest`The request that is passed into the native function
**replacementContent**`UNMutableNotificationContent`The content of the request retrieved through `[request.content mutableCopy]`. Any non-OneSignal changes that you want to make to the notification should be made to the content before passing the content to this method.
SDK version **3.5.0** and higher only **contentHandler**`contentHandler callback`The contentHandler completion block that triggers the display of the notification. Prior to SDK 3.5.0 you should call `contentHandler(<UNMutableNotificationContent>)` with the new request content to trigger the notification's display. As of 3.5.0 this is handled automatically by passing the contentHandler to `didReceiveNotificationExtensionRequest`