mipush

来自于:官方立即使用

概述

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及更高版本