# Cordova 插件 API 参考

```txt title="示例"
var pushwoosh = cordova.require("pushwoosh-cordova-plugin.PushNotification");

// 应在 pushwoosh.onDeviceReady 之前调用
document.addEventListener('push-notification', function(event) {
	var notification = event.notification;
	// 在此处处理推送打开事件
});

// 初始化 Pushwoosh。这将在启动时触发所有待处理的推送通知。
pushwoosh.onDeviceReady({
	appid: "XXXXX-XXXXX",
	serviceName: "XXXX"
});

pushwoosh.registerDevice(
	function(status) {
		var pushToken = status.pushToken;
    	// 在此处处理成功注册
  },
  function(status) {
    // 在此处处理注册错误
  }
);
```

## onDeviceReady

```javascript
PushNotification.prototype.onDeviceReady = function( config )
```

_\[android, ios, wp8, windows]_
初始化 Pushwoosh 插件并触发启动推送消息。应在每次应用启动时调用。

`config.appid` – Pushwoosh 应用代码。

`config.serviceName` – 用于 wp8 平台的 MPNS 服务名称。

```txt title="示例"
// 使用 appid : "PUSHWOOSH_APP_ID", serviceName : "WINDOWS_PHONE_SERVICE" 初始化 Pushwoosh。这将在启动时触发所有待处理的推送通知。
pushwoosh.onDeviceReady({
    appid : "XXXXX-XXXXX",
    serviceName: "XXXX"
});
```

## registerDevice

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

_\[android, ios, wp8, windows]_
为推送通知注册设备并检索推送令牌 (Push Token)。

`success` – 成功回调。推送令牌作为 “status.pushToken” 参数传递给此回调。

`fail` – 错误回调。

```txt title="示例"
pushwoosh.registerDevice(
    function(status) {
        alert("已注册，推送令牌为: " + status.pushToken);
    },
    function(error) {
        alert("注册失败: " +  error);
    }
);
```

## unregisterDevice

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

_\[android, ios, wp8, windows]_
取消设备接收推送通知的注册。

`success` – 成功回调。

`fail` – 错误回调。

## setTags

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

_\[android, ios, wp8, windows]_
为设备设置标签 (tags)。

**参数**

`config` – 带有自定义设备标签的对象。

`success` – 成功回调。推送令牌作为 “status.pushToken” 参数传递给此回调。

`fail` – 错误回调。

```txt title="示例"
// 设置标签：“deviceName” 值为 “hello”，“deviceId” 值为 10
pushwoosh.setTags({deviceName:"hello", deviceId:10},
    function() {
        console.warn('setTags 成功');
    },
    function(error) {
        console.warn('setTags 失败');
    }
);

// 设置列表标签 "MyTag"，值为数组 ["hello", "world"]
pushwoosh.setTags({"MyTag":["hello", "world"]});
```

## getTags

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

_\[android, ios, wp8, windows]_
返回设备的标签，包括默认标签。

`success` – 成功回调。接收标签作为参数。

`fail` – 错误回调。

```javascript
pushwoosh.getTags(
    function(tags) {
        console.warn('设备的标签: ' + JSON.stringify(tags));
    },
    function(error) {
        console.warn('获取标签错误: ' + JSON.stringify(error));
    }
);
```

## getPushToken

```javascript
PushNotification.prototype.getPushToken = function(	success	)
```

_\[android, ios, wp8, windows]_
如果可用，则返回推送令牌。请注意，该令牌也会在 `registerDevice` 函数回调中返回。

`success` – 成功回调。

```javascript
pushwoosh.getPushToken(
    function(token) {
        console.warn('推送令牌: ' + token);
    }
);
```

## getPushwooshHWID

```javascript
PushNotification.prototype.getPushwooshHWID = function(	success	)
```

_\[android, ios, wp8, windows]_
返回用于与 Pushwoosh API 通信的 Pushwoosh HWID。

`success` – `getPushwooshHWID` 回调。

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

## getRemoteNotificationStatus

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

_\[android, ios]_
返回推送通知权限的详细状态。

`callback` – 成功回调。接收具有以下属性的对象：

```
{
  "enabled" : 通知启用标志。
  "pushBadge" : 已授予角标权限。(仅限 iOS)
  "pushAlert" : 已授予提醒权限。(仅限 iOS)
  "pushSound" : 已授予声音权限。(仅限 iOS)
}
```

`error` — 错误回调。

## setApplicationIconBadgeNumber

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

_\[android, ios]_
设置应用图标的角标数字。

`badgeNumber` – 图标角标数字。

## getApplicationIconBadgeNumber

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

_\[android, ios]_
返回应用图标的角标数字。

`callback` – 成功回调。

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

## addToApplicationIconBadgeNumber

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

_\[android, ios]_
向应用图标角标添加一个值。

`badgeNumber` — 增量图标角标数字。

## getLaunchNotification

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

_\[android, ios]_
如果应用是为响应推送通知而启动的，则返回推送通知的有效负载，否则返回 null。

`callback` – 成功回调。

## clearLaunchNotification

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

_\[android, ios]_
清除启动通知，此调用后 `getLaunchNotification()` 将返回 null。

