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

Cordova SDK

OneSignal Cordova SDK Reference. Works with iOS, Android (and derivatives like Amazon) and Windows Phone 8.1.

πŸ“˜

Just getting started?

Check out our Cordova SDK Setup guide / Ionic SDK Setup guide / PhoneGap SDK Setup guide

Parameter

Data Type

Description

Debugging

setLogLevel

Method

Enable logging to help debug OneSignal implementation

Initialization

startInit

Method

Starts initialization of OneSignal, call this from the deviceready event. See Cordova SDK Setup / Ionic SDK Setup / PhoneGap SDK Setup for details and code examples.

inFocusDisplaying

Method

Setting to control how OneSignal notifications will be shown when one is received while your app is in focus.

iOSSettings

Builder Method

iOS - Automatically prompt users to enable notifications and open all URLs in In-App Safari window.

endInit

Builder Method

Must be called after StartInit to complete initialization of OneSignal.

Handling Notifications

handleNotificationReceived

Builder Method

Called when the app receives a notification while in focus only.

handleNotificationOpened

Builder Method

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

Privacy

setRequiresUserPrivacyConsent

Method

Delays initialization of the SDK until the user provides privacy consent

consentGranted

Method

Tells the SDK that the user has provided privacy consent (if required)

userProvidedPrivacyConsent

Method

Accepts a callback that returns a boolean indicating if the user provided privacy consent

iOS Prompting

promptForPushNotificationsWithUserResponse

Method

Prompt the user for notification permissions. Callback fires as soon as the user accepts or declines notifications.

Must set kOSSettingsKeyAutoPrompt to false when calling initWithLaunchOptions.

Recommended: Set to false and follow iOS Push Opt-In Prompt.

User Status

getPermissionSubscriptionState

Method

Get the current notification and permission state. Returns a OSPermissionSubscriptionState type.

addPermissionObserver

Method

Observer method for Current Device Record's Permission status changes.

addSubscriptionObserver

Method

Observer method for Current Device Record's Subscription status changes.

setSubscription

Method

Disable OneSignal from sending notifications to current device.

External IDs

setExternalUserId

Method

Allows 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

Method

Removes whatever was set as the current user's external user ID.

Tagging

getTags

Method

View Tags from current device record.

sendTag

Method

Add a single Data Tag to current device record.

sendTags

Method

Add multiple Data Tags to current device record.

deleteTag

Method

Delete a Tag from current device record.

deleteTags

Method

Delete multiple Tags from current device record.

Location Data

setLocationShared

Method

Disable or Enable SDK location collection. See Handling Personal Data.

promptLocation

Method

Prompt Users for Location Not Recommended

Recommended: Use In-App Message Location Opt-In Prompt.

Sending Notifications

postNotification

Method

Send or schedule a notification to a OneSignal Player ID.

clearOneSignalNotifications

Method

Delete all app notifications

In-App Messaging

addTrigger

Method

Add a trigger, may show an In-App Message if its triggers conditions were met.

addTriggers

Method

Add a map of triggers, may show an In-App Message if its triggers conditions were met.

removeTriggerForKey

Method

Removes a list of triggers based on a collection of keys, may show an In-App Message if its triggers conditions were met.

getTriggerValueForKey

Method

Gets a trigger value for a provided trigger key.

pauseInAppMessages

Method

Allows you to temporarily pause all In App Messages.

setInAppMessageClickHandler

Method

Sets an In App Message opened block.

Email

setEmail

Method

Set 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

Method

Log user out to dissociate email from device.

addEmailSubscriptionObserver

Method

Observer for subscription changes to email.

Appearance

enableVibrate

Method

When user receives notification, vibrate device less

enableSound

Method

When user receives notification, do not play a sound

Initialization

iOSSettings

Builder Method - iOS

Settings keys that can be passed into the initialization chaining method.

Parameter

Type

Description

kOSSettingsKeyAutoPrompt

Boolean

Auto prompt user for notification permissions.

kOSSettingsKeyInAppLaunchURL

Boolean

Used with the Launch URL you set on push notifications.

true will open the Launch URL in an in-app browser.

false will open the Launch URL in the device's default browser.

// Set your iOS Settings
var iosSettings = {};
iosSettings["kOSSettingsKeyAutoPrompt"] = false;
iosSettings["kOSSettingsKeyInAppLaunchURL"] = false;

// Initialize
window.plugins.OneSignal
  .startInit("YOUR_APPID")
  .iOSSettings(iosSettings)
  .endInit();

handleNotificationReceived

Builder Method

Sets a notification received handler. Only called if the app is running in the foreground at the time the notification was received.

Parameter

Type

Description

handler

NotificationReceivedHandler

Instance to a class implementing this interference.

window.plugins.OneSignal
  .startInit("YOUR_APPID")
  .handleNotificationReceived(function(notificationData) {
    alert("Notification Received:\n" + JSON.stringify(notificationData));
    console.log('Notification Received: ' + JSON.stringify(notificationData));
  })
  .endInit();

handleNotificationOpened

Builder Method

Sets a notification opened handler. The instance will be called when a notification is tapped on from the notification shade (Android) or notification center (iOS), or when closing an Alert notification shown in the app (if InAppAlert is enabled in inFocusDisplaying, below).

Parameter

Type

Description

handler

NotificationOpenedHandler

Instance to a class implementing this interference.

window.plugins.OneSignal
  .startInit("YOUR_APPID")
  .handleNotificationOpened(function(openResult) {
    alert("Notification opened:\n" + JSON.stringify(openResult));
    console.log('Notification opened: ' + JSON.stringify(openResult));   
  })
  .endInit();

