mipush

来自于：官方立即使用

• Method

registerPush setListener unregisterPush setAlias unsetAlias setUserAccount unsetUserAccount subscribe unsubscribe setAcceptTime pausePush resumePush clearNotification getRegId reportMessageClicked getAllAlias getAllTopic getAllUserAccount

概述

mipush模块封装了小米消息推送的SDK，使用此模块可实现接收推送通知和透传消息功能。

注意：使用了mipush或者其他非APICloud提供的push服务，如个推等，请登录官网，在推送设置界面将 APICloud 官方的推送关闭，避免因同时使用多个推送服务而带来设备资源的更多消耗，如耗电量增加等。

使用小米消息推送基本流程说明：

在小米开放平台网站（ http://dev.xiaomi.com ）注册帐号，并创建应用，获取APP_ID和APP_KEY

由于系统平台差异，iOS平台需要配置一个plist文件,配置参数如下：

<dict>
    <key>MiSDKAppID</key>
    <string>1000888</string>
    <key>MiSDKAppKey</key>
    <string>500088888888</string>
    <key>MiSDKRun</key>
    <string>online</string>
</dict>

MiSDKAppID, MiSDKAppKey 为在小米开发者网站http://developer.xiaomi.com ，注册App后的AppID,AppKey。

MiSDKRun 是设定SDK是连接 Development/Distribution 环境 对应参数为 Debug/Online，详情参考 plist 文件配置详情

注意： 在 iOS 平台上使用此模块之前需要先生成相关证书：

 打包证书：需要上传到 APICloud 平台
 描述文件：需要上传到 APICloud 平台
 推送证书：需要上传到小米服务器

iOS 相关证书生成请参考 iOS证书及描述文件制作流程

其他重要信息

在iOS平台，使用小米推送发送通知时，若应用在前台运行，则推送内容可以通过setListener方法监听到，若应用在后台，系统会往设备通知栏发送通知，当通知被点击后，APICloud会将本次推送的内容通过事件监听回调的方式交给开发者。具体使用如下：

api.addEventListener({
    name: 'noticeclicked'
}, function(ret, err) {
    if (ret) {
        var value = ret.value;
    }
})

registerPush

注册 miPush 推送服务。

注意：iOS 平台不需要设置任何参数，因为此前已经在 plist 文件里配置。

registerPush({params}, callback(ret, err))

params

appId：

• 类型：字符串
• 描述：在小米消息推送平台应用的appid

appKey：

• 类型：字符串数组
• 描述：在小米消息推送平台应用的appkey

callback(ret)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status: true,    //布尔类型；是否初始化成功
    regId: ,         //字符串类型；当前设备上当前app的唯一标示,您可以将                                regId上传到自己的服务器，方便向其发消息
    msg:             //字符串类型；表示调用命令失败的原因。如果失败，则返回                                失败原因，否则返回为 undifine
}

示例代码

var mipush = api.require('mipush');
mipush.registerPush({
    appId: '******',
    appKey: '******'
}, function(ret) {
    alert(JSON.stringify(ret));
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setListener

设置消息监听

setListener(callback(ret))

callback(ret)

ret：

• 类型：JSON 对象
• 内部字段：

{
    id:''               //字符串类型；消息id，可能为空
    notifyId:            //数字类型；通知id
    title:''             //字符串类型；消息标题，可能为空
    content:''          //字符串类型；消息内容
    extra:{}            //Json对象类型；额外键值对，可能为空
    messageType:''        //字符串类型；消息的类型，取值范围:reg、alias、topic、account
    alias:''            //字符串类型；消息的别名，当messageType为alias时有值
    topic:''            //字符串类型；消息的主题，当messageType为topic时有值
    account:''            //字符串类型；消息的主题，当messageType为account时有值
    passThrough:true    //布尔类型；是否为透传消息
    isNotified:true        //布尔类型；是否通过通知栏传给app的。如果为true，表示消息在通知                    栏出过通知；如果为false，表示消息是直接传给app的，没有弹出过通                        知
    aps:{           //JSON 对象类型；iOS平台上的推送信息
      alert:        //字符串类型；iOS平台上的推送信息内容
    }
}

示例代码

var mipush = api.require('mipush');
mipush.setListener(
    function(ret) {
        alert(JSON.stringify(ret));
    }
);

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

unregisterPush

关闭 miPush 推送服务。

在 Android 平台上，当用户希望不再使用 miPush 推送服务的时候调用，调用成功之后，app 将不会接收到任何 miPush 服务推送的数据，直到下一次调用 registerPush()。

在 iOS 平台上，会在应用下次启动时自动回复推送服务。

unregisterPush()

示例代码

var mipush = api.require('mipush');
mipush.unregisterPush();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setAlias

设置别名，服务端可以指定别名进行消息推送

setAlias({params}, callback(ret))

params

alias：

• 类型：字符串
• 描述：别名(length:128)

callback(ret)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status  : true          //布尔类型；是否设置成功
    msg :                     //字符串类型；表示调用命令失败的原因。如果失败，则返回失败                            原因，否则返回为null
}

示例代码

var mipush = api.require('mipush');
mipush.setAlias({
        alias: '******',
    },
    function(ret) {
        alert(JSON.stringify(ret));
    }
);

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

unsetAlias

取消指定用户的某个别名，服务端对指定别名不再进行消息推送

unsetAlias({params}, callback(ret, err))

params

alias：

• 类型：字符串
• 描述：别名

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status  : true          //布尔类型；是否设置成功
    msg :                     //字符串类型；表示调用命令失败的原因。如果失败，则返回失败                            原因，否则返回为null
}

