From 8a55aaa42954ceab424518f8fee2e6ce283e87f0 Mon Sep 17 00:00:00 2001 From: Hevin Date: Fri, 22 Sep 2017 20:13:25 +0800 Subject: [PATCH] Update README --- README.md | 2 +- doc/Common_detail_api.md | 284 ++++++++++++++++++++++++++++++--------- 2 files changed, 219 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 66d9d7e..2432dcb 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # JPush PhoneGap / Cordova Plugin [![Build Status](https://travis-ci.org/jpush/jpush-phonegap-plugin.svg?branch=master)](https://travis-ci.org/jpush/jpush-phonegap-plugin) -[![release](https://img.shields.io/badge/release-3.2.3-blue.svg)](https://github.com/jpush/jpush-phonegap-plugin/releases) +[![release](https://img.shields.io/badge/release-3.2.4-blue.svg)](https://github.com/jpush/jpush-phonegap-plugin/releases) [![platforms](https://img.shields.io/badge/platforms-iOS%7CAndroid-lightgrey.svg)](https://github.com/jpush/jpush-phonegap-plugin) [![weibo](https://img.shields.io/badge/weibo-JPush-blue.svg)](http://weibo.com/jpush?refer_flag=1001030101_&is_all=1) diff --git a/doc/Common_detail_api.md b/doc/Common_detail_api.md index 529b7f2..661e245 100644 --- a/doc/Common_detail_api.md +++ b/doc/Common_detail_api.md @@ -23,7 +23,9 @@ #### 接口定义 - window.plugins.jPushPlugin.init() +```js +window.JPush.init() +``` ### API - stopPush + Android 平台: @@ -43,7 +45,9 @@ #### 接口定义 - window.plugins.jPushPlugin.stopPush() +```js +window.JPush.stopPush() +``` ### API - resumePush @@ -59,7 +63,7 @@ #### 接口定义 - window.plugins.jPushPlugin.resumePush() + window.JPush.resumePush() ### API - isPushStopped @@ -73,37 +77,39 @@ #### 接口定义 - window.plugins.jPushPlugin.isPushStopped(callback) +```js +window.JPush.isPushStopped(callback) +``` #### 参数说明 -+ callback: 回调函数，用来通知 JPush 的推送服务是否开启。 +- callback: 回调函数，用来通知 JPush 的推送服务是否开启。 #### 代码示例 - window.plugins.jPushPlugin.isPushStopped(function (result) { - if (result == 0) { - // 开启 - } else { - // 关闭 - } - }) +```js +window.JPush.isPushStopped(function (result) { + if (result == 0) { + // 开启 + } else { + // 关闭 + } +}) +``` ## 开启 Debug 模式 ### API - setDebugMode 用于开启 Debug 模式，显示更多的日志信息。 -#### 接口定义 +#### 代码示例 - JPushPlugin.prototype.setDebugMode(isOpen) +```js +window.JPush.setDebugMode(true) +``` #### 参数说明 - isOpen: true，开启 Debug 模式；false，关闭 Debug 模式，不显示错误信息之外的日志信息。 -#### 代码示例 - - window.plugins.jPushPlugin.setDebugMode(true) - ## 获取 RegistrationID ### API - getRegistrationID @@ -117,7 +123,7 @@ JPush SDK 会以广播的形式发送 RegistrationID 到应用程序。 #### 接口定义 - JPushPlugin.prototype.getRegistrationID(callback) + window.JPush.getRegistrationID(callback) #### 返回值 @@ -125,14 +131,14 @@ JPush SDK 会以广播的形式发送 RegistrationID 到应用程序。 #### 代码示例 - window.plugins.jPushPlugin.getRegistrationID(function(data) { - console.log("JPushPlugin:registrationID is " + data) - }) +```js +window.JPush.getRegistrationID(function(rId) { + console.log("JPushPlugin:registrationID is " + rId) +}) +``` ## 设置别名与标签 -### API - setTagsWithAlias, setTags, setAlias - 提供几个相关 API 用来设置别名（alias）与标签（tags）。 这几个 API 可以在 App 里任何地方调用。 @@ -159,54 +165,200 @@ JPush SDK 会以广播的形式发送 RegistrationID 到应用程序。 举例： game, old_page, women。 -#### 接口定义 +> 以下方法的错误回调均包含 `sequence` 和 `code` 属性。其中 code 为错误码，具体定义可参考[官方文档](https://docs.jiguang.cn/jpush/client/Android/android_api/#_133)。 -```js -JPushPlugin.prototype.setTagsWithAlias(tags, alias, successCallback, errorCallback) -JPushPlugin.prototype.setTags(tags, successCallback, errorCallback) -JPushPlugin.prototype.setAlias(alias, successCallback, errorCallback) -``` +### setAlias -#### 参数说明 -* tags: - * 参数类型为数组。 - * nil 此次调用不设置此值。 - * 空集合表示取消之前的设置。 - * 每次调用至少设置一个 tag，覆盖之前的设置，不是新增。 - * 有效的标签组成：字母（区分大小写）、数字、下划线、汉字。 - * 限制：每个 tag 命名长度限制为 40 字节，最多支持设置 100 个 tag，但总长度不得超过1K字节（判断长度需采用 UTF-8 编码）。 - * 单个设备最多支持设置 100 个 tag，App 全局 tag 数量无限制。 -* alias: - * 参数类型为字符串。 - * nil 此次调用不设置此值。 - * 空字符串 （""）表示取消之前的设置。 - * 有效的别名组成：字母（区分大小写）、数字、下划线、汉字。 - * 限制：alias 命名长度限制为 40 字节（判断长度需采用 UTF-8 编码）。 +设置别名。注意这个接口是覆盖逻辑，而不是增量逻辑。即新的调用会覆盖之前的设置。 #### 代码示例 ```js -window.plugins.jPushPlugin.setTagsWithAlias([tag1, tag2], alias1, function () { - // success callback. -}, function (errorMsg) { - // errorMsg 格式为 'errorCode: error message'. -}) +window.JPush.setAlias({ sequence: 1, alias: 'your_alias' }, + (result) => { + var sequence = result.sequence + var alias = result.alias + }, (error) => { + var sequence = error.sequence + var errorCode = error.code + }) ``` -#### 错误码定义 +#### 参数说明 -|Code|描述 |详细解释 | -|----|:----------------------------------------|:--------| -|6001|无效的设置，tag / alias 不应参数都为 null。 | | -|6002|设置超时。 |建议重试。| -|6003|alias 字符串不合法。 |有效的别名、标签组成：字母（区分大小写）、数字、下划线、汉字。| -|6004|alias超长。 |最多 40个字节，中文 UTF-8 是 3 个字节。| -|6005|某一个 tag 字符串不合法。 |有效的别名、标签组成：字母（区分大小写）、数字、下划线、汉字。| -|6006|某一个 tag 超长。 |一个 tag 最多 40个字节，中文 UTF-8 是 3 个字节。| -|6007|tags 数量超出限制，最多 100 个。 |这是一台设备的限制，一个应用全局的标签数量无限制。| -|6008|tag / alias 超出总长度限制。 |总长度最多 1K 字节。| -|6011|10s内设置 tag 或 alias 大于 3 次。 |短时间内操作过于频繁。| +- sequence: number。用户自定义的操作序列号, 同操作结果一起返回，用来标识一次操作的唯一性。 +- alias: string + - 每次调用设置有效的别名将覆盖之前的设置。 + - 有效的别名组成：字母（区分大小写）、数字、下划线、汉字、特殊字符@!#$&*+=.|。 + - 限制：alias 命名长度限制为 40 字节（判断长度需采用 UTF-8 编码）。 +### deleteAlias + +删除别名。 + +#### 代码示例 + +```js +window.JPush.deleteAlias({ sequence: 1 }, + (result) => { + var sequence = result.sequence + }, (error) => { + var sequence = error.sequence + var errorCode = error.code + }) +``` + +#### 参数说明 + +- sequence: number。用户自定义的操作序列号, 同操作结果一起返回，用来标识一次操作的唯一性。 + +### getAlias + +查询别名。 + +#### 代码示例 + +```js +window.JPush.getAlias({ sequence: 1 }, + (result) => { + var sequence = result.sequence + var alias = result.alias + }, (error) => { + var sequence = error.sequence + var errorCode = error.code + }) +``` + +#### 参数说明 + +- sequence: number。用户自定义的操作序列号, 同操作结果一起返回，用来标识一次操作的唯一性。 + +### setTags + +设置标签。注意这个接口是覆盖逻辑，而不是增量逻辑。即新的调用会覆盖之前的设置。 + +#### 代码示例 + +```js +window.JPush.setTags({ sequence: 1, tags: ['tag1', 'tag2'] }, + (result) => { + var sequence = result.sequence + var tags = result.tags // 数组类型 + }, (error) => { + var sequence = error.sequence + var errorCode = error.code + }) +``` + +#### 参数说明 + +- sequence: number。用户自定义的操作序列号, 同操作结果一起返回，用来标识一次操作的唯一性。 +- tags: Array，标签数组。 + +### addTags + +新增标签。 + +#### 代码示例 + +```js +window.JPush.addTags({ sequence: 1, tags: ['tag1', 'tag2'] }, + (result) => { + var sequence = result.sequence + var tags = result.tags // 数组类型 + }, (error) => { + var sequence = error.sequence + var errorCode = error.code + }) +``` + +#### 参数说明 + +- sequence: number。用户自定义的操作序列号, 同操作结果一起返回，用来标识一次操作的唯一性。 +- tags: Array，标签数组。 + +### deleteTags + +删除指定标签。 + +#### 代码示例 + +```js +window.JPush.deleteTags({ sequence: 1, tags: ['tag1', 'tag2'] }, + (result) => { + var sequence = result.sequence + }, (error) => { + var sequence = error.sequence + var errorCode = error.code + }) +``` + +#### 参数说明 + +- sequence: number。用户自定义的操作序列号, 同操作结果一起返回，用来标识一次操作的唯一性。 +- tags: Array，标签数组。 + +### cleanTags + +清除所有标签。 + +#### 代码示例 + +```js +window.JPush.cleanTags({ sequence: 1 }, + (result) => { + var sequence = result.sequence + }, (error) => { + var sequence = error.sequence + var errorCode = error.code + }) +``` + +#### 参数说明 + +- sequence: number。用户自定义的操作序列号, 同操作结果一起返回，用来标识一次操作的唯一性。 + +### getAllTags + +获取当前绑定的所有标签。 + +#### 代码示例 + +```js +window.JPush.getAllTags({ sequence: 1 }, + (result) => { + var sequence = result.sequence + var tags = result.tags + }, (error) => { + var sequence = error.sequence + var errorCode = error.code + }) +``` + +#### 参数说明 + +- sequence: number。用户自定义的操作序列号, 同操作结果一起返回，用来标识一次操作的唯一性。 + +### checkTagBindState + +查询指定tag与当前用户绑定的状态。 + +#### 代码示例 + +```js +window.JPush.checkTagBindState({ sequence: 1, tag: 'tag1' }, + (result) => { + var sequence = result.sequence + }, (error) => { + var sequence = error.sequence + var errorCode = error.code + }) +``` + +#### 参数说明 + +- sequence: number。用户自定义的操作序列号, 同操作结果一起返回，用来标识一次操作的唯一性。 +- tag: string，待查询的 tag。 ## 获取点击通知内容 @@ -227,7 +379,7 @@ window.plugins.jPushPlugin.setTagsWithAlias([tag1, tag2], alias1, function () { } }, false) -> ps：点击通知后传递的 json object 保存在 window.plugins.jPushPlugin.openNotification，直接访问即可，字段示例，根据实际推送情况，可能略有差别，请注意。 +> ps：点击通知后传递的 json object 保存在 window.JPush.openNotification，直接访问即可，字段示例，根据实际推送情况，可能略有差别，请注意。 + Android: @@ -280,7 +432,7 @@ window.plugins.jPushPlugin.setTagsWithAlias([tag1, tag2], alias1, function () { }, false) -> ps：点击通知后传递的 json object 保存在 window.plugins.jPushPlugin.receiveNotification，直接访问即可，字段示例，根据实际推送情况，可能略有差别，请注意。 +> ps：点击通知后传递的 json object 保存在 window.JPush.receiveNotification，直接访问即可，字段示例，根据实际推送情况，可能略有差别，请注意。 + Android: @@ -334,7 +486,7 @@ window.plugins.jPushPlugin.setTagsWithAlias([tag1, tag2], alias1, function () { } }, false) -> ps：点击通知后传递的 json object 保存在 window.plugins.jPushPlugin.receiveMessage，直接访问即可，字段示例，根据实际推送情况，可能略有差别，请注意。 +> ps：点击通知后传递的 json object 保存在 window.JPush.receiveMessage，直接访问即可，字段示例，根据实际推送情况，可能略有差别，请注意。 + Android: @@ -371,7 +523,7 @@ window.plugins.jPushPlugin.setTagsWithAlias([tag1, tag2], alias1, function () { #### 代码示例 - window.plugins.jPushPlugin.getUserNotificationSettings(function(result) { + window.JPush.getUserNotificationSettings(function(result) { if(result == 0) { // 系统设置中已关闭应用推送。 } else if(result > 0) {