Cordova plugin API reference

example

var pushwoosh = cordova.require("pushwoosh-cordova-plugin.PushNotification");

// Should be called before pushwoosh.onDeviceReady
document.addEventListener('push-notification', function(event) {
  var notification = event.notification;
  // handle push open here
});

// Initialize Pushwoosh. This will trigger all pending push notifications on start.
pushwoosh.onDeviceReady({
  appid: "XXXXX-XXXXX",
  projectid: "XXXXXXXXXXXXXXX",
  serviceName: "XXXX"
});

pushwoosh.registerDevice(
  function(status) {
    var pushToken = status.pushToken;
      // handle successful registration here
  },
  function(status) {
    // handle registration error here
  }
);

onDeviceReady

PushNotification.prototype.onDeviceReady = function( config )

[android, ios, wp8, windows]
Initializes Pushwoosh plugin and triggers a start push message. Should be called on every app launch.

config.appid – Pushwoosh application code.

config.projectid – GCM project number for Android platform.

config.serviceName – MPNS service name for wp8 platform.

example

// initialize Pushwoosh with projectid: "GOOGLE_PROJECT_NUMBER", appid : "PUSHWOOSH_APP_ID", serviceName : "WINDOWS_PHONE_SERVICE". This will trigger all pending push notifications on start.
pushwoosh.onDeviceReady({
    appid : "XXXXX-XXXXX",
    projectid: "XXXXXXXXXXXXXXX",
    serviceName: "XXXX"
});

registerDevice

PushNotification.prototype.registerDevice = function( success, fail )

[android, ios, wp8, windows]
Registers device for push notifications and retrieves a push Token.

success – success callback. Push token is passed as “status.pushToken” parameter to this callback

fail – error callback

example

pushwoosh.registerDevice(
    function(status) {
        alert("Registered with push token: " + status.pushToken);
    },
    function(error) {
        alert("Failed to register: " +  error);
    }
);

unregisterDevice

PushNotification.prototype.unregisterDevice = function(  success, fail  )

[android, ios, wp8, windows]
Unregisters device from receiving push notifications.

success – success callback

fail – error callback

setTags

PushNotification.prototype.setTags = function(  config, success, fail  )

[android, ios, wp8, windows]
Sets tags for the device.

Parameters

config – object with custom device tags

success – success callback. Push token is passed as “status.pushToken” parameter to this callback

fail – error callback

example

// sets tags: “deviceName” with value “hello” and “deviceId” with value 10
pushwoosh.setTags({deviceName:"hello", deviceId:10},
    function() {
        console.warn('setTags success');
    },
    function(error) {
        console.warn('setTags failed');
    }
);

// sets list tags "MyTag" with values (array) "hello", "world"
pushwoosh.setTags({"MyTag":["hello", "world"]});

getTags

PushNotification.prototype.getTags = function(  success, fail  )

[android, ios, wp8, windows]
Returns tags for the device including default tags.

success – success callback. Receives tags as parameters

fail – error callback

pushwoosh.getTags(
    function(tags) {
        console.warn('tags for the device: ' + JSON.stringify(tags));
    },
    function(error) {
        console.warn('get tags error: ' + JSON.stringify(error));
    }
);

getPushToken

PushNotification.prototype.getPushToken = function(  success  )

[android, ios, wp8, windows]
Returns push token if it is available. Note that the token also comes in registerDevice function callback.

success – success callback.

pushwoosh.getPushToken(
    function(token) {
        console.warn('push token: ' + token);
    }
);

getPushwooshHWID

PushNotification.prototype.getPushwooshHWID = function(  success  )

[android, ios, wp8, windows]
Returns Pushwoosh HWID used for communications with Pushwoosh API.

success – getPushwooshHWID callback

pushwoosh.getPushwooshHWID(
    function(token) {
        console.warn('Pushwoosh HWID: ' + token);
    }
);

getRemoteNotificationStatus

PushNotification.prototype.getRemoteNotificationStatus = function(  callback, error  )

[android, ios]
Returns detailed status of push notification permissions.

callback – success callback. Receives object with following properties:

{
”enabled” : notificaions enabled flag.
”pushBadge” : badges permission granted. (iOS only)
”pushAlert” : alert permission granted. (iOS only)
”pushSound” : sound permission granted. (iOS only)
}

error — error callback

setApplicationIconBadgeNumber

PushNotification.prototype.setApplicationIconBadgeNumber = function(  badgeNumber  )

[android, ios]
Set the application icon badge number.

badgeNumber – icon badge number

getApplicationIconBadgeNumber

PushNotification.prototype.getApplicationIconBadgeNumber = function(  callback  )

[android, ios]
Returns application icon badge number.

callback – success callback

pushwoosh.getApplicationIconBadgeNumber(function(badge){ alert(badge);} );

addToApplicationIconBadgeNumber

PushNotification.prototype.addToApplicationIconBadgeNumber = function( badgeNumber )

[android, ios]
Adds value to application icon badge.

badgeNumber — incremental icon badge number

getLaunchNotification

PushNotification.prototype.getLaunchNotification = function(  callback  )

[android, ios]
Returns push notification payload if the app was started in response to a push notification, or null.

callback – success callback

clearLaunchNotification

PushNotification.prototype.clearLaunchNotification = function(  callback  )