示例代码

var mipush = api.require('mipush');
mipush.unsetAlias({
        alias: '******',
    },
    function(ret) {
        alert(JSON.stringify(ret));
    }
);

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setUserAccount

设置用户名，服务端可以指定用户名进行消息推送。

多设备设置同一个帐号, 发送消息时多设备可以同时收到

setUserAccount({params}, callback(ret, err))

params

account：

• 类型：字符串
• 描述：用户名(length:128)

示例代码

var mipush = api.require('mipush');
mipush.setUserAccount({
    account: '******',
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

unsetUserAccount

取消指定用户的某个用户名，服务端对指定用户名不再进行消息推送

unsetUserAccount({params}, callback(ret, err))

params

account：

• 类型：字符串
• 描述：用户名

示例代码

var mipush = api.require('mipush');
mipush.unsetUserAccount({
    account: '******',
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

subscribe

设置订阅的主题，服务端可以根据订阅的主题实现分组群发。

支持同时设置多个topic, 中间使用”,”分隔

subscribe({params}, callback(ret, err))

params

topic：

• 类型：字符串
• 描述：订阅的主题描述，支持同时设置多个topic， 中间使用 “,” 分隔

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status  : true          //布尔类型；是否设置成功
    msg :                     //字符串类型；表示调用命令失败的原因。如果失败，则返回失败                            原因，否则返回为null
}

示例代码

var mipush = api.require('mipush');
mipush.subscribe({
        topic: '******',
    },
    function(ret) {
        alert(JSON.stringify(ret));
    }
);

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

unsubscribe

取消指定用户订阅的主题

unsubscribe({params}, callback(ret, err))

params

topic：

• 类型：字符串
• 默认值：无
• 描述：用户名

callback(ret, err)

ret：

• 类型：JSON 对象

内部字段：

{
    status  : true          //布尔类型；是否设置成功
    msg :                     //字符串类型；表示调用命令失败的原因。如果失败，则返回失败                            原因，否则返回为null
}

示例代码

var mipush = api.require('mipush');
mipush.unsubscribe({
        topic: '******',
    },
    function(ret) {
        alert(JSON.stringify(ret));
    }
);

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setAcceptTime

设置接收miPush服务推送的时段，不在该时段的推送消息会被缓存起来，到了合适的时段再向app推送原先被缓存的消息，本接口不支持 iOS 平台

setAcceptTime({params}, callback(ret, err))

params

startHour：

• 类型：数字
• 默认值：0
• 描述：接收时段开始时间的小时（24小时制：startHour的范围为0到23）

startMin：

• 类型：数字
• 默认值：0
• 描述：接收时段开始时间的分钟（startMin的范围为0到59）

endHour：

• 类型：数字
• 默认值：23
• 描述：接收时段结束时间的小时（24小时制：endHour的范围为0到23）

endMin：

• 类型：数字
• 默认值：0
• 描述：接收时段结束时间的分钟（endMin的范围为0到59）

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status  : true          //布尔类型；是否设置成功
    msg :                     //字符串类型；表示调用命令失败的原因。如果失败，则返回失败                            原因，否则返回为null
}

示例代码

var mipush = api.require('mipush');
mipush.setAcceptTime({
        startHour: 8,
        startMin: 0,
        endHour: 9,
        endMin: 0
    },
    function(ret) {
        alert(JSON.stringify(ret));
    }
);

补充说明

这里采用24小时制，如果开始时间早于结束时间，则这个时段落在一天内；否则，这个时间将会跨越凌晨0点。

如果时间设置为0:00-0:00，就是暂停push推送服务，也可以直接调用pausePush()方法，其本质相同

如果时间设置为0:00-23:59，就是恢复push推送服务，即全天接收push推送消息，也可以直接调用resumePush()方法，其本质相同

可用性

Android系统

可提供的1.0.0及更高版本

pausePush

暂停接收miPush服务推送的消息，app在恢复miPush推送服务之前，不接收任何推送消息

pausePush()

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status  : true          //布尔类型；是否设置成功
    msg :                     //字符串类型；表示调用命令失败的原因。如果失败，则返回失败                            原因，否则返回为null
}

示例代码

var mipush = api.require('mipush');
mipush.pausePush(
    function(ret) {
        if (ret.status) {
            alert(JSON.stringify(ret));
        } else {
            alert(ret.msg);
        }
    }
);

补充说明

这里使用与RegId相关联的alias和topic推送消息，也是被暂停的。

可用性

iOS 系统，Android系统

可提供的1.0.0及更高版本

resumePush

恢复接收miPush服务推送的消息

resumePush()

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    status  : true          //布尔类型；是否设置成功
    msg :                     //字符串类型；表示调用命令失败的原因。如果失败，则返回失败                            原因，否则返回为null
}

