一、小米推送简介
小米推送（MiPush）是小米公司向开发者提供的消息推送服务，通过在云端与客户端之间建立一条稳定、可靠的长连接，为开发者提供向客户端应用实时推送消息的服务，有效地帮助开发者触达用户，提升App活跃度。
依托强大的服务器集群，以及多年在手机即时通讯领域的技术积累，小米在消息推送服务这一领域有着丰富的经验和雄厚的实力。在保证推送消息的到达率及到达速度的同时，我们还设计了一套基于业界最高标准加密算法的安全措施，让应用消息的传输更加安全可靠。
截止2020年底，小米推送累计接入应用40000+，覆盖设备数13亿，每天发送消息100+亿条。
图1 小米推送服务业务逻辑
二、产品优势
1、MIUI系统级通道
小米推送在MIUI上的长连接由系统维护，能够充分的保障通知栏消息在MIUI上的送达率。设备联网的情况下，有效推送的送达率能达到90%以上。
2、稳定、安全、快速、灵活
小米推送支持通知栏消息，同时提供API接口和推送运营平台两种消息下发途径。SDK覆盖Android、服务端主流语言，只需半天时间集成，可以帮助开发者更好的结合自身业务逻辑，满足复杂业务场景需求。
3、全面的数据统计
推送运营平台提供包括App数据和消息数据等多维度的统计，帮助开发者更好的掌握应用数据，助力精细化运营。
4、自助调查工具
小米推送为开发者提供了一套完备的调查工具，可以辅助开发者自助查询设备与消息的送达/在线情况，实时把控消息状态。
三、推送功能介绍
1、推送的消息类型
通知栏消息
通知栏消息通过小米系统通道下发，不需要应用驻留后台。
客户端收到这类消息后，会直接在通知栏展现。用户点击弹出通知后，客户端SDK会将消息中携带的数据传递给应用，由应用决定下一步的动作。
通知栏消息展示效果如图2所示，主要内容包括消息标题、摘要、应用图标和时间。开发者可以自行定义具体展示内容。
关于通知栏消息有如下几点说明：
1. 消息成组
- MIUI10以上，同一个App的所有通知栏消息会聚合成一个消息组，消息组最多支持展示10条消息，超过10条消息，会自动删除一条最老的消息并补上来一条新消息。
- 消息组折叠状态下默认展示3条消息，多余的消息用+N标识，N=消息总数-3。特别的，如果该App的消息组位于通知栏首位，则会展示5条消息，超过5条的多余消息用+N标识。
- 如果手动点击或删除一条展示的消息，会自动补充上来一条消息展示。
2. 历史通知
- 小米澎湃OS（ Xiaomi HyperOS）起新增了历史通知的功能，应用的消息在通知栏长时间未点击，消息会进入历史通知；公信消息超24小时未点击消息消失，私信消息超48小时未点击消息消失。
- 公私信消息的分类规则，请参见《小米推送消息分类新规》。
- 不重要通知，详细介绍请参见文档：https://dev.mi.com/xiaomihyperos/documentation/detail?
2、推送方式
小米推送支持标签（Topic）、RegID、别名（Alias）、Useraccount四种消息发送方式。
2.1、基于标签的推送
标签（Topic）可以认为是具有某些相同属性的用户集合, 在应用初始化时或运行过程中，开发者可结合自己的业务特征，给用户打上不同的标签(Topic)。
在推送消息时，开发者可以结合每条消息的内容和目标用户，选择所对应的标签，完成请求后，小米推送服务会向所有打上这一标签的用户发送该消息，从而满足精准推送的需求。
注：
- 标签不会主动失效，只有开发者主动调用退订标签（unsubscribe）或设备标识（RegID/alias/useraccount）失效才会取消；
- 全部用户消息同样属于标签消息（设备注册时会注册一个默认标签用于发送全量消息）；
- 每个App单台设备可订阅标签的个数为30个；
- 每个标签可对应的设备数无上限;
- 标签可以和RegID与alias对应（具体方法请参见服务端Java SDK文档）;
- 标签消息在消息有效期结束之前，可以停止发送。停止后不能继续发送。只有标签消息可以停止，其余消息发送后不可停止。
2.2、基于 RegID的推送
RegID是小米推送为每个设备上的每个App注册推送服务时生成的唯一标识。
当开发者需要给一个或多个具体的设备推送消息时，可以使用基于 RegID的推送，将个性化的信息推送给指定的设备。这种方式适用于需要为每个用户订制个性化推送的场景。
注：
- RegID是在客户端向小米推送服务注册时，小米推送服务端根据设备标识、AppID以及当前时间戳生成，因此能够保证每个设备上每个App对应的regID都是不同的。
- RegID在应用卸载或清除本地数据后会重新生成；
- RegID在如下几种情况下会被判断失效：
① App卸载重装或者清除数据后重新注册，这种情况下会生成一个新的RegID，而老的RegID会失效；
② App调用了unregisterPush；
③ 在MIUI上，App卸载时，如果能成功上报，则RegID会被判定失效；
④ 设备超过30天没有和小米Push服务器建立长连接。
- 可以通过feedback接口从小米推送服务后台拉取失效RegID的列表，具体用法请参见《服务端Java SDK文档》。
2.3、基于别名（alias）的推送
别名（alias）是小米推送提供的一种个性化设定, 开发者可以将用户在应用内的账号或其它用户唯一标识设定为用户设备 RegID 的别名，在推送中可以直接基于别名进行推送。
别名不仅方便开发者将推送与自有的账号系统进行关联，同时也避免了因需要保存设备 RegID 与自有账号的对应关系而额外带来的开发和存储成本。
注：
- alias与RegID(设备)一一对应，同一个alias不能对应多个RegID，alias对应的RegID以最后一次setalias对应的RegID为准；
- 每个App单台设备可订阅alias的个数为15个；
- alias失效的可能原因如下：
① 主动调用unsetalias；
② alias对应的RegID已经失效；
③ 设置alias不成功（调用setalias失败）。
- alias只跟设备相关，所以请使用用户账号作为alias时，合理判断alias可能失效的情况。
2.4、基于useraccount的推送
useraccount主要适用于用户多点登陆的情况，与alias类似，同样可以作为应用自身的用户标识与RegID建立映射关系。
典型的场景就是用户的alias和user account都可以用来设置设备对应的用户账号，所不同的是，一个alias只能对应一台设备，如果有多台设备设置了同样的alias，则最后一个设置成功的生效，其它设备就会失效。而一个user account可对应20台以内的设备。因此如果应用是单点登录的，一个账号只会在一台设备上生效，用alias会比较合适。而如果产品需求是单账号多点登录同时接收消息，则用user account会更合适。
注：
useraccount最多可对应20台设备，并以最近注册的20台设备为准（如果第21台设备注册，则第一个注册的设备将会失效）。
3、其他个性化功能
3.1、定时推送
开发者可以根据业务需求自定义消息推送时间，可以选择立即推送或指定时间推送。定时消息功能可以指定未来30天内任意时间作为消息下发时间。定时消息在消息开始推送之前可以在“推送运营平台-消息记录-详情”中取消。
详细设置请参见《服务端Java SDK文档》中的timeToSend(long milliseconds)方法。
3.2、自定义消息有效期
开发者可以根据自己的业务需求设置每条推送消息的有效期，推送的目标用户在消息有效期内网络在线就会收到消息。公信消息有效期最长1天，私信消息有效期最长10天。详细设置请参见《服务端Java SDK文档》中的timeToLive(int milliseconds)方法。
3.3、自定义消息接收时间
小米推送支持为每个客户端设定可接收推送时间，开发者可以设置接收消息推送时间段，不在该时间段的推送消息会被缓存起来，到了合适的时段再向App推送被缓存的消息；
应用内设置免打扰时段的功能即可以通过自定义消息接收时间实现。
注：具体的设置方法请参见《Android客户端SDK文档》中的setAcceptTime方法。
3.4、通知分类
通知分类用来控制多条消息在通知栏内的替换关系。
相同通知分类消息会存在替换（新的消息会覆盖之前的），不同类通知可以在通知栏并存。最多可以有10001类通知并存。
因此，如果需要多条通知在通知栏内并存，请在推送时将将这些通知设置为不同的分类。
注：具体设置可以参考《服务端Java SDK文档》 notifyId(Integer id)。
3.5、自定义键值对
开发者可以自己输入一些自定义的键值对（key-value），在发送消息时传给客户端/服务端。客户端/服务端可以根据这些key-value可完成一些相应的操作。
3.6、平缓推送
开启平缓推送功能，开发者可自行控制消息发送速度，让消息匀速的送达至设备，以降低大量消息对服务器造成的负担。
平缓推送支持每秒1000~ 100000条消息，默认每秒3000条。
3.7、个性化场景推送
- 根据网络环境推送
开发者可以根据设备所处的环境进行推送，可以选择仅推送给处于WiFi环境下的用户。典型场景举例：视频类App可以推给WiFi条件下的用户，提升点击率。
- 按照应用版本推送
开发者可以通过指定应用的版本号来进行推送，可以选择某些版本接收消息/不接收消息。
注：版本号需要开发者自己指定。
四、使用推送
1、启用推送
登录小米开放平台，注册开发者账号并创建App，通过管理控制台启用推送服务，详细介绍请参见《小米推送服务启用指南》。
2、下载并集成客户端SDK
SDK下载地址：https://dev.mi.com/xiaomihyperos/documentation/detail?pId=1528
SDK集成和调试：
小米推送服务的客户端SDK集成非常简单，仅需一位工程师0.5天的时间即可完成客户端 SDK 的集成。
同时开发者也可以在接入SDK之前，通过接入demo的方式，快速体验小米推送的实际效果（仅限Android设备）（请参见《小米推送Andoid版快速接入指南》）。
Android详细的集成方式请参见：
Android：《Android版客户端SDK使用指南》
3、推送实现方式
3.1、API推送
通过小米推送提供的API接口，开发者可以自行构建并发送消息。包括个性化功能实现、获取统计数据、追踪消息状态、拉取失效数据等。小米推送官方提供了JAVA服务端SDK版本，如果无法满足需求，我们同样提供了http API，开发者可以在底层接口上自行进行封装，满足各种定制化的推送需求。
详细介绍请参见《服务端Java SDK文档》。
3.2、推送运营平台
推送运营平台是小米推送提供的管理和使用推送业务的一站式平台，通过运营平台开发者可以实现应用管理、消息下发、数据统计、使用人员管理等功能。
推送运营平台网页版推送工具可以帮助开发者通过运营平台快速实现消息下发。
支持通知栏消息下发，同时支持多种推送方式和个性化推送。
推送运营平台地址：http://admin.xmpush.xiaomi.com/
五、推送统计
小米推送支持推送数据实时统计功能，包括推送数据、App数据、消息记录等维度，帮助开发者更好的监控和分析业务现状。
开发者可以根据业务需求，登录推送运营后台查看，或者通过API接口获取。
API接口请参见《服务端 JavaSDK文档》中的“获取统计数据”一节。
六、常见问题&联系我们
关于推送接入及后续使用的常见问题，请参见《小米推送常见问题汇总》。
如有其它问题，也欢迎通过工单系统反馈
