html5在线api,HTML5+ API Reference

Push模块管理推送消息功能，可以实现在线、离线的消息推送，通过plus.push可获取推送消息管理对象。

方法：

对象：

ClientInfo: JSON对象，获取的客户端标识信息

PushMessage: JSON对象，推送消息对象

MessageOptions: JSON对象，获客户端创建本地消息的参数

回调方法：

权限：

permissions

{

// ...

"permissions":{

// ...

"Push": {

"description": "消息推送"

}

}

}

属性：

cover: 设定显示推送消息的模式

可取值true或false，true表示推送消息覆盖模式显示，即仅显示最后接收到的推送消息；false表示在系统消息中心显示多条消息。

默认值为ture。

平台支持

Android - 2.2+ (支持)

iOS - 4.3+ (不支持)

:

不支持覆盖消息，每条信息都在系统消息中心，忽略cover属性值。

添加推送消息事件监听器

void plus.push.addEventListener( event, listener, Boolean );

说明：

添加推送消息事件监听器，当指定推送事件发出时触发。

参数：

type:

(

String

)

必选事件类型

支持事件类型："click"-从系统消息中心点击消息启动应用事件；"receive"-应用从推送服务器接收到推送消息事件。

listener:

capture:

(

Boolean

)

可选是否捕获事件，此处可忽略

返回值：

void

: 无

平台支持：

Android

- 2.2+

(支持)

iOS

- 4.3+

(支持)

:

在客户端在运行时收到推送消息触发receive事件，离线接收到的推送消息全部进入系统消息中心。

示例：

Push Example

// 监听plusready事件

document.addEventListener('plusready', function(){

// 扩展API加载完毕，现在可以正常调用扩展API

// 添加监听从系统消息中心点击某条消息启动应用事件

plus.push.addEventListener('click', function(msg){

// 分析msg.payload处理业务逻辑

alert( 'You clicked: ' + msg.content );

}, false );

}, false);

清空所有推送消息

void plus.push.clear();

说明：

清空系统消息中心所有的推送消息。

参数：

无

返回值：

void

: 无

创建本地消息

void plus.push.createMessage( content, payload, option );

说明：

在本地直接创建推送消息，并添加到系统消息中心。

参数：

content:

(

String

)

必选

消息显示的内容，在系统通知中心中显示的文本内容。

payload:

(

String

)

可选

消息承载的数据，可根据业务逻辑自定义数据格式。

options:

创建消息的额外参数，参考MessageOptions。

返回值：

void

: 无

获取所有推送消息

PushMessage[] plus.push.getAllMessage();

说明：

获取客户端接收到的所有推送消息。

仅包括在系统消息中心显示的推送消息，不包括调用setAutoNotification(false)方法设置不显示推送消息后接收到的消息。

参数：

无

返回值：

PushMessage

: Array[PushMessage]对象，推送消息PushMessage数组。

平台支持：

Android

- 2.2+

(支持)

iOS

- 4.3+

(不支持)

:

无法获取系统消息中心的消息列表，调用此方法返回空数组。

获取客户端推送标识信息

ClientInfo plus.push.getClientInfo();

说明：

客户端标识信息用于业务服务器下发推送消息时提交给推送服务器的数据，用于说明下发推送消息的接收者(客户端)。

通常需要客户端在第一次运行时获取并提交到业务服务器绑定。

参数：

无

返回值：

ClientInfo

: 客户端推送标识信息对象

示例：

Push Example

// 监听plusready事件

document.addEventListener(‘plusready’, function(){

// 扩展API加载完毕，现在可以正常调用扩展API

// 获取客户端标识信息

var info = plus.push.getClientInfo();

alert( JSON.stringify( info ) );

// 添加监听从系统消息中心点击消息启动事件

plus.push.addEventListener(‘click’, function(msg){

// 分析msg.payload处理业务逻辑

alert('You clicked: ' + msg.content);

}, false);

}, false);

异步获取客户端推送标识信息

void plus.push.getClientInfoAsync(successCB, errorCB);