clearOneSignalNotifications

Method

Clears all notifications in the Notification Center aka Shade sent from OneSignal.

OneSignal.clearOneSignalNotifications();

Receiving Notifications

NotificationReceivedHandler

Handler

Only fires when a OneSignal notification is received if the app is in focus.

Parameter

Type

Description

notificationData

OSNotification

Contains both the user's response and properties of the notification.

window.plugins.OneSignal
  .startInit("YOUR_APP_ID")
  .handleNotificationReceived(function(notificationData) {
    alert("Notification Data Received:\n" + JSON.stringify(notificationData));
    console.log('Notification Data Received: ' + JSON.stringify(notificationData));
  })
  .endInit();

The above example contains only a NotificationReceivedHandler that logs the notification to console. You will want to update it with the appropriate action, and you may wish to add other things to your init, such as a NotificationOpenedHandler (below) or other display options.

NotificationOpenedHandler

Handler

Use to process a OneSignal notification the user just tapped on.

Parameter

Type

Description

openResult

OSNotificationOpenedResult

Contains both the user's response and properties of the notification.

window.plugins.OneSignal
  .startInit( "YOUR_APP_ID")
  .handleNotificationOpened(function(openResult) {
    alert("Notification Opened:\n" + JSON.stringify(openResult));
    console.log('Notification Opened: ' + JSON.stringify(openResult));   
  })
  .endInit();

OSNotificationOpenedResult

JSON Object

The information returned from a notification the user received.

Parameter

Type

Description

notification

OSNotification

Notification the user opened.

action

OSNotificationAction

The action the user took on the notification.

OSNotification

JSON Object

The notification the user opened.

Parameter

Type

Description

isAppInFocus

Boolean

Was app in focus.

shown

Boolean

Was notification shown to the user. Will be false for silent notifications.

androidNotificationId

Integer

Android - Android Notification assigned to the notification. Can be used to cancel or replace the notification.

payload

OSNotificationPayload

Payload received from OneSignal.

displayType

displayType

How the notification was displayed to the user. Can be set to Notification, InAppAlert, or None if it was not displayed.

groupedNotifications

List<OSNotificationPayload>

Android - Notification is a summary notification for a group this will contain all notification payloads it was created from.

displayType

How the notification was displayed to the user. Part of OSNotification. See inFocusDisplaying for more information on how this is used.

Notification - native notification display.
InAppAlert (Default) - native alert dialog display.
None - notification is silent, or inFocusDisplaying is disabled.

OSNotificationAction

JSON Object

The action the user took on the notification.

Parameter

Type

Description

type

ActionType

Was the notification opened normally (Opened) or was a button pressed on the notification (ActionTaken).

actionID

String

If type == ActionTaken then this will contain the id of the button pressed.

OSNotificationPayload

JSON Object

Contents and settings of the notification the user received.

Parameter

Type

Description

notificationId

String

OneSignal notification UUID.

title

String

Title of the notification.

body

String

Body of the notification.

additionalData

JSONObject

Custom additional data that was sent with the notification. Set on the dashboard under Options > Additional Data or with the 'data' field on the REST API.

smallIcon

String

Android - Small icon resource name set on the notification.

largeIcon

String

Android - Large icon set on the notification.

bigPicture

String

Android - Big picture image set on the notification.

smallIconAccentColor

String

Android - Accent color shown around small notification icon on Android 5+ devices. ARGB format.

launchUrl

String

URL to open when opening the notification.

sound

String

Sound resource to play when the notification is shown.

ledColor

String

Android - Devices that have a notification LED will blink in this color. ARGB format.

lockScreenVisibility

Integer

Android - Privacy setting for how the notification should be shown on the lockscreen of Android 5+ devices.
1 = Public (fully visible)(default)
0 = Private (Contents are hidden)
-1 = Secret (not shown)

groupKey

String

Android - Notifications with this same key will be grouped together as a single summary notification.

groupMessage

String

Android - Summary text displayed in the summary notification.

actionButtons

List<ActionButton>

List of action buttons on the notification.

fromProjectNumber

String

Android - The Google project number the notification was sent under.

backgroundImageLayout

BackgroundImageLayout

Android - If a background image was set this object will be available.

rawPayload

String

Raw JSON payload string received from OneSignal.

ActionButton

JSON Object

List of action buttons on the notification. Part of OSNotificationPayload.

Parameter

Type

Description

id

String

Id assigned to the button.

text

String

Text show on the button to the user.

icon

String

Android - Icon shown on the button.


Appearance

enableVibrate

Method - Android

By default OneSignal always vibrates the device when a notification is displayed unless the device is in a total silent mode. Passing false means that the device will only vibrate lightly when the device is in it's vibrate only mode.

You can link this action to a UI button to give your user a vibration option for your notifications.

Parameter

Type

Description

enable

Boolean

false to disable vibrate, true to re-enable it.

window.plugins.OneSignal.enableVibrate(false);

enableSound

Method - Android

By default OneSignal plays the system's default notification sound when the device's notification system volume is turned on. You may also set custom sounds on notifications. Passing false means that the device will only vibrate unless the device is set to a total silent mode.

You can link this action to a UI button to give your user a different sound option for your notifications.

Parameter

Type

Description

enable

Boolean

false to disable sound, true to re-enable it.

window.plugins.OneSignal.enableSound(false);

Updated 7 months ago


Cordova SDK


OneSignal Cordova SDK Reference. Works with iOS, Android (and derivatives like Amazon) and Windows Phone 8.1.

Suggested Edits are limited on API Reference Pages

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