OPPO推送服务客户端SDK接入

目前SDK版本为V3.0.0，只支持Android 4.4或以上版本的手机系统，如无特殊说明，兼容历史版本。开发者技术支持：QQ群1(1125363958)、QQ群2(1125372593)。

二、SDK接入流程

2.1、开通推送权限

具体权限申请流程可参考【推送服务开启指南】

2.2、获取秘钥等验证信息

申请通过后，可在OPPO推送平台-配置管理-应用配置-页面查看AppKey、AppSecret和MasterSecret（仅开发者帐号（主帐号）可查看）。

名词解释：AppKey、AppSecret客户端的身份标识，客户端SDK初始化时使用。

三、SDK集成步骤

3.1.注册并下载SDK

Android的SDK以aar形式提供，第三方APP只需要添加少量代码即可接入OPPO推送服务。代码参考demo下载：heytapPushDemo.rar（3.0.0版本）

下载aar文件，即3.0.0版本sdk：OPPO PUSH 客户端SDK（3.0.0版本）

3.2.gradle配置文件

3.2.1)maven依赖
第一步：添加maven仓库

maven {
url 'https://maven.columbus.heytapmobi.com/repository/releases/'
credentials {
username 'nexus'
password 'c0b08da17e3ec36c3870fed674a0bcb36abc2e23'
}
}

第二步：添加maven依赖

implementation com.heytap.msp:push:3.0.0

3.2.2)aar依赖
第一步：添加maven依赖

implementation(name: 'push-3.0.0', ext: 'aar')
//以下依赖都需要添加
implementation 'com.google.code.gson:gson:2.6.2'
implementation 'commons-codec:commons-codec:1.6'
implementation 'androidx.annotation:annotation:1.1.0'

第二步：添加aar配置
1)在build文件中添加以下代码

Android{
....
repositories {
flatDir {
dirs 'libs'
}
}
....
}

3.3.配置AndroidManifest.xml

1)OPPO推送服务SDK支持的最低安卓版本为Android 4.4系统。
<uses-sdk  android:minSdkVersion="19"/>2)推送服务组件注册
//必须配置
<serviceandroid:name="com.heytap.msp.push.service.XXXService"    android:permission="com.heytap.mcs.permission.SEND_PUSH_MESSAGE"android:exported="true"><intent-filter><action android:name="com.heytap.mcs.action.RECEIVE_MCS_MESSAGE"/>
<action android:name="com.heytap.msp.push.RECEIVE_MCS_MESSAGE"/></intent-filter>
</service>（兼容Q版本，继承DataMessageCallbackService）<serviceandroid:name="com.heytap.msp.push.service.XXXService"
android:permission="com.coloros.mcs.permission.SEND_MCS_MESSAGE"
android:exported="true"><intent-filter><action android:name="com.coloros.mcs.action.RECEIVE_MCS_MESSAGE"/></intent-filter>
</service>（兼容Q以下版本，继承CompatibleDataMessageCallbackService）

3.4.注册推送服务

1)应用推荐在Application类主线程中调用HeytapPushManager.init(…)接口，这个方法不是耗时操作，执行之后才能进行后续操作。

2)业务需要调用api接口，例如应用内开关开启/关闭，需要调用注册接口之后，才会生效。

3)由于不是所有平台都支持MSP PUSH，提供接口HeytapPushManager.isSupportPush()方便应用判断是否支持,支持才能执行后续操作。

4)通过调用HeytapPushManager.register(…)进行应用注册，注册成功后,您可以在ICallBackResultService的onRegister回调方法中得到regId,您可以将regId上传到自己的服务器，方便向其发消息。初始化相关参数具体要求参考详细API说明中的初始化部分。

5)为了提高push的注册率，你可以在Application的onCreate中初始化push。你也可以根据需要，在其他地方初始化push。如果第一次注册失败,第二次可以直接调用PushManager.getInstance().getRegister()进行重试,此方法默认会使用第一次传入的参数掉调用注册。

3.5.混淆配置

