集成推送平台 PushSDK 设计文档 此文档在于向开发者介绍魅族统一推送平台 PushSDK 如何对各个厂家的 PushSDK 进行整合以及我们在统一接口设计中遵循的规则, 由于各个厂家的 API 接口功能差异巨大我们只对各个厂商共用的接口进行统一封装, 当然你也可以直接使用厂商提供的接口 UpsPushSDK 设计初衷不仅仅是在帮助开发者接入魅族的统一推送平台, 也希望我们能够尽量简化接口的同时, 能够将厂商所有的个性化接口全部提供给开发者, 即使开发者不使用魅族统一推送平台也能通过各个厂商提供推送服务平台快速接入 背景 目前各个主流厂商为了优化手机耗电情况, 实行静默后台策略, 导致很多应用无法常驻后台, 导致基于长连接的推送应用也无法常驻后台, 进而影响推送消息的到达率, 因此各个主流厂商 ( 小米, 华为, 魅族 ) 都提供基于系统推送服务的方案, 应用需要接入各个厂商的 PushSDK 才能在各个平台的手机上接收推送消息 此项目为了屏蔽不同厂商 PushSDK 的接入流程, 为开发这提供统一的接口, 方便开发者一次集成, 即可完成不同厂商的 PushSDK 的接入 一. 接入说明 快速接入文档详见统一推送平台的规则说明 二. 接口说明 为了统一接入方式,ups-meizu-pushsdk 沿用魅族 pushsdk 的接口的定义方式, 其主要包括 UpsPushManager 功能入口类和接收消息回调的广播回调类 UpsPushReceiver 2.1 UpsPushManager 接入类
接口名称 register(context,string appid,string appkey) unregister(context ) setalias(context,string alias) unsetalias(context,string alias) 接口说明 订阅接口 反订阅接口 订阅别名 取消别名 使用建议 建议 Application oncreate 调用 取消所有推送时使用, 慎用, 如果取消, 将有可能停止所有推送 无 无 是已经废弃 对应 UpsPushReceiver 回调方法 onupscommandresult(context, UpsCommandMessage upscommandmessage) onupscommandresult(context, UpsCommandMessage upscommandmessage) onupscommandresult(context, UpsCommandMessage upscommandmessage) onupscommandresult(context, UpsCommandMessage upscommandmessage) 2.2 UpsPushMessageReceiver 广播接收器 UpsPushMessageReceiver 是一个抽象的 BroadcastReceiver 类, 为了统一各个厂商的回调, 必须定义通用的方法, 在包装数据格式时只是原样返回, 不做任何修饰, 里面定义了五个方法, 分别为 onthroughmessage,onnotificationclicked,onnotificationarrived,onnotifi cationdeleted,onupscommandresult 接口名称接口说明使用建议 onthroughmessage(context,upspushmessage upspushmessage) onnotificationclicked(context, UpsPushMessage upspushmessage) 是已经废弃 透传消息回调无 通知栏点击回调无
接口名称接口说明使用建议 onnotificationarrived(context, UpsPushMessage upspushmessage) onnotificationdeleted(context, UpsPushMessage upspushmessage) onupscommandresult(context, UpsCommandMessage upscommandmessage) 通知栏展示回调 通知栏删除回调 小米, 魅族尽在应用进程在时回调, 华为不回调 仅仅 Flyme 基于 android6.0 以下版本会回调, 小米华为均不支持 无 是已经废弃 三. UPSManager API 详细说明 3.0 public static void enabledirectmode(context, boolean enable) 是启用直连模式, 启用该模式可以直接进行相应厂商接口调试, 在发起订阅, 别名相关操作时不再与魅族推送平台进行交互,UpsPushReceiver 直接返回相关平台信息 NOTE: 正式发布时请关闭此模式, 默认该模式关闭 3.1 public static void register(context,string appid,string appkey) 注册统一推送服务, 建议在应用启动时调用 Android 平台上 app 的上下文, 建议传入当前 app 的 application appid appkey 应用在统一集成平台申请的 appid 应用在统一集成平台申请的 appkey
3.2 public static void unregister(context ) 反订阅推送服务, 关闭推送时使用 Android 平台上 app 的上下文, 建议传入当前 app 的 application 3.3 public static void setalias(context,string alias) Android 平台上 app 的上下文, 建议传入当前 app 的 application alias 应用别名 3.4 public static void unsetalias(context,string alias) Android 平台上 app 的上下文, 建议传入当前 app 的 application alias 应用别名 四. UpsPushMessageReceiver 回调方法详细说明 4.1 public void onthroughmessage(context,upspushmessage upspushmessage) 接收透传消息回调 NOTE: Android 平台上 app 的上下文, 建议传入当前 app 的 application
upspushmessage 服务端返回的结果全部封装在 upspushmessage 对象中, 可以从对象中和获取例如 content title extra pushtype NOTE: UpsPushMessage 在设计 UpsPushMessage 时我们尽量保证将厂商提供的参数信息回调给用户, 方便开发者能够使用各个厂商的个性化功能 参数名 title content pushtyp e extra 消息的标题, 如果时通知栏消息, 则为通知栏标题 消息内容, 如果时通知栏则为消息通知栏内容, 如果为透传消息, 则为透传消息体 消息类型,0 代表通知栏消息,1 代表透传消息 厂商类型包括 : UpsPushMessage.MEIZU,UpsPushMessage.HUAWEI,UpsPushMessage.XI AOMI 代表各个平台的传递的对象, 魅族代表 selfdefinecontentstring, 小米代表 MiPushMessage, 华为代表 bundle, 需要通过判断 进行对象类型转化, 如下 : if(==upspushmessage.meizu){ string extra = extra; } else if(==upspushmessage.xiaomi){ MiPushMessage mipushmssage = (MiPushMessage)extra; } else if(==upspushmessage.huawei){ Bundle bundle = (Bundle)extra; } 4.2 public void onnotificationclicked(context, UpsPushMessage upspushmessage) 接收通知栏消息点击回调 Android 平台上 app 的上下文, 建议传入当前 app 的 application
upspushmessage 服务端返回的结果全部封装在 upspushmessage 对象中, 可以从对象中和获取例如 content title extra pushtype NOTE: UpsPushMessage 在设计 UpsPushMessage 时我们尽量保证将厂商提供的参数信息回调给用户, 方便开发者能够使用各个厂商的个性化功能 参数名 title content pushtyp e notifyi d extra 消息的标题, 如果时通知栏消息, 则为通知栏标题 消息内容, 如果时通知栏则为消息通知栏内容, 如果为透传消息, 则为透传消息体 消息类型,0 代表通知栏消息,1 代表透传消息 通知栏消息 Id 厂商类型包括 : UpsPushMessage.MEIZU,UpsPushMessage.HUAWEI,UpsPushMessage.XI AOMI 代表各个平台的传递的对象, 魅族代表 selfdefinecontentstring, 小米代表 MiPushMessage, 华为代表 bundle, 需要通过判断 进行对象类型转化, 如下 : if(==upspushmessage.meizu){ string extra = extra; } else if(==upspushmessage.xiaomi){ MiPushMessage mipushmssage = (MiPushMessage)extra; } else if(==upspushmessage.huawei){ Bundle bundle = (Bundle)extra; } 4.3 public void onnotificationarrived(context, UpsPushMessage upspushmessage) 接收通知栏消息到达回调 Android 平台上 app 的上下文, 建议传入当前 app 的 application
upspushmessage 服务端返回的结果全部封装在 upspushmessage 对象中, 可以从对象中和获取例如 content title extra pushtype NOTE: UpsPushMessage 在设计 UpsPushMessage 时我们尽量保证将厂商提供的参数信息回调给用户, 方便开发者能够使用各个厂商的个性化功能 参数名 title content pushtyp e notifyi d extra 消息的标题, 如果时通知栏消息, 则为通知栏标题 消息内容, 如果时通知栏则为消息通知栏内容, 如果为透传消息, 则为透传消息体 消息类型,0 代表通知栏消息,1 代表透传消息 通知栏消息 Id 厂商类型包括 : UpsPushMessage.MEIZU,UpsPushMessage.HUAWEI,UpsPushMessage.XI AOMI 代表各个平台的传递的对象, 魅族代表 selfdefinecontentstring, 小米代表 MiPushMessage, 华为代表 bundle, 需要通过判断 进行对象类型转化, 如下 : if(==upspushmessage.meizu){ string extra = extra; } else if(==upspushmessage.xiaomi){ MiPushMessage mipushmssage = (MiPushMessage)extra; } else if(==upspushmessage.huawei){ Bundle bundle = (Bundle)extra; } 4.4 public void onnotificationdeleted(context, UpsPushMessage upspushmessage) 接收通知栏消息删除回调 Android 平台上 app 的上下文, 建议传入当前 app 的 application
upspushmessage 服务端返回的结果全部封装在 upspushmessage 对象中, 可以从对象中和获取例如 content title extra pushtype NOTE: UpsPushMessage 在设计 UpsPushMessage 时我们尽量保证将厂商提供的参数信息回调给用户, 方便开发者能够使用各个厂商的个性化功能 参数名 title content pushtyp e notifyi d extra 消息的标题, 如果时通知栏消息, 则为通知栏标题 消息内容, 如果时通知栏则为消息通知栏内容, 如果为透传消息, 则为透传消息体 消息类型,0 代表通知栏消息,1 代表透传消息 通知栏消息 Id 厂商类型包括 : UpsPushMessage.MEIZU,UpsPushMessage.HUAWEI,UpsPushMessage.XI AOMI 代表各个平台的传递的对象, 魅族代表 selfdefinecontentstring, 小米代表 MiPushMessage, 华为代表 bundle, 需要通过判断 进行对象类型转化, 如下 : if(==upspushmessage.meizu){ string extra = extra; } else if(==upspushmessage.xiaomi){ MiPushMessage mipushmssage = (MiPushMessage)extra; } else if(==upspushmessage.huawei){ Bundle bundle = (Bundle)extra; } 4.5 public void onupscommandresult(context, UpsCommandMessage upscommandmessage) 接收订阅, 反订阅, 别名订阅, 取消别名订阅回调 Android 平台上 app 的上下文, 建议传入当前 app 的 application
upscommandmessage 服务端返回的结果全部封装在 upscommandmessage 对象中, 可以从对象中和获取例如 code,message,commandtype,commandresult NOTE: UpsCommandMessage 具体 参数名 code message commandty pe commandre sult extra 表示订阅, 反订阅的返回码, 如果成功, 即返回 UPS.SUCCESS==200, 则返回错误状态码 表示执行请求返回的成功与错误信息 表示请求服务类型, 目前包括四种 UpsManager.REGISTER,UpsManager.UNREGISTER,UpsManager.SUBAL IAS,UpsManager.UNSUBALIAS 表示执行成功后, 服务端返回的结果参数, 例如订阅成功后, 返回的 pushid. 厂商类型包括 : UpsPushMessage.MEIZU,UpsPushMessage.HUAWEI,UpsPushMessage. XIAOMI 代表各个平台传递对象, 魅族为空, 小米为 MiPushCommandMessage, 华为为 Bundle, 需要通过 进行类型转换如下代码 : if(==upspushmessage.meizu){ string extra = extra; } else if(==upspushmessage.xiaomi){ MiPushCommandMessage mipushcommandmessage = (MiPushCommandMessage)extra; } else if(==upspushmessage.huawei){ Bundle bundle = (Bundle)extra; } 五技术实现 5.1 UpsManager 接口代理 UpsManager 调用的定义的 API 最终会调用各个厂商提供的 API, 我们展示屏蔽了具体进行厂商判断的细节, 以及对接魅族统一推送平台的接口 以下为订阅逻辑的逻辑图 :
具体步骤基本和厂商 sdk 的逻辑一致, 只是增加了上报魅族统一推送平台订阅状态的逻辑, 该逻辑我们可以考虑是支持上报, 即使此步骤执行不成功, UpsReceiver 也会回调各个厂商的状态, 完全不必担心此逻辑会影响厂商的具体的订阅发起与回调逻辑 NOTE: 以上步骤值讨论了订阅的逻辑, 其他如别名订阅与此大致一致 License /* * MIT License * * Copyright (c) [2017] [Meizu.inc] * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in all * copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE * SOFTWARE. */