说明：

HBuilderX2.5.11+版本新增。

用于解决plus.push.getClientInfo同步获取可能返回数据为空的问题。

客户端标识信息用于业务服务器下发推送消息时提交给推送服务器的数据，用于说明下发推送消息的接收者(客户端)。

通常需要客户端在第一次运行时获取并提交到业务服务器绑定。

参数：

successCB:

成功获取客户端推送标识信息时触发。

errorCB:

获取客户端推送标识信息发生错误时触发。

返回值：

void

: 无

示例：

function getPushInfo(){

console.log("异步获取客户端推送标识信息");

plus.push.getClientInfoAsync(function(info){

console.log('Success');

console.log(JSON.stringify(info));

}, function(e){

console.log('Failed');

console.log(JSON.stringify(e));

})

}

设置程序是否将消息显示在系统消息中心

void plus.push.setAutoNotification( notify );

说明：

默认情况下程序在接收到推送消息后将会在系统消息中心显示，通过此方法可关闭默认行为，接收到推送消息后不在系统消息中心显示，通过addEventListener方法的“receive”事件监听处理接收到的消息。

在这种模式下可通过createMessage方法创建在系统消息中心显示的消息。

参数：

notify:

(

Boolean

)

必选是否自动提示推送消息

可取值true或false，true表示自动显示推送消息，false则不显示。默认值为true。

返回值：

void

: 无

平台支持：

Android

- 2.2+

(支持)

:

如果程序没有运行时接收到推送消息，则在程序启动后调用addEventListener方法监听“receive”事件时返回接收到的消息。

注意：个推平台仅透传消息才支持此功能，其它消息依然会显示到系统消息中心。

iOS

- 4.3+

(不支持)

:

无法修改是否显示离线推送消息，当程序在前台运行时接收到消息时一定不会添加到系统消息中心，当程序在不再前台运行时一定会添加到系统消息中。

示例：

Push Example

// 监听plusready事件

document.addEventListener( "plusready", function(){

// 扩展API加载完毕，现在可以正常调用扩展API

// 在程序运行时接收到的消息不显示在系统消息中心

plus.push.setAutoNotification( false );

}, false );

删除推送消息

void plus.push.remove( message )

说明：

删除系统消息中心指定的推送消息，可通过getAllMessage方法获取所有的消息后进行操作。

参数：

message:

返回值：

void

: 无

平台支持：

Android

- 2.2+

(支持)

iOS

- 4.3+

(不支持)

:

无法对单条消息进行删除操作，可调用clear()方法清空所有消息。

JSON对象，获取的客户端标识信息

属性：

id: (String

类型

)推送通道标识

目前支持以下推送通道：

"igexin" - 表示个推推送；

"mipush" - 表示小米推送；

"unipush" - 表示DCloud UniPush。

token: (String

类型

)设备令牌(iOS设备唯一标识)，用于APNS服务推送中标识设备的身份

平台支持

Android - 2.2+ (支持)

:

设备的唯一标识号，通常与clientid值一致。

iOS - 4.5+ (支持)

:

设备的DeviceToken值，向APNS服务器发送推送消息时使用。

clientid: (String

类型

)推送服务令牌(设备唯一标识)，用于标识推送信息接收者身份

第三方推送服务器管理的设备唯一标识，在iOS平台此值通常与token不同；在其它平台此值通常与token值一致。

此值与设备及应用都相关，即不同的apk/ipa安装到同一台设备上的值都不相同。

appid: (String

类型

)第三方推送服务的应用标识

第三方推送服务器管理的应用标识，通常需要在第三方推送服务器平台进行注册获取。

appkey: (String

类型

)第三方推送服务器的应用键值

第三方推送服务器管理的应用键值，通常需要在第三方推送服务器平台进行注册获取。

JSON对象，推送消息对象

属性：

title: (String

类型

)推送消息显示的标题

平台支持

Android - 2.2+ (支持)

iOS - ALL (支持)

:

。

content: (String

类型

)推送消息显示的内容