-keep public class * extends android.app.Service
-keep class com.heytap.msp.** { *;}

四、详细API说明

4.1.DataMessageCallbackService 和CompatibleDataMessageCallbackService的回调方法

processMessage(Context context, DataMessage message){
}
DataMessage是mcs回调给应用的透传消息

里面包含notifyId，如果业务通过透传消息，后续业务自身逻辑创建的通知栏消息，想要撤回，务必用message携带的notifyId展示，否则可能无法撤回

业务通过以下方式判断消息类型

获取DataMessage.getMessageType()进行判断

内部透传	透传消息
MessageConstant.MessageType.MESSAGE_APP	MessageConstant.MessageType.MESSAGE_DATA

4.2.HeytapPushManager

4.2.1.接口定义

   /***初始化MSP服务，创建默认通道*@param context必须传入当前app的context*@param needLog是否需要设置log*/1）void init (Context context，bool needLog)/***获取Mcs的包名*/2）string getMcsPackageName ()/***获取接收消息服务的action*/3）string getReceiveSdkAction ()/***判断是否手机平台是否支持PUSH@param context传入应用上下文*@return true 表示手机平台支持PUSH, false表示不支持*/4）boolean isSupportPush (Context context)/*** （旧埋点）消息事件统计接口，用于进行额外的Push消息事件统计   ** @param context 应用的context* @param message 需要上报的消息或消息列表*///会在以后的版本逐渐废弃5）void statisticMessage (Context context, MessageStat message)6）void statisticMessage (Context context, List < MessageStat > messages)/*** （新埋点）消息事件统计接口，用于进行额外的Push消息事件统计，如有需要使用，请开发者提前与OppoPush团队进行充分沟通和确认,为了防止业务方频繁调用上报** @param context 应用的context* @param eventId 需要上报的eventId事件，上报的eventId在EventConstant类中* @param eventId 透传消息下发的消息体*7）void statisticEvent(Context context,String eventId , DataMessage message)/***获取registerId*/8）String getRegisterID ()/***设置registerId*/9）void setRegisterID (String mRegisterID)/*** 注册MSP推送服务* @param applicatoinContext必须传入当前app的applicationcontet* @param appKey 在开发者网站上注册时生成的，与AppKey相对应* @param appSecret 与AppSecret相对应* @param ICallBackResultService SDK操作的回调*/10）void register (Context applicatoinContext, String appKey, String appSecret, ICallBackResultServiceICallBackResultService );/*** 设置appKey等参数,可以覆盖register中的appkey设置* @param appKey 在开发者网站上注册时生成的key* @param appSecret*/11）void setAppKeySecret (String appKey, String appSecret);/***获取pushcall回调*/12）ICallBackResultService getPushCallback ()/*** 设置sdk操作回调处理,可以覆盖register中的ICallBackResultService设置* @param ICallBackResultService sdk操作回调处理*/13）void setPushCallback (ICallBackResultService ICallBackResultService );/*** 解注册MSP推送服务*/14）void unRegister ();/*** 获取注册OPush推送服务的注册ID,此方法用于提高注册率，里面调用的是注册的逻辑，引用之前传入的参数*/15）void getRegister ()/*** 暂停接收MSP服务推送的消息*/16）void pausePush ();/*** 恢复接收MSP服务推送的消息，这时服务器会把暂停时期的推送消息重新推送过来*/17）void resumePush ();/*** 客户端设置通知消息的提醒类型,当服务端指定了消息的提醒类型，会优选考虑客户端设置的。*/18）void setNotificationType ( int notificationType)/*** 清除客户端设置的通知消息提醒类型。*/19）void clearNotificationType ()/*** 清除通知*/20）void clearNotifications ()/*** 获取MSP推送服务状态*/21）void getPushStatus ();/*** 获取MSP推送服务SDK版本（例如”2.1.0”）** @return SDKVersion*/22）String getSDKVersionCode ();/*** 获取MSP推送服务SDK名称** @return SDKVersionName*/23）String getSDKVersionName ();/*** 获取MSP推送服务MCS版本(例如“2400”)** @return PushVersionCode*/24）String getPushVersionCode ();/*** 获取MSP推送服务MCS版本(例如“2.4.0”)** @return PushVersionName*/25）String getPushVersionName ();/*** 设置允许推送时间 API** @param weekDays 周日为0,周一为1,以此类推* @param startHour 开始时间,24小时制* @param endHour 结束时间,24小时制*/26）void setPushTime (List< Integer > weekDays, int startHour, int start Min, int endHour, int endMin);/*** 弹出通知栏权限弹窗（仅一次）*/27）void requestNotificationPermission ();/*** 打开通知栏设置界面*/28）void openNotificationSetting ();/*** 获取通知栏状态，从callbackresultservice回调结果*/29）void getNotificationStatus ();/*** 打开应用内通知*@see ISetAppNotificationCallBackService*/30）void enableAppNotificationSwitch (ISetAppNotificationCallBackService callBackService);/*** 关闭应用内通知*@see ISetAppNotificationCallBackService*/31）void disableAppNotificationSwitch (ISetAppNotificationCallBackService callBackService);/*** 获取应用内通知开关*@see IGetAppNotificationCallBackService*/32）void getAppNotificationSwitch (IGetAppNotificationCallBackService callBackService);