示例代码

var mipush = api.require('mipush');
mipush.resumePush(
    function(ret) {
        alert(JSON.stringify(ret));
    }
);

补充说明

这里使用与 RegId 相关联的 alias 和 topic 推送消息，也是被恢复的；这时服务器会把暂停时期的推送消息重新推送过来。

可用性

iOS 系统，Android系统

可提供的1.0.0及更高版本

clearNotification

清除 miPush 发送到状态栏的通知

clearNotification({params}, callback(ret, err))

params

id：

• 类型：数字
• 描述：待清除的通知id（notifyId），不填时清除所有

示例代码

var miPush = api.require('mipush');
miPush.clearNotification({
    id: 1
});

可用性

iOS 系统，Android系统

可提供的1.0.0及更高版本

getRegId

获取客户端的RegId

getRegId()

callback(ret, err)

ret：

• 类型：JSON 对象
• 内部字段：

{
    regId  : ''          //字符串类型，客户端的RegId
}

示例代码

var mipush = api.require('mipush');
mipush.getRegId(
    function(ret) {
        alert(JSON.stringify(ret));
    }
);

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

reportMessageClicked

上报点击的消息，用于统计开发者获取消息的点击率，你想使用服务器帮你统计你app的点击率请自行调用此方法，可在 setListener 的回调函数中调用此方法

reportMessageClicked()

params

id：

• 类型：字符串
• 描述：消息id

示例代码

var mipush = api.require('mipush');
mipush.reportMessageClicked({
    id: '******'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getAllAlias

获取客户端所有设置的别名

getAllAlias()

callback(ret)

ret：

• 类型：JSON 对象
• 内部字段：

{
    aliasList  : []          //数组类型，客户端所有设置的别名
}

示例代码

var mipush = api.require('mipush');
mipush.getAllAlias(
    function(ret) {
        alert(JSON.stringify(ret));
    }
);

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getAllTopic

获取客户端所有订阅的主题。

getAllTopic()

callback(ret)

ret：

• 类型：JSON 对象
• 内部字段：

{
    topicList  : []          //数组类型，客户端所有订阅的主题
}

示例代码

var mipush = api.require('mipush');
mipush.getAllTopic(
    function(ret) {
        alert(JSON.stringify(ret));
    }
);

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getAllUserAccount

获取客户端所有设置的帐号

getAllUserAccount()

callback(ret)

ret：

• 类型：JSON 对象
• 内部字段：

{
    accountList  : []          //数组类型，客户端所有设置的帐号
}

示例代码

var mipush = api.require('mipush');
mipush.getAllUserAccount(
    function(ret) {
        alert(JSON.stringify(ret));
    }
);

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本