[android, ios]
Clears launch notification, getLaunchNotification() will return null after this call.

setUserId

PushNotification.prototype.setUserId = function(  userId  )

[android, ios]
Sets User indentifier– a Facebook ID, username,email, or any other user ID. This allows data and events to be matched across multiple user devices.

userId – user string identifier

postEvent

PushNotification.prototype.postEvent = function( event, attributes )

[android, ios]
Posts events for In-App Messages. This can trigger In-App message display as specified in Pushwoosh Control Panel.

event – event to trigger

attributes – object with additional event attributes

pushwoosh.setUserId("XXXXXX");
pushwoosh.postEvent("buttonPressed", { "buttonNumber" : 4, "buttonLabel" : "banner" });

createLocalNotification

PushNotification.prototype.createLocalNotification = function( config, success, fail )

[android, ios]
Schedules local notification.

config.msg – notification message

config.seconds – notification delay in seconds

config.userData – additional data to pass in notification

success – success callback

fail – error callback

pushwoosh.createLocalNotification({msg:"Your pumpkins are ready!", seconds:30, userData:{}})

clearLocalNotification

PushNotification.prototype.clearLocalNotification = function()

[android]
Clears all pending local notifications created by createLocalNotification

clearNotificationCenter

PushNotification.prototype.clearNotificationCenter = function()

[android]
Clears all notifications presented in Android Notification Center.

setMultiNotificationMode

PushNotification.prototype.setMultiNotificationMode = function( success, fail )

[android]
Allows multiple notifications to be displayed in the Android Notification Center.

setSingleNotificationMode

PushNotification.prototype.setSingleNotificationMode = function(  success,
fail  )

[android]
Allows only the last notification to be displayed in Android Notification Center.

setSoundType

PushNotification.prototype.setSoundType = function( type, success, fail )

[android]
Sets default sound for incoming pushes.

type – Sound type (0 – default, 1 – no sound, 2 – always)

setVibrateType

PushNotification.prototype.setVibrateType = function(type, success, fail )

[android]
Sets default vibration mode for incoming pushes.

type – Vibration type (0 – default, 1 – no vibration, 2 – always)

setLightScreenOnNotification

PushNotification.prototype.setLightScreenOnNotification = function( on, success, fail )

[android]
Turns screen on when notification arrives.

on – enable/disable screen unlock (disabled by default)

setEnableLED

PushNotification.prototype.setEnableLED = function( on, success, fail )

[android]
Enables led blinking when notification arrives and display is off.

on – enable/disable LED blink (disabled by default)

setColorLED

PushNotification.prototype.setColorLED = function( color, success, fail )

[android]
Sets led color. Use with setEnableLED.

color – LED color in ARGB integer format

getPushHistory

PushNotification.prototype.getPushHistory = function(  success  )

[android]
Returns array of received push notifications.

success – success callback

pushwoosh.getPushHistory(function(pushHistory) {
    if(pushHistory.length == 0)
        alert("no push history");
    else
        alert(JSON.stringify(pushHistory));
});

pushwoosh.clearPushHistory();

clearPushHistory

PushNotification.prototype.clearPushHistory = function()

[android]
Clears push history.

cancelAllLocalNotifications

PushNotification.prototype.cancelAllLocalNotifications = function( callback )

[ios]
Clears all local notifications from the notification center.

presentInboxUI

[android, ios]
Opens Inbox screen.

PushNotification.prototype.presentInboxUI = function()

setCommunicationEnabled

A binary method enabling/disabling all communication with Pushwoosh. The boolean value is false unsubscribes the device from receiving push notifications and stops in-app messages download. The value true reverses the effect.

PushNotification.prototype.setCommunicationEnabled = function(enable, success, fail)

removeAllDeviceData

Removes all data about the device.

PushNotification.prototype.removeAllDeviceData = function()

push-receive

[android, ios]
Push notification receive event. Is fired when application receives push notification in foreground or background. Closed applications does not receive this event.

Event properties

message – (string) Push notification message

userdata – (object/array) Push notification custom data

onStart – (boolean) Is launch notification

foreground – (boolean) Is notification received in foreground

android – (object) Android specific notification payload

ios – (object) iOS specific notification payload

windows – (object) Windows specific notification payload

document.addEventListener('push-receive',
  function(event) {
    var userData = event.notification.userdata;

    if (typeof(userData) != "undefined") {
      // handle custom notification data
      console.warn('user data: ' + JSON.stringify(userData));
    }
  }
);

Foreground notifications

By default Pushwoosh plugin does not display notifications in the foreground and automatically triggers push-receive event. See plugin customization guide for controlling this behavior.

push-notification

[android, ios, wp8, windows]
Push notification accept event. It is fired when user taps the push notification.

document.addEventListener('push-notification',
  function(event) {
    var message = event.notification.message;
    var userData = event.notification.userdata;

    if (typeof(userData) != "undefined") {
      console.warn('user data: ' + JSON.stringify(userData));
    }
  }
);

Event properties

Same as push-receive

additionalAuthorizationOptions

[ios only]
Provides _a_dditional notification authorization options. Should be called before calling registerDevice.

pushwoosh.additionalAuthorizationOptions({
  "UNAuthorizationOptionCriticalAlert" : 1,
  "UNAuthorizationOptionProvisional": 0 // set 0 or don't specify the option if you don't want to add it to your app.
});