# Cordova plugin API reference

```txt title="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",
	serviceName: "XXXX"
});

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

## onDeviceReady

```javascript
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.serviceName` – MPNS service name for wp8 platform.

```txt title="example"
// initialize Pushwoosh with appid : "PUSHWOOSH_APP_ID", serviceName : "WINDOWS_PHONE_SERVICE". This will trigger all pending push notifications on start.
pushwoosh.onDeviceReady({
    appid : "XXXXX-XXXXX",
    serviceName: "XXXX"
});
```

## registerDevice

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

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

## unregisterDevice

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

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

`success` – success callback

`fail` – error callback

## setTags

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

```txt title="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

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

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

## getPushToken

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

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

## getPushwooshHWID

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

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

```javascript
PushNotification.prototype.setApplicationIconBadgeNumber = function(	badgeNumber	)
```

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

`badgeNumber` – icon badge number

## getApplicationIconBadgeNumber

```javascript
PushNotification.prototype.getApplicationIconBadgeNumber = function(	callback	)
```

_\[android, ios]_\
Returns application icon badge number.

`callback` – success callback

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

## addToApplicationIconBadgeNumber

```javascript
PushNotification.prototype.addToApplicationIconBadgeNumber = function( badgeNumber )
```

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

`badgeNumber` — incremental icon badge number

## getLaunchNotification

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

```javascript
PushNotification.prototype.clearLaunchNotification = function(	callback	)
```

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

## setUserId

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

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

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

```javascript
PushNotification.prototype.clearLocalNotification = function()
```

_\[android]_\
Clears all pending local notifications created by createLocalNotification

## clearNotificationCenter

```javascript
PushNotification.prototype.clearNotificationCenter = function()
```

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

## setMultiNotificationMode

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

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

## setSingleNotificationMode

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

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

## setSoundType

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

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

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

_\[android]_\
Turns screen on when notification arrives.

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

## setEnableLED

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

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

_\[android]_\
Sets led color. Use with [setEnableLED](#setenableled).

`color` – LED color in ARGB integer format

## getPushHistory

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

```javascript
PushNotification.prototype.clearPushHistory = function()
```

_\[android]_\
Clears push history.

## cancelAllLocalNotifications

```javascript
PushNotification.prototype.cancelAllLocalNotifications = function( callback )
```

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

## presentInboxUI

_\[android, ios]_\
Opens [Inbox](/developer/guides/message-inbox/mobile-message-inbox) screen.

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

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

## removeAllDeviceData

Removes all data about the device.

```javascript
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](/developer/pushwoosh-sdk/cross-platform-frameworks/cordova/customizing-cordova-plugin/) 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](#push-receive)

### additionalAuthorizationOptions

_\[ios only]_\
Provides _a_dditional [notification authorization options](https://developer.apple.com/documentation/usernotifications/unauthorizationoptions?language=objc). 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. 
});
```