4.2.2.接口说明
应用在没有获取到registerId时,需要先调用register进行注册,注册成功后才可以进行后续操作。如果调用register注册失败,可以调用getRegister使用上一次传入的参数进行重试。
调用requestNotificationPermission显示通知权限弹窗，用户可通过弹窗自行选择是/否打开应用的通知权限。建议在Activity的onResume方法中调用该接口以避免和其他弹窗重叠。重复调用该接口，弹窗也仅会显示一次。

4.3.ICallBackResultService

4.3.1.接口定义

//注册的结果,如果注册成功,registerID就是客户端的唯一身份标识
void onRegister(int responseCode, String registerID);//反注册的结果
void onUnRegister(int responseCode);//获取当前的push状态返回,根据返回码判断当前的push状态,返回码具体含义可以参考[错误码]
void onGetPushStatus(int responseCode,int status);
public class PushStatus {public static final int PUSH_STATUS_START = 0;public static final int PUSH_STATUS_PAUSE = 1;public static final int PUSH_STATUS_STOP = 2;
}//获取当前通知栏状态，返回码具体含义可以参考[错误码]
void onGetNotificationStatus(int responseCode,int status);
public class NotificatoinStatus {public static final int STATUS_OPEN = 0;public static final int STATUS_CLOSE = 1;
}//获取设置推送时间的执行结果
void onSetPushTime(int responseCode, String pushTime)//错误码返回的接口(当前主要是用于调用频繁的回调，后续可做拓展)
void onError(int code, String msg)

4.3.2.接口说明
所有回调都需要根据responseCode来判断操作是否成功，0 代表成功,其他代码失败，失败具体原因可以查阅附录中的错误码列表。
onRegister接口返回的registerID是当前客户端的唯一标识，app开发者可以上传保存到应用服务器中,在发送push消息是可以指定registerID发送。

4.4.ISetAppNotificationCallBackService

4.4.1.接口定义

//设置应用内通知开关结果,如果成功返回0，失败返回非0，具体指参考错误码
void onSetAppNotificationSwitch(int responseCode);

4.4.2.接口说明
建议复用使用一个callBackService，避免后面对象覆盖调前面一个对象导致前面的callBackService无返回。

4.5.IGetAppNotificationCallBackService

4.5.1.接口定义

//获取应用内通知开关结果,如果成功返回0，失败返回非0，具体指参考错误码
//appSwich：0：未定义状态（不校验开关），1：打开状态，2：关闭状态
void onGetAppNotificationSwitch(int responseCode, int appSwitch);

4.5.2.接口说明
建议复用使用一个callBackService，避免后面对象覆盖调前面一个对象导致前面的callBackService无返回。

五、错误码定义说明

参考类com.coloros.mcssdk.mode.ErrorCode中的错误码定义进行处理，详细如下：