## setUserId

```javascript
PushNotification.prototype.setUserId = function(	userId	)
```

_\[android, ios]_
设置用户标识符——Facebook ID、用户名、电子邮件或任何其他用户 ID。这允许在多个用户设备之间匹配数据和事件。

`userId` – 用户字符串标识符。

## postEvent

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

_\[android, ios]_
为应用内消息 (In-App Messages) 发布事件。这可以按照 Pushwoosh 控制面板中的指定触发应用内消息的显示。

`event` – 要触发的事件。

`attributes` – 带有附加事件属性的对象。

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

## createLocalNotification

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

_\[android, ios]_
安排本地通知。

`config.msg` – 通知消息。

`config.seconds` – 以秒为单位的通知延迟。

`config.userData` – 在通知中传递的附加数据。

`success` – 成功回调。

`fail` – 错误回调。

```
pushwoosh.createLocalNotification({msg:"您的南瓜已准备就绪！", seconds:30, userData:{}})
```

## clearLocalNotification

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

_\[android]_
清除由 `createLocalNotification` 创建的所有待处理的本地通知。

## clearNotificationCenter

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

_\[android]_
清除 Android 通知中心中显示的所有通知。

## setMultiNotificationMode

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

_\[android]_
允许多个通知显示在 Android 通知中心。

## setSingleNotificationMode

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

_\[android]_
只允许最后一个通知显示在 Android 通知中心。

## setSoundType

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

_\[android]_
为传入的推送设置默认声音。

`type` – 声音类型 (0 – 默认，1 – 无声，2 – 始终)。

## setVibrateType

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

_\[android]_
为传入的推送设置默认振动模式。

`type` – 振动类型 (0 – 默认，1 – 无振动，2 – 始终)。

## setLightScreenOnNotification

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

_\[android]_
当通知到达时点亮屏幕。

`on` – 启用/禁用屏幕解锁 (默认为禁用)。

## setEnableLED

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

_\[android]_
当通知到达且显示屏关闭时，启用 LED 闪烁。

`on` – 启用/禁用 LED 闪烁 (默认为禁用)。

## setColorLED

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

_\[android]_
设置 LED 颜色。与 [setEnableLED](#setenableled) 一起使用。

`color` – ARGB 整数格式的 LED 颜色。

## getPushHistory

```javascript
PushNotification.prototype.getPushHistory = function(	success	)
```

_\[android]_
返回接收到的推送通知数组。

`success` – 成功回调。

```
pushwoosh.getPushHistory(function(pushHistory) {
    if(pushHistory.length == 0)
        alert("无推送历史");
    else
        alert(JSON.stringify(pushHistory));
});

pushwoosh.clearPushHistory();
```

## clearPushHistory

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

_\[android]_
清除推送历史。

## cancelAllLocalNotifications

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

_\[ios]_
从通知中心清除所有本地通知。

## presentInboxUI

_\[android, ios]_
打开[收件箱](/zh/developer/guides/message-inbox/mobile-message-inbox)屏幕。

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

## setCommunicationEnabled

一个启用/禁用与 Pushwoosh 所有通信的二进制方法。布尔值 **false** 会取消设备接收推送通知的订阅，并停止下载应用内消息。值 **true** 则反转该效果。

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

## removeAllDeviceData

删除有关设备的所有数据。

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

## push-receive

_\[android, ios]_
推送通知接收事件。当应用在前台或后台接收到推送通知时触发。已关闭的应用不会接收此事件。

**事件属性**

`message` – (`string`) 推送通知消息

`userdata` – (`object`/`array`) 推送通知自定义数据

`onStart` – (`boolean`) 是否为启动通知

`foreground` – (`boolean`) 是否在前台接收到通知

`android` – (`object`) Android 特定通知有效负载

`ios` – (`object`) iOS 特定通知有效负载

`windows` – (`object`) Windows 特定通知有效负载

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

		if (typeof(userData) != "undefined") {
			// 处理自定义通知数据
			console.warn('用户数据: ' + JSON.stringify(userData));
		}
	}
);
```

## 前台通知

默认情况下，Pushwoosh 插件不会在前台显示通知，并会自动触发 `push-receive` 事件。有关控制此行为的信息，请参阅[插件自定义指南](/zh/developer/pushwoosh-sdk/cross-platform-frameworks/cordova/customizing-cordova-plugin/)。

### push-notification

_\[android, ios, wp8, windows]_
推送通知接受事件。当用户点击推送通知时触发。

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

		if (typeof(userData) != "undefined") {
			console.warn('用户数据: ' + JSON.stringify(userData));
		}
	}
);
```

**事件属性**

与 [push-receive](#push-receive) 相同

### additionalAuthorizationOptions

_\[仅限 ios]_
提供_额_外的[通知授权选项](https://developer.apple.com/documentation/usernotifications/unauthorizationoptions?language=objc)。应在调用 **registerDevice** 之前调用。

```
pushwoosh.additionalAuthorizationOptions({ 
	"UNAuthorizationOptionCriticalAlert" : 1,
	"UNAuthorizationOptionProvisional": 0 // 如果您不想将其添加到您的应用中，请设置为 0 或不指定该选项。
});
```