payload: (JSON

类型

)推送消息承载的数据

如果推送消息中传输的数据不符合JSON格式，则作为String类型数据保存。

aps: (JSON

类型

)Apple APNS推送协议数据

平台支持

Android - 2.2+ (不支持)

:

不支持此数据，返回值为undefined。

iOS - 5.0+ (支持)

:

仅封装标准APNS协议中的数据，其它数据封装在payload中。如果是通过本地API创建的消息此属性值则为undefined。

JSON对象，获客户端创建本地消息的参数

属性：

appid: (String

类型

)要启动流应用的appid

仅在流应用环境中有效，默认值为当前流应用的appid。

平台支持

Android - ALL (不支持)

iOS - ALL (不支持)

cover: (Boolean

类型

)是否覆盖上一次提示的消息

可取值true或false，true为覆盖，false不覆盖。

默认为false。

平台支持

Android - ALL (支持)

iOS - 10.0+ (支持)

:

iOS10以下系统不支持覆盖。

delay: (Number

类型

)提示消息延迟显示的时间

当设备接收到推送消息后，可不立即显示，而是延迟一段时间显示，延迟时间单位为s，默认为0s，立即显示。

icon: (String

类型

)推送消息的图标

本地图片地址，相对路径 - 相对于当前页面的host位置，如"a.jpg"，注意当前页面为网络地址则不支持； 绝对路径 - 系统绝对路径，如Android平台"/sdcard/logo.png"，此类路径通常通过其它5+ API获取的； 扩展相对路径URL(RelativeURL) - 以"_"开头的相对路径，如"_www/a.jpg"； 本地路径URL - 以“file://”开头，后面跟随系统绝对路径。

平台支持

Android - 2.3+ (支持)

iOS - ALL (不支持)

:

不支持自定义图片，固定使用应用图标。

sound: (String

类型

)推送消息的提示音

显示消息时的播放的提示音，可取值：

“system”-表示使用系统通知提示音；

“none”-表示不使用提示音；

默认值为“system”。

平台支持

Android - 2.3+ (支持)

iOS - ALL (支持)

:

当程序在前台运行时，提示音不生效。

注：通常应该设置延迟时间，当程序切换到后台才创建本地推送消息时生效。

title: (String

类型

)推送消息的标题

在系统消息中心显示的通知消息标题，默认值为程序的名称。

平台支持

Android - ALL (支持)

iOS - 10+ (支持)

:

iOS10及以上版本支持设置标题，低版本忽略此属性。

subtitle: (String

类型

)推送消息的副标题

平台支持

Android - ALL (不支持)

iOS - 10+ (支持)

:

iOS10及以上版本支持设置副标题，低版本忽略此属性。

when: (Date

类型

)消息上显示的提示时间

默认为当前时间，如果延迟显示则使用延时后显示消息的时间。

平台支持

Android - ALL (支持)

iOS - ALL (不支持)

:

不支持设定消息的显示时间，由系统自动管理消息的创建时间。

客户端接收到推送消息的回调函数

void onReceive( msg ) {

// Recieved push message code.

}

参数：

msg:

(

String

)

必选接收到的推送信息msg

返回值：

void

: 无

用户点击推送消息事件的回调函数

void onClick( msg ) {

// Clicked push message code.

}

参数：

msg:

(

String

)

必选用户点击的推送信息msg

返回值：

void

: 无

异步获取客户端推送标识信息成功的回调函数

void onSuccess( info ) {

// getClientInfo success.

}

说明：

异步获取客户端推送标识信息成功时回调。

参数：

info:

返回值：

void

: 无

异步获取客户端推送标识信息失败的回调函数

void onError(error){

// Handle the error

var code = error.code; // 错误编码

var message = error.message; // 错误描述信息

}

说明：

异步获取推送标识信息失败时触发。

参数：

error:

(

Exception

)

可选错误信息

可通过error.code(Number类型)获取错误编码；

可通过error.message(String类型)获取错误描述信息。

返回值：

void

: 无