通用错误码：

Code	英文描述	中文描述
-5	ERROR_REGISTERID_CHECK_ERROR	监测registerId有误
-4	ERROR_APPPACKAGE_EMPTY	应用包名为空
-3	ERROR_DEVICEID_NULL	设备id为空
-2	ERROR	初始值
-1	SERVICE_CURRENTLY_UNAVAILABLE	服务不可用，请开发者稍候再试
0	SUCCESS	成功，只表明接口调用成功

应用注册接口错误码：

Code	英文描述	中文描述
11	Insufficient ISV Permissions	无此API调用权限，开发者权限不足
12	Http Action Not Allowed	HTTP 方法不正确
13	App Call Limited	应用调用次数超限，包含调用频率超限
14	Invalid App Key	无效的AppKey参数
15	Missing App Key	缺少AppKey参数
16	Invalid Signature sign	校验不通过，无效签名
17	Missing Signature	缺少签名参数
18	Missing Timestamp	缺少时间戳参数
19	Invalid Timestamp	非法的时间戳参数
20	Invalid Method	不存在的方法名
21	Missing Method	缺少方法名参数
22	Missing Version	缺少版本参数
23	Invalid Version	非法的版本参数，用户传入的版本号格式错误，必需为数字格式
24	Unsupported Version	不支持的版本号，用户传入的版本号没有被提供
25	Invalid encoding	编码错误，一般是用户做http请求的时候没有用UTF-8编码请求造成
26	IP Black List	IP黑名单
40	Missing Required Arguments	缺少必选参数，API文档中设置为必选的参数是必传的，请仔细核对文档
41	Invalid Arguments	参数错误，一般是用户传入参数非法引起的，请仔细检查入参格式、范围是否一一对应

onError错误码

Code	英文描述	中文描述
-1	ERROR_CODE_REGISTER_API_FREQUENTLY	注册频繁调用
-2	ERROR_CODE_UNREGISTER_API_FREQUENTLY	注销频繁调用
-3	ERROR_CODE_PAUSE_API_FREQUENTLY	停止推送频繁调用
-4	ERROR_CODE_RESUME_PUSH_API_FREQUENTLY	恢复推送频繁调用
-5	ERROR_CODE_GET_NOTIFICATION_STATUS_API_FREQUENTLY	获取通知栏状态频繁调用
-6	ERROR_CODE_SET_NOTIFICATION_TYPE_API_FREQUENTLY	设置通知栏tyye频繁调用
-7	ERROR_CODE_CLEAR_NOTIFICATION_TYPE_API_FREQUENTLY	清除通知栏type频繁调用
-8	ERROR_CODE_OPEN_NOTIFICATION_SETTINGS_API_FREQUENTLY	打开通知栏设置界面频繁调用
-9	ERROR_CODE_CLEAR_NOTIFICATIONS_API_FREQUENTLY	清除通知栏消息频繁调用
-10	ERROR_CODE_GET_PUSH_STATUS_API_FREQUENTLY	获取push状态频繁调用
-11	ERROR_CODE_SET_PUSH_TIME_API_FREQUENTLY	设置push时间频繁调用
-12	ERROR_CODE_REQUEST_NOTIFICATION_PERMISSION_API_FREQUENTLY	请求通知栏权限频繁调用
-13	ERROR_CODE_SEND_INSTANT_ACK_API_FREQUENTLY	发送ack频繁调用
-14	ERROR_CODE_STATISTIC_FREQUENTLY	埋点上报频繁调用
-15	ERROR_CODE_ENABLE_APP_NOTIFICATION_FREQUENTLY	关闭应用通知栏频繁调用
-16	ERROR_CODE_DISABLE_APP_NOTIFICATION_FREQUENTLY	开启应用通知栏频繁调用
-17	ERROR_CODE_GET_APP_NOTIFICATION_FREQUENTLY	获取应用通知栏状态频繁

六、性能指标和SDK包大小

1)性能指标：响应时间小于500毫秒
2)sdk包大小：500kb以内