Removed Functions

❗️

In version 3, there are several functions you should remove.

New Functions

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.

Replaces inFocusDisplaying() functionality.

setNotificationWillShowInForegroundHandler Function

Runs before displaying a notification while the app is in focus. Use this handler to decide if the notification should show or not.

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

The callback accepts the parameter OSNotification.

window.plugins.OneSignal.setNotificationWillShowInForegroundHandler(function(notificationReceivedEvent) {
  notificationReceivedEvent.complete(notificationReceivedEvent.notification);
});

the callback argument object has two functions:

Handlers

setInAppMessageClickHandler Function

Set the callback to run on an In-App Message click.

var iamClickCallback = function(jsonData) {
  var iamClickAction = JSON.stringify(jsonData);
  console.log('iamClickCallback: ' + iamClickAction);
};
window.plugins.OneSignal.setInAppMessageClickHandler(iamClickCallback);

setNotificationOpenedHandler Function

Set the callback to run on notification open/click.

var notificationOpenedCallback = function(jsonData) {
  var notificationData = JSON.stringify(jsonData)
  console.log('notificationOpenedCallback: ' + notificationData);
};

window.plugins.OneSignal.setNotificationOpenedHandler(notificationOpenedCallback);

openedEvent fields:

Observers

Each callback you pass to an observer adder function will receive a state change object when fired that contains two parameters: to and from. The parameters on those objects are the same between the two. This format allows for the detection of the previous state and the new state.

Example: a change in the subscription state of the device might see the isSubscribed parameter change from false to true. You can detect the change by the event.from.isSubscribed and event.to.isSubscribed objects.

addPermissionObserver Function

Add a callback that fires when the native push permission changes.

Change event parameters:

addSubscriptionObserver Function

Add a callback that fires when the OneSignal subscription state changes.

Change event parameters:

addEmailSubscriptionObserver Function

Add a callback that fires when the OneSignal email subscription changes.

Change event parameters:

Example

window.plugins.OneSignal.addEmailSubscriptionObserver(function(stateChanges) {
  console.log("Email subscription state changed: \n" + JSON.stringify(stateChanges, null, 2));
});

window.plugins.OneSignal.addSubscriptionObserver(function(stateChanges) {
  console.log("Push subscription state changed: " + JSON.stringify(stateChanges, null, 2));
});

window.plugins.OneSignal.addPermissionObserver(function(stateChanges) {
  console.log("Push permission state changed: " + JSON.stringify(stateChanges, null, 2));
});

Other Functions

getDeviceState Function

(Async 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. Make sure to call getDeviceState again to get the latest state.

window.plugins.OneSignal.getDeviceState(function(stateChanges) {
  console.log('OneSignal getDeviceState: ' + JSON.stringify(stateChanges));
});

deviceState parameters:

requiresUserPrivacyConsent Function

Use this function to retrieve a boolean that indicates the application requires privacy consent.

window.plugins.OneSignal.requiresUserPrivacyConsent(function(require) {   
});

isLocationShared Function

Use this function to retrieve a boolean that indicates the application is sharing the location with OneSignal.

window.plugins.OneSignal.isLocationShared(function(shared) {   
});

disablePush Function

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

window.plugins.OneSignal.disablePush(true);

clearOneSignalNotifications Function

Android Only, use this function to manually remove all OneSignal notifications from the Notification Shade.

window.plugins.OneSignal.clearOneSignalNotifications();

removeNotification Function

Android Only, use this function to manually cancel a single OneSignal notification based on its Android notification integer ID.

window.plugins.OneSignal.removeNotification("NOTIFICATION_ID");

unsubscribeWhenNotificationsAreDisabled Function

Android Only, use this function to unsubscribe the user from OneSignal when notifications are disabled.

window.plugins.OneSignal.unsubscribeWhenNotificationsAreDisabled(true);

registerForProvisionalAuthorization Function

iOS Only, use this function to retrieve a boolean that indicates if the user-provided provisional authorization see documentation for more details'

window.plugins.OneSignal.registerForProvisionalAuthorization(function(accepted) {   
});

Other Additions / Changes

OSNotification Object

In version 4, the OSNotification class is composed of all notification properties in a single object. This is the object passed into the notificationWillShowInForeground handler.

setLogLevel

setLogLevel now accepts two params logLevel, visualLogLevel, instead of an object.
Example:
window.plugins.OneSignal.setLogLevel({logLevel: 6, visualLevel: 0}); becomes window.plugins.OneSignal.setLogLevel(6, 0);.