厂商通道 SDK 集成指南
本文旨在指导客户使用自动集成的方式集成各个厂商通道的 SDK,实现离线推送。
前提条件
- 已经集成Engagelab通道
- 集成厂商通道 SDK 需要先申请厂商通道相关参数,详情参考 厂商通道参数申请指南 。
资源文件
- 在res/drawable/下放好命名为
mtpush_notification_icon.png
的通知小图标。如果没配置,sdk会取应用图标,android高版本会出现显示异常问题
小米通道集成指南
配置 mavenCentral 支持
在 Project 根目录的主 gradle 中配置 mavenCentral 支持。(新建 project 默认配置就支持)
buildscript {
repositories {
mavenCentral()
}
}
allprojects {
repositories {
mavenCentral()
}
}
配置依赖
在应用 module 的 gradle 中 dependencies 节点添加如下代码:
dependencies {
//厂商版本和 Engagelab SDK 版本保持一致
implementation 'com.engagelab.plugin:mi:5.x.x'
}
配置参数
在应用 module 的 gradle 中 defaultConfig 节点添加如下代码:
manifestPlaceholders = [
// 设置manifest.xml中的变量
XIAOMI_APPKEY : "MI-您的应用对应的小米的APPID", // 小米平台注册的appkey
XIAOMI_APPID : "MI-您的应用对应的小米的APPKEY",// 小米平台注册的appid
]
配置代码混淆
如果使用了 proguard,为了防止误报的 warning 导致无法成功编译,需要在配置文件中加入以下内容:
-dontwarn com.xiaomi.push.**
-keep class com.xiaomi.push.** { *; }
集成结果判断
若集成成功,日志显示如下:
D [MTMiBusiness] support xiaomi push
D [MTMiBusiness] onTokenSuccess:get token is Tv3KBknVcnEaXnLe89MGEH3SWVgUYdLDYzJaST30IoIGATl2tv5eu6iuT/PTO0Mj
D [MTPlatformBusiness] onPlatformTokenSuccess, rid:5, platformToken:
{
platform=1,
token=Tv3KBknVcnEaXnLe89MGEH3SWVgUYdLDYzJaST30IoIGATl2tv5eu6iuT/PTO0Mj
region=NULL
isUserSettings=false
}
小米通道测试方法
1.进入【EngageLab控制台】-【AppPush】-【基础设置】-【集成设置】页面,填写参数:AppKey、AppID、AppSecret、并点击“保存”。
2.杀死 App 进程后进行推送,如果能够收到推送,则表明厂商通道集成成功。
小米 Android 13 及其以上系统特殊说明
根据小米官方说明,其 Android 13 及其以上版本,要求应用启动方式按照谷歌要求:显示调用必须精确匹配 Intent 过滤器,以确保应用在小米设备上的正常使用体验。
具体请查阅谷歌官方文档以了解更多关于 Android 13 及以上版本的 Intent 过滤器要求:Google 官方文档 - Intent 过滤器
开发者调测建议:
开发者可以在小米设备,开发者选项中,查找“应用兼容性变更”下的 ENFORCE_INTENTS_TO_MATCH_INTENT_FILTERS 开关,并在测试期间,考虑开启该选项,以确保应用在各种情况下都能正常运行。
华为通道集成指南
配置 mavenCentral 支持
在 Project 根目录的主 gradle 中配置 mavenCentral 支持和 agconnect 依赖。
buildscript {
repositories {
google()
mavenCentral()
maven {url 'https://developer.huawei.com/repo/'}
}
}
buildscript {
dependencies {
classpath 'com.huawei.agconnect:agcp:1.6.0.300'
}
}
allprojects {
repositories {
google()
mavenCentral()
maven {url 'https://developer.huawei.com/repo/'}
}
}
(可选)如果使用gradle 8.0版本,需要在项目级“gradle.properties”文件添加如下命令:
说明: 集成低于1.9.1.300版本的AGC插件,不支持兼容gradle 8.0版本,则需要执行此步骤。
apmsInstrumentationEnabled=false
添加华为插件
在应用 module 的 build.gradle 文件底部添加 apply plugin 代码行,以启用 gradle 插件:
apply plugin: 'com.huawei.agconnect'
配置依赖
在应用 module 的 gradle 中 dependencies 节点添加如下代码,可根据华为发布的版本更新选择最新版本:
dependencies {
implementation 'com.huawei.hms:push:6.11.0.300'
//厂商版本和 AppPush SDK 版本保持一致
implementation 'com.engagelab.plugin:huawei:5.x.x'
}
配置 agconnect-services.json 文件
参考 厂商通道参数申请指南 获取 agconnect-services.json 文件,并配置到 app 目录下。
配置签名证书
在 build.gradle 中配置在华为后台添加的指纹证书对应的签名。
HMS 服务必须要求 app 签名才能注册成功,可以在终端采用keytool -list -v -keystore keystorefileName 获取对应的指纹证书。
signingConfigs {
release {
storeFile file("release.keystore")//签名文件的path
storePassword "123456"
keyAlias "android.keystore"
keyPassword "123456"
}
}
buildTypes {
release {
minifyEnabled true
proguardFiles 'proguard-rules.pro'
signingConfig signingConfigs.release
}
debug{
minifyEnabled false
signingConfig signingConfigs.release
}
}
配置代码混淆
如果使用了 proguard,为了防止误报的 warning 导致无法成功编译,需要在配置文件中加入以下内容:
-ignorewarnings
-keepattributes *Annotation*
-keepattributes Exceptions
-keepattributes InnerClasses
-keepattributes Signature
-keepattributes SourceFile,LineNumberTable
-keep class com.hianalytics.android.**{*;}
-keep class com.huawei.updatesdk.**{*;}
-keep class com.huawei.hms.**{*;}
如果开发者使用了 AndResGuard,需要在混淆配置文件中加入 AndResGuard 白名单。
"R.string.hms*",
"R.string.connect_server_fail_prompt_toast",
"R.string.getting_message_fail_prompt_toast",
"R.string.no_available_network_prompt_toast",
"R.string.third_app_*",
"R.string.upsdk_*",
"R.layout.hms*",
"R.layout.upsdk_*",
"R.drawable.upsdk*",
"R.color.upsdk*",
"R.dimen.upsdk*",
"R.style.upsdk*",
"R.string.agc*"
集成结果判断
若集成成功,日志显示如下:
D [MTHuaweiBusiness] support huawei push
D [MTHuaweiBusiness] onTokenSuccess:get token is IQAAAACy0aL1AABEZ3l2C7jluCGX5XriooCvoOwK9TrjG1MTpH0CD47WPXFcAbtt3DdOeOPvX6d7xfAVctoyaOCGKRllRa-0RBP7WQrYI6SxnOp1GA
D [MTPlatformBusiness] onPlatformTokenSuccess, rid:5, platformToken:
{
platform=2,
token=IQAAAACy0aL1AABEZ3l2C7jluCGX5XriooCvoOwK9TrjG1MTpH0CD47WPXFcAbtt3DdOeOPvX6d7xfAVctoyaOCGKRllRa-0RBP7WQrYI6SxnOp1GA
region=NULL
isUserSettings=false
}
华为通道测试方法
1.进入【EngageLab控制台】-【AppPush】-【基础设置】-【集成设置】页面,填写参数:AppID、AppSecret、并点击“保存”。
2.杀死 App 进程后进行推送,如果能够收到推送,则表明厂商通道集成成功。
魅族通道集成指南
配置 mavenCentral 支持
在 Project 根目录的主 gradle 中配置 mavenCentral 支持。(新建 project 默认配置就支持)
buildscript {
repositories {
mavenCentral()
}
}
allprojects {
repositories {
mavenCentral()
}
}
配置依赖
在应用 module 的 gradle 中 dependencies 节点添加如下代码:
dependencies {
//厂商版本和AppPush SDK版本保持一致
implementation 'com.engagelab.plugin:meizu:5.x.x'
}
配置参数
在应用 module 的 gradle 中 defaultConfig 节点添加如下代码:
魅族的参数需要添加前缀 “MZ-”。
manifestPlaceholders = [
// 设置manifest.xml中的变量
MEIZU_APPKEY : "MZ-您的应用对应的魅族的APPKEY", // 魅族平台注册的appkey
MEIZU_APPID : "MZ-您的应用对应的魅族的APPID", // 魅族平台注册的appid
]
配置代码混淆
如果使用了 proguard,为了防止误报的 warning 导致无法成功编译,需要在配置文件中加入以下内容:
-dontwarn com.meizu.cloud.**
-keep class com.meizu.cloud.** { *; }
集成结果判断
若集成成功,日志显示如下:
D [MTMeizuBusiness] support meizu push
D [MTPlatformBusiness] onPlatformTokenSuccess, rid:5, platformToken:
{
platform=3,
token=DDI5c060475064d447b40670206756d73605705037205
region=NULL
isUserSettings=false
}
魅族通道获取不到token,尝试在 gradle.properties 中添加 android.enableR8 = false 进行关闭 R8
魅族厂商测试方法
1.进入【EngageLab控制台】-【AppPush】-【基础设置】-【集成设置】页面,填写参数:AppKey、AppID、AppSecret,并点击“保存”。
2.杀死 App 进程后进行推送,如果能够收到推送,则表明厂商通道集成成功。
vivo 通道集成指南
配置 mavenCentral 支持
在 Project 根目录的主 gradle 中配置 mavenCentral 支持。(新建 project 默认配置就支持)
buildscript {
repositories {
mavenCentral()
}
}
allprojects {
repositories {
mavenCentral()
}
}
配置依赖
在应用 module 的 gradle 中 dependencies 节点添加如下代码:
dependencies{
//厂商版本和 AppPush SDK 版本保持一致
implementation 'com.engagelab.plugin:vivo:5.x.x'
}
配置参数
在应用 module 的 gradle 中 defaultConfig 节点添加如下代码:
manifestPlaceholders=[
VIVO_APPKEY : "您的应用对应的VIVO的APPKEY", // VIVO平台注册的appkey
VIVO_APPID : "您的应用对应的VIVO的APPID", // VIVO平台注册的appid
]
集成结果判断
若集成成功,日志显示如下:
D [MTVivoBusiness] support vivo push
D [MTVivoBusiness] getRegId onTokenSuccess:get token is v2-CRrhwCeK9eY77H6m_EeUqz3zGqmbh0LJPnhvsF0V-ia9OmMHQP9FGCjZ
D [MTPlatformBusiness] onPlatformTokenSuccess, rid:5, platformToken:
{
platform=5,
token=v2-CRrhwCeK9eY77H6m_EeUqz3zGqmbh0LJPnhvsF0V-ia9OmMHQP9FGCjZ
region=NULL
isUserSettings=false
}
配置代码混淆
如果使用了 proguard,为了防止误报的 warning 导致无法成功编译,需要在配置文件中加入以下内容:
-dontwarn com.vivo.push.**
-keep class com.vivo.push.**{*; }
-keep class com.vivo.vms.**{*; }
vivo 通道测试方法
1.进入【EngageLab控制台】-【AppPush】-【基础设置】-【集成设置】页面,填写参数:AppKey、AppID、AppSecret,并点击“保存”。
2.杀死 App 进程后进行推送,如果能够收到推送,则表明厂商通道集成成功。
若 vivo 未上架,推送测试时需要在 vivo 推送平台添加测试设备,并且只能通过 API 指定推送参数 push_mode 进行下发。
"options": {
"classification": 1,
"third_party_channel": {
"vivo": {
"pushMode": 1, //可选,2020/09/21 新增,对应 vivo 的 pushMode 字段,值为int 类型,值分别是:“0”表示正式推送;“1”表示测试推送,不填默认为0
"distribution_new": "pns_mtpush"
}
}
}
OPPO 通道集成指南
配置 mavenCentral 支持
在 Project 根目录的主 gradle 中配置 mavenCentral 支持。(新建 project 默认配置就支持)
buildscript {
repositories {
mavenCentral()
}
}
allprojects {
repositories {
mavenCentral()
}
}
配置依赖
在应用 module 的 gradle 中 dependencies 节点添加如下代码:
dependencies{
//厂商版本和 AppPush SDK 版本保持一致
implementation 'com.engagelab.plugin:oppo:5.x.x'
implementation 'com.engagelab.plugin:oppo_th_push:5.x.x'
//OPPO需要以下依赖都需要添加
implementation 'com.google.code.gson:gson:2.8.9'
implementation 'commons-codec:commons-codec:1.13'
implementation 'androidx.annotation:annotation:1.1.0'
}
配置参数
在应用 module 的 gradle 中 defaultConfig 节点添加如下代码:
OPPO 的参数需要添加前缀 “OP-”。
manifestPlaceholders=[
OPPO_APPKEY : "OP-您的应用对应的OPPO的APPKEY", // OPPO平台注册的appkey
OPPO_APPID : "OP-您的应用对应的OPPO的APPID", // OPPO平台注册的appid
OPPO_APPSECRET: "OP-您的应用对应的OPPO的APPSECRET"//OPPO平台注册的appsecret
]
配置代码混淆
如果使用了 proguard,为了防止误报的 warning 导致无法成功编译,需要在配置文件中加入以下内容:
-dontwarn com.coloros.mcsdk.**
-keep class com.coloros.mcsdk.** { *; }
-dontwarn com.heytap.**
-keep class com.heytap.** { *; }
-dontwarn com.mcs.**
-keep class com.mcs.** { *; }
集成结果判断
若集成成功,日志显示如下:
D [MTOppoBusiness] support oppo push
D [MTOppoBusiness] onTokenSuccess:get token is OnePlus_CN_0e3c2f966c9d01d4e2423cbc9e7598b6
D [MTPlatformBusiness] onPlatformTokenSuccess, rid:5, platformToken:
{
platform=4,
token=OnePlus_CN_0e3c2f966c9d01d4e2423cbc9e7598b6
region=NULL
isUserSettings=false
}
OPPO 通道测试方法
1.进入【EngageLab控制台】-【AppPush】-【基础设置】-【集成设置】页面,填写参数:AppKey、AppID、AppSecret、MasterSecret,并点击“保存”。
2.杀死 App 进程后进行推送,如果能够收到推送,则表明厂商通道集成成功。
若应用未上架,需要在 OPPO 开放平台申请推送测试权限,每个应用每天可以推送1000条公信通道消息。
FCM 通道集成指南
配置 mavenCentral 支持
在 Project 根目录的主 gradle 中配置 mavenCentral 支持和 google-services 依赖。
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'com.google.gms:google-services:4.3.15'
}
}
allprojects {
repositories {
mavenCentral()
maven { url "https://maven.google.com" }
}
}
添加 FCM 插件
在应用 module 的 build.gradle 文件底部添加 apply plugin 代码行,以启用 gradle 插件:
apply plugin: 'com.google.gms.google-services'
配置依赖
在应用 module 的 gradle 中 dependencies 节点添加如下代码:
dependencies {
//厂商版本和 AppPush SDK 版本保持一致
implementation 'com.engagelab.plugin:google:5.x.x'
implementation 'com.google.firebase:firebase-messaging:23.2.0'
}
在应用 module 的 gradle 中 android 节点添加如下代码:
android {
// google push need java 1.8
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
配置 google-services.json文件
参考 厂商通道参数申请指南 获取 google-services.json 文件,并配置到 app 目录下。
配置 FCM 通知图标
在 AndroidManifest.xml 中增加如下配置来设置 FCM 通知图标。
<meta-data android:name="com.google.firebase.messaging.default_notification_icon"
android:resource="@drawable/您要配置的通知图标" />
集成结果判断
若集成成功,日志显示如下:
D [MTGoogleBusiness] support google push
D [MTPlatformBusiness] onPlatformTokenSuccess, rid:5, platformToken:
{
platform=8,
token=dj793yH_RO6FqNyKImQJYV:APA91bExj3PSVv50pwtl83LXVeB_HKOCSkyB6qCE12TIwIRl-RKiqCfXjvCshcqVrqn_8htlNBa8_A_8ixq7YIxfrloxig2BryZPCkunyx_z2drz0L-C2K8R7J8Yrojs61WCsF-BZj8h
region=NULL
isUserSettings=false
}
FCM 通道测试方法
1.测试前置条件
- 手机系统有 GooglePlay 服务且版本不低于17.3.4。
- 测试需要挂海外节点的VPN,手机网络可以正常访问谷歌。
- 若使用国内手机测试,只能退到后台测试,不能关闭后台,国内厂商对系统做了调整,关后台会杀进程。
2.进入【EngageLab控制台】-【AppPush】-【基础设置】-【集成设置】页面,填写参数:App Secret,并点击“保存”。
3.若在国内测试,需要在初始化之后设置国家码。
public class ExampleApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
MTCorePrivatesApi.configDebugMode(this, true);
// 设置国家码 -- 正式环境请不要设置
MTGlobal.setCountryCode("US");
// 初始化
MTPushPrivatesApi.init(this);
}
}
4.在AppPush后台查看推送的记录是 FCM 通道还是Engagelab通道。
荣耀通道集成指南
配置 mavenCentral 支持
在 Project 根目录的主 gradle 中配置 mavenCentral 支持。(新建 project 默认配置就支持)
buildscript {
repositories {
...
mavenCentral()
...
}
}
allprojets {
repositories {
...
mavenCentral()
...
}
}
配置参数和依赖
在项目 module 的 build.gradle 中添加如下代码:
defaultConfig {
...
manifestPlaceholders = [
...
HONOR_APPID : "您的应用对应的Honor的APP ID", // Honor平台注册的APP ID
...
]
...
}
dependencies {
...
//厂商版本和 AppPush SDK 版本保持一致
implementation 'com.engagelab.plugin:honor:5.x.x'
implementation 'com.engagelab.plugin:honor_th_push:5.x.x'
...
}
配置签名证书
在 build.gradle 中配置在荣耀后台添加的指纹证书对应的签名。
- 荣耀服务必须要求 app 签名才能注册成功。
- 可以在终端采用 keytool -list -v -keystore <签名文件的绝对路径> 获取对应的指纹证书。
- 如果没有签名文件或密钥口令,也可以在终端采用 keytool -list -printcert -jarfile < Apk 文件的绝对路径> 获取对应的指纹证书。
集成结果判断
若集成成功,日志显示如下:
D [MTHonorBusiness] support honor push
D [MTHonorBusiness] onTokenSuccess:get token is s18069ps301291893q1ssro2o40s1630-n262n542r9669q62o83s390306179rro-775875632-654-6105326555582-PA-0052993947080949113-5
D [MTPlatformBusiness] onPlatformTokenSuccess, rid:5, platformToken:
{
platform=7,
token=s18069ps301291893q1ssro2o40s1630-n262n542r9669q62o83s390306179rro-775875632-654-6105326555582-PA-0052993947080949113-5
region=NULL
isUserSettings=false
}
配置代码混淆
如果使用了 proguard,为了防止误报的 warning 导致无法成功编译,需要在配置文件中加入以下内容:
-ignorewarnings
-keepattributes *Annotation*
-keepattributes Exceptions
-keepattributes InnerClasses
-keepattributes Signature
-keepattributes SourceFile,LineNumberTable
-keep class com.hihonor.push.**{*;}
荣耀通道测试方法
1.进入【EngageLab控制台】-【AppPush】-【基础设置】-【集成设置】页面,填写参数:App ID、Client ID、Client Secrect、App Secret,并点击“保存”。
2.杀死 App 进程后进行推送,如果能够收到推送,则表明厂商通道集成成功。
如何不集成厂商SDK,但仍使用Engagelab推送厂商消息
/**
* 上报厂商通道通知到达
*
* 走http/https上报
*
* @param context 不为空
* @param messageId Engagelab消息id,不为空
* @param platform 厂商,取值范围(1:mi、2:huawei、3:meizu、4:oppo、5:vivo、8:google)
* @param platformMessageId 厂商消息id,可为空
*/
public static void reportNotificationArrived(Context context, String messageId, byte platform, String platformMessageId)
/**
* 上报厂商通道通知点击
*
* 走http/https上报
*
* @param context 不为空
* @param messageId Engagelab消息id,不为空
* @param platform 厂商,取值范围(1:mi、2:huawei、3:meizu、4:oppo、5:vivo、7:honor、8:google)
* @param platformMessageId 厂商消息id,可为空
*/
public static void reportNotificationClicked(Context context, String messageId, byte platform, String platformMessageId)
/**
* 上报厂商通道通知删除
*
* 走http/https上报
*
* @param context 不为空
* @param messageId Engagelab消息id,不为空
* @param platform 厂商,取值范围(1:mi、2:huawei、3:meizu、4:oppo、5:vivo、7:honor、8:google)
* @param platformMessageId 厂商消息id,可为空
*/
public static void reportNotificationDeleted(Context context, String messageId, byte platform, String platformMessageId)
/**
* 上报厂商通道通知打开
*
* 走http/https上报
*
* @param context 不为空
* @param messageId Engagelab消息id,不为空
* @param platform 厂商,取值范围(1:mi、2:huawei、3:meizu、4:oppo、5:vivo、7:honor、8:google)
* @param platformMessageId 厂商消息id,可为空
*/
public static void reportNotificationOpened(Context context, String messageId, byte platform, String platformMessageId)
/**
* 上传厂商token
*
* 需要在Engagelab长连接建立成功后再调用,否则无效。MTCommonReceiver.onConnectStatus回调结果为true时为长连接建立成功。
*
* 走tcp上传
*
* @param context 不为空
* @param platform 厂商,取值范围(1:mi、2:huawei、3:meizu、4:oppo、5:vivo、7:honor、8:google)
* @param token 厂商返回的token,不为空
*/
public static void uploadPlatformToken(Context context, byte platform, String token)