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

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

ParameterData TypeDescription
setLogLevelMethodEnable logging to help debug OneSignal implementation
startInitMethodStarts initialization of OneSignal, call this from the deviceready event. See Cordova SDK Setup / Ionic SDK Setup / PhoneGap SDK Setup for details and code examples.
inFocusDisplayingMethodSetting to control how OneSignal notifications will be shown when one is received while your app is in focus.
iOSSettingsBuilder MethodiOS - Automatically prompt users to enable notifications and open all URLs in In-App Safari window.
endInitBuilder MethodMust be called after StartInit to complete initialization of OneSignal.
Handling Notifications
handleNotificationReceivedBuilder MethodCalled when the app receives a notification while in focus only.
handleNotificationOpenedBuilder MethodCalled when the user opens or taps an action on a notification.
setRequiresUserPrivacyConsentMethodDelays initialization of the SDK until the user provides privacy consent
consentGrantedMethodTells the SDK that the user has provided privacy consent (if required)
userProvidedPrivacyConsentMethodAccepts a callback that returns a boolean indicating if the user provided privacy consent
iOS Prompting
promptForPushNotificationsWithUserResponseMethodPrompt 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
getPermissionSubscriptionStateMethodGet the current notification and permission state. Returns a OSPermissionSubscriptionState type.
addPermissionObserverMethodObserver method for Current Device Record's Permission status changes.
addSubscriptionObserverMethodObserver method for Current Device Record's Subscription status changes.
setSubscriptionMethodDisable OneSignal from sending notifications to current device.
External IDs
setExternalUserIdMethodAllows 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.
removeExternalUserIdMethodRemoves whatever was set as the current user's external user ID.
getTagsMethodView Tags from current device record.
sendTagMethodAdd a single Data Tag to current device record.
sendTagsMethodAdd multiple Data Tags to current device record.
deleteTagMethodDelete a Tag from current device record.
deleteTagsMethodDelete multiple Tags from current device record.
Location Data
setLocationSharedMethodDisable or Enable SDK location collection. See Handling Personal Data.
promptLocationMethodPrompt Users for Location Not Recommended

Recommended: Use In-App Message Location Opt-In Prompt.
Sending Notifications
postNotificationMethodSend or schedule a notification to a OneSignal Player ID.
clearOneSignalNotificationsMethodDelete all app notifications
In-App Messaging
addTriggerMethodAdd a trigger, may show an In-App Message if its triggers conditions were met.
addTriggersMethodAdd a map of triggers, may show an In-App Message if its triggers conditions were met.
removeTriggerForKeyMethodRemoves a list of triggers based on a collection of keys, may show an In-App Message if its triggers conditions were met.
getTriggerValueForKeyMethodGets a trigger value for a provided trigger key.
pauseInAppMessagesMethodAllows you to temporarily pause all In App Messages.
setInAppMessageClickHandlerMethodSets an In App Message opened block.
setEmailMethodSet 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.
logoutEmailMethodLog user out to dissociate email from device.
addEmailSubscriptionObserverMethodObserver for subscription changes to email.
enableVibrateMethodWhen user receives notification, vibrate device less
enableSoundMethodWhen user receives notification, do not play a sound



Builder Method - iOS

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

kOSSettingsKeyAutoPromptBooleanAuto prompt user for notification permissions.
kOSSettingsKeyInAppLaunchURLBooleanUsed 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


Builder Method

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

handlerNotificationReceivedHandlerInstance to a class implementing this interference.
  .handleNotificationReceived(function(notificationData) {
    alert("Notification Received:\n" + JSON.stringify(notificationData));
    console.log('Notification Received: ' + JSON.stringify(notificationData));


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

handlerNotificationOpenedHandlerInstance to a class implementing this interference.
  .handleNotificationOpened(function(openResult) {
    alert("Notification opened:\n" + JSON.stringify(openResult));
    console.log('Notification opened: ' + JSON.stringify(openResult));   



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


Receiving Notifications



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

notificationDataOSNotificationContains both the user's response and properties of the notification.
  .handleNotificationReceived(function(notificationData) {
    alert("Notification Data Received:\n" + JSON.stringify(notificationData));
    console.log('Notification Data Received: ' + JSON.stringify(notificationData));

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.



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

openResultOSNotificationOpenedResultContains both the user's response and properties of the notification.
  .startInit( "YOUR_APP_ID")
  .handleNotificationOpened(function(openResult) {
    alert("Notification Opened:\n" + JSON.stringify(openResult));
    console.log('Notification Opened: ' + JSON.stringify(openResult));   


JSON Object

The information returned from a notification the user received.

notificationOSNotificationNotification the user opened.
actionOSNotificationActionThe action the user took on the notification.


JSON Object

The notification the user opened.

isAppInFocusBooleanWas app in focus.
shownBooleanWas notification shown to the user. Will be false for silent notifications.
androidNotificationIdIntegerAndroid - Android Notification assigned to the notification. Can be used to cancel or replace the notification.
payloadOSNotificationPayloadPayload received from OneSignal.
displayTypedisplayTypeHow the notification was displayed to the user. Can be set to Notification, InAppAlert, or None if it was not displayed.
groupedNotificationsList<OSNotificationPayload>Android - Notification is a summary notification for a group this will contain all notification payloads it was created from.


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.


JSON Object

The action the user took on the notification.

typeActionTypeWas the notification opened normally (Opened) or was a button pressed on the notification (ActionTaken).
actionIDStringIf type == ActionTaken then this will contain the id of the button pressed.


JSON Object

Contents and settings of the notification the user received.

notificationIdStringOneSignal notification UUID.
titleStringTitle of the notification.
bodyStringBody of the notification.
additionalDataJSONObjectCustom 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.
smallIconStringAndroid - Small icon resource name set on the notification.
largeIconStringAndroid - Large icon set on the notification.
bigPictureStringAndroid - Big picture image set on the notification.
smallIconAccentColorStringAndroid - Accent color shown around small notification icon on Android 5+ devices. ARGB format.
launchUrlStringURL to open when opening the notification.
soundStringSound resource to play when the notification is shown.
ledColorStringAndroid - Devices that have a notification LED will blink in this color. ARGB format.
lockScreenVisibilityIntegerAndroid - 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)
groupKeyStringAndroid - Notifications with this same key will be grouped together as a single summary notification.
groupMessageStringAndroid - Summary text displayed in the summary notification.
actionButtonsList<ActionButton>List of action buttons on the notification.
fromProjectNumberStringAndroid - The Google project number the notification was sent under.
backgroundImageLayoutBackgroundImageLayoutAndroid - If a background image was set this object will be available.
rawPayloadStringRaw JSON payload string received from OneSignal.


JSON Object

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

idStringId assigned to the button.
textStringText show on the button to the user.
iconStringAndroid - Icon shown on the button.



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.

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


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.

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