本文介绍 Android SDK 4.x 的初始化、注册、设备标识、推送开关、日志和通知权限相关接口。
适用于移动推送 Android SDK 4.x,本文接口和示例以已发布的 4.0.0 版本为基线。使用 3.x 的应用请参见对应的 3.x API 文档。
初始化和调用顺序
在应用的 Application.onCreate() 中初始化 SDK。init 用于配置 SDK;register 用于注册推送服务。请在满足应用隐私授权等业务条件后调用 register。
以下类分别位于 com.alibaba.sdk.android.push.noonesdk(PushInitConfig、PushServiceFactory)和 com.alibaba.sdk.android.push(CloudPushService、CommonCallback)。
以下示例中的 application 为当前应用的 Application 实例。CloudPushService 的接口须在 init 完成后调用;账号、标签等业务操作应在 register 成功后执行。
使用配置对象初始化(init)
通过 PushInitConfig 配置应用和 AppKey、AppSecret。
所属类:PushServiceFactory。
接口定义
public static void init(PushInitConfig pushInitConfig);
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
pushInitConfig |
PushInitConfig |
是 |
初始化配置对象,其中 application 必须为非空的 Application 实例。 |
返回值
无(void)。初始化完成后调用 register 注册推送服务。
代码示例
PushInitConfig config = new PushInitConfig.Builder()
.application(application)
.appKey("YOUR_APP_KEY")
.appSecret("YOUR_APP_SECRET")
.build();
PushServiceFactory.init(config);val config = PushInitConfig.Builder()
.application(application)
.appKey("YOUR_APP_KEY")
.appSecret("YOUR_APP_SECRET")
.build()
PushServiceFactory.init(config)使用 Manifest 配置初始化(init)
读取 AndroidManifest.xml 中配置的 AppKey 和 AppSecret,初始化 SDK。
使用此重载前,需在 AndroidManifest.xml 的 application 节点下配置 com.alibaba.app.appkey 和 com.alibaba.app.appsecret。两种 init 方式选择一种即可。每次 init 都会恢复默认的 MessageReceiver 分发方式,如需使用自定义 IntentService,应在 init 后设置。
所属类:PushServiceFactory。
接口定义
public static void init(Context appContext);
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
appContext |
Context |
是 |
应用上下文,不能为空。 |
返回值
无(void)。
代码示例
PushServiceFactory.init(application.getApplicationContext());PushServiceFactory.init(application.applicationContext)获取推送服务实例(getCloudPushService)
获取 CloudPushService 实例,用于调用注册、推送开关等接口。
所属类:PushServiceFactory。
接口定义
public static CloudPushService getCloudPushService();
参数说明
无。
返回值
CloudPushService:推送服务实例。获取实例不会自动完成初始化或注册。
代码示例
CloudPushService pushService = PushServiceFactory.getCloudPushService();val pushService = PushServiceFactory.getCloudPushService()初始化配置(PushInitConfig.Builder)
以下方法用于构建传给 init 的配置对象。application、appKey 和 appSecret 返回当前 Builder,支持链式调用。
|
配置方法 |
参数 |
说明 |
|
PushInitConfig.Builder application(Application application) |
Application |
必填,应用 Application。 |
|
PushInitConfig.Builder appKey(String appKey) |
String |
EMAS 应用 AppKey;如已在 Manifest 正确配置可省略。 |
|
PushInitConfig.Builder appSecret(String appSecret) |
String |
与 AppKey 配套的 AppSecret;如已在 Manifest 正确配置可省略。 |
|
PushInitConfig build() |
无 |
创建初始化配置对象。 |
配置应用(application)
配置当前应用的 Application 实例,不能为空。
所属类:PushInitConfig.Builder。
接口定义
public PushInitConfig.Builder application(Application application);
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
application |
Application |
是 |
配置当前应用的 Application 实例,不能为空。 |
返回值
PushInitConfig.Builder:当前 Builder 实例。
代码示例
PushInitConfig.Builder builder = new PushInitConfig.Builder();
builder.application(application);val builder = PushInitConfig.Builder()
builder.application(application)配置 AppKey(appKey)
EMAS 应用的 AppKey。已在 Manifest 中配置时可省略,应与 AppSecret 配套。
所属类:PushInitConfig.Builder。
接口定义
public PushInitConfig.Builder appKey(String appKey);
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
appKey |
String |
否 |
EMAS 应用的 AppKey。已在 Manifest 中配置时可省略,应与 AppSecret 配套。 |
返回值
PushInitConfig.Builder:当前 Builder 实例。
代码示例
PushInitConfig.Builder builder = new PushInitConfig.Builder().application(application);
builder.appKey("YOUR_APP_KEY");val builder = PushInitConfig.Builder().application(application)
builder.appKey("YOUR_APP_KEY")配置 AppSecret(appSecret)
EMAS 应用的 AppSecret。已在 Manifest 中配置时可省略,应与 AppKey 配套。
所属类:PushInitConfig.Builder。
接口定义
public PushInitConfig.Builder appSecret(String appSecret);
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
appSecret |
String |
否 |
EMAS 应用的 AppSecret。已在 Manifest 中配置时可省略,应与 AppKey 配套。 |
返回值
PushInitConfig.Builder:当前 Builder 实例。
代码示例
PushInitConfig.Builder builder = new PushInitConfig.Builder().application(application);
builder.appSecret("YOUR_APP_SECRET");val builder = PushInitConfig.Builder().application(application)
builder.appSecret("YOUR_APP_SECRET")生成配置对象(build)
根据已设置的参数创建 PushInitConfig。
所属类:PushInitConfig.Builder。
接口定义
public PushInitConfig build();
参数说明
无。
返回值
PushInitConfig:初始化配置对象,传给 PushServiceFactory.init 使用。
代码示例
// 本例已在 Manifest 中配置 AppKey 和 AppSecret。
PushInitConfig config = new PushInitConfig.Builder()
.application(application)
.build();// 本例已在 Manifest 中配置 AppKey 和 AppSecret。
val config = PushInitConfig.Builder()
.application(application)
.build()注册推送服务
向移动推送注册当前应用和设备,成功后可获取设备标识并调用业务接口。
所属类:CloudPushService。
接口定义
void register(Context context, CommonCallback callback);
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
context |
Context |
是 |
使用 ApplicationContext,不能为空。 |
|
callback |
CommonCallback |
是 |
提供非空回调,判断本次注册是否成功。 |
返回值和回调
无直接返回值(void)。注册成功时调用 onSuccess(response),失败时调用 onFailed(errorCode, errorMessage)。请通过注册回调确认结果。
代码示例
CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.register(application.getApplicationContext(), new CommonCallback() {
@Override public void onSuccess(String response) {
String deviceId = pushService.getDeviceId();
// 根据业务需要保存注册状态和 deviceId。
}
@Override public void onFailed(String errorCode, String errorMessage) {
// 结合错误码和 SDK 日志排查。
}
});val pushService = PushServiceFactory.getCloudPushService()
pushService.register(application.applicationContext, object : CommonCallback {
override fun onSuccess(response: String?) {
val deviceId = pushService.deviceId
}
override fun onFailed(errorCode: String?, errorMessage: String?) {
// 结合错误码和 SDK 日志排查。
}
})CommonCallback 定义 onSuccess(String response) 和 onFailed(String errorCode, String errorMessage)。在回调中更新界面时,请将界面操作切换到主线程执行。
|
回调方法 |
参数 |
类型 |
说明 |
|
onSuccess |
response |
String |
接口返回的成功响应;具体内容取决于所调用的接口。 |
|
onFailed |
errorCode |
String |
错误码,用于定位失败原因。 |
|
onFailed |
errorMessage |
String |
错误描述。 |
获取设备标识
所属类:CloudPushService。
接口定义
String getDeviceId();
参数说明
无。
返回值
|
返回类型 |
说明 |
|
String |
获取移动推送设备标识,用于服务端按设备推送。建议在 register 成功后读取;尚未完成初始化/注册时可能为空。 |
代码示例
String deviceId = PushServiceFactory.getCloudPushService().getDeviceId();val deviceId = PushServiceFactory.getCloudPushService().deviceId打开推送(turnOnPushChannel)
所属类:CloudPushService。
接口定义
void turnOnPushChannel(CommonCallback callback);
开启当前设备的推送接收开关。Android 系统通知权限和 ACCS 连接状态需分别检查。
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
callback |
CommonCallback |
否 |
操作回调。建议提供,以确认开关是否成功。 |
返回值和回调
无直接返回值(void)。onSuccess(response) 表示打开成功;onFailed(errorCode, errorMessage) 返回错误码和描述。
代码示例
PushServiceFactory.getCloudPushService().turnOnPushChannel(new CommonCallback() {
@Override public void onSuccess(String response) {
// 推送接收已开启。
}
@Override public void onFailed(String errorCode, String errorMessage) {
// 根据错误码和描述处理失败。
}
});PushServiceFactory.getCloudPushService().turnOnPushChannel(object : CommonCallback {
override fun onSuccess(response: String?) {
// 推送接收已开启。
}
override fun onFailed(errorCode: String?, errorMessage: String?) {
// 根据错误码和描述处理失败。
}
})关闭推送(turnOffPushChannel)
关闭当前设备的推送接收开关。恢复接收时调用 turnOnPushChannel。
所属类:CloudPushService。
接口定义
void turnOffPushChannel(CommonCallback callback);
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
callback |
CommonCallback |
否 |
操作回调。建议提供,以确认关闭结果。 |
返回值和回调
无直接返回值(void)。onSuccess(response) 表示关闭成功;onFailed(errorCode, errorMessage) 返回错误码和描述。
代码示例
PushServiceFactory.getCloudPushService().turnOffPushChannel(new CommonCallback() {
@Override public void onSuccess(String response) {
// 推送接收已关闭。
}
@Override public void onFailed(String errorCode, String errorMessage) {
// 根据错误码和描述处理失败。
}
});PushServiceFactory.getCloudPushService().turnOffPushChannel(object : CommonCallback {
override fun onSuccess(response: String?) {
// 推送接收已关闭。
}
override fun onFailed(errorCode: String?, errorMessage: String?) {
// 根据错误码和描述处理失败。
}
})查询推送开关状态(checkPushChannelStatus)
查询当前设备的推送接收开关状态。设备连接状态请结合连接日志检查,通知展示权限请通过 Android 系统接口查询。
所属类:CloudPushService。
接口定义
void checkPushChannelStatus(CommonCallback callback);
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
callback |
CommonCallback |
否 |
结果回调。查询时请提供,以读取返回状态。 |
返回值和回调
无直接返回值(void)。onSuccess(response) 的 response 为 on 或 off;查询失败时调用 onFailed(errorCode, errorMessage)。
代码示例
PushServiceFactory.getCloudPushService().checkPushChannelStatus(new CommonCallback() {
@Override public void onSuccess(String response) {
// response 为 "on"(开启)或 "off"(关闭)。
}
@Override public void onFailed(String errorCode, String errorMessage) {
// 根据错误码和描述处理失败。
}
});PushServiceFactory.getCloudPushService().checkPushChannelStatus(object : CommonCallback {
override fun onSuccess(response: String?) {
// response 为 "on"(开启)或 "off"(关闭)。
}
override fun onFailed(errorCode: String?, errorMessage: String?) {
// 根据错误码和描述处理失败。
}
})设置消息接收服务
Android SDK 4.x 中,MessageReceiver 和 AliyunMessageIntentService 的业务回调范围如下:
ACCS 自有通道和 FCM:支持消息接收(onMessage)、通知到达(onNotification)、通知点击(onNotificationOpened)、通知清除(onNotificationRemoved)等完整业务回调。
除 FCM 外的其他 Android 厂商通道:仅支持 onNotificationOpened(通知点击),不触发消息接收、通知到达、通知清除等其他回调。
所属类:CloudPushService。
接口定义
void setPushIntentService(Class intentService);
默认通过 MessageReceiver 接收消息。需要使用 AliyunMessageIntentService 时,在每次应用启动的 Application.onCreate() 中完成 init 后尽早设置自定义服务类,并在 Manifest 声明该服务。设置后,消息和通知回调不再交给 MessageReceiver。传 null 恢复广播方式。
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
intentService |
Class |
否 |
继承 AliyunMessageIntentService 的自定义服务类。传 null 恢复 MessageReceiver 分发方式。 |
返回值
无(void)。
代码示例
PushServiceFactory.getCloudPushService()
.setPushIntentService(MyMessageIntentService.class);PushServiceFactory.getCloudPushService()
.setPushIntentService(MyMessageIntentService::class.java)示例中的 MyMessageIntentService 为应用已创建并在 Manifest 中声明的服务类,实现方式见消息与通知处理接口(4.x)。
设置日志等级(setLogLevel)
设置 SDK 日志的输出等级。所属类:CloudPushService。
接口定义
void setLogLevel(int logLevel);
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
logLevel |
int |
是 |
日志输出等级,使用下表中的 CloudPushService 常量。 |
logLevel 取值
|
配置 |
说明 |
|
LOG_ERROR(0) |
输出 WARN 和 ERROR 日志。4.0.0 中此常量对应 WARN 阈值。 |
|
LOG_INFO(1) |
输出 INFO 及更高等级日志。 |
|
LOG_DEBUG(2) |
开发排查时使用,输出 DEBUG 及更高等级日志。 |
|
LOG_OFF(-1) |
关闭 SDK 统一日志管道的输出。 |
返回值
无(void)。
请在 init 之后、register 和厂商注册之前调用 setLogLevel,统一设置 SDK 日志等级。正式环境建议使用 LOG_ERROR 或 LOG_OFF;如需调整底层连接日志的过滤等级,请在下次启动注册前完成设置。
代码示例
// 在 init 之后、register 和厂商通道注册之前调用。
PushServiceFactory.getCloudPushService().setLogLevel(CloudPushService.LOG_DEBUG);// 在 init 之后、register 和厂商通道注册之前调用。
PushServiceFactory.getCloudPushService().setLogLevel(CloudPushService.LOG_DEBUG)4.0.0 的主要 SDK 日志使用 Logcat TAG EMAS_PUSH,模块名位于正文中。Android Studio Logcat 可用 tag:EMAS_PUSH,再结合正文模块或错误码筛选。
adb logcat -s EMAS_PUSH
LOG_OFF 仅关闭 SDK 统一日志管道的输出。应用自行调用 Android Log 输出的日志、厂商原生 SDK 日志和系统日志,由各自的日志配置控制。收集和共享日志前,请对设备标识等业务信息脱敏。
设置接入检查(setDebug)
在调试接入时开启组件和部分参数检查。此开关不改变日志输出等级;需要查看 DEBUG 日志时,另行调用 setLogLevel。
所属类:CloudPushService。
接口定义
void setDebug(boolean isDebug);
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
isDebug |
boolean |
是 |
true:开启接入组件和部分参数检查;false:关闭接入检查。不改变日志输出等级。 |
返回值
无(void)。
代码示例
// 在 init 之后、register 之前调用。
PushServiceFactory.getCloudPushService().setDebug(true);// 在 init 之后、register 之前调用。
PushServiceFactory.getCloudPushService().setDebug(true)接收 SDK 日志
接口定义
static void addListener(LoggerListener listener);
AmsLogger 和 LoggerListener 位于 com.alibaba.sdk.android.ams.common.logger。监听器仅接收 SDK 统一日志管道中通过等级过滤的日志;主要日志的 tag 为 EMAS_PUSH,msg 中包含模块前缀。
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
listener |
LoggerListener |
是 |
日志监听器,不能为空。实现 d、i、w、e 四个回调,分别接收 DEBUG、INFO、WARN、ERROR 日志。 |
返回值和回调
addListener 无返回值(void)。LoggerListener 的四个回调均无返回值,参数含义相同,如下表所示。
|
回调参数 |
类型 |
说明 |
|
tag |
String |
日志 TAG,主要 SDK 日志为 EMAS_PUSH。 |
|
msg |
String |
日志正文,包含模块前缀。 |
|
tr |
Throwable |
异常对象。4.0.0 的日志桥接回调传 null。 |
|
flag |
int |
兼容字段,4.0.0 的日志桥接回调传 0。 |
代码示例
AmsLogger.addListener(new LoggerListener() {
@Override public void d(String tag, String msg, Throwable tr, int flag) {}
@Override public void i(String tag, String msg, Throwable tr, int flag) {}
@Override public void w(String tag, String msg, Throwable tr, int flag) {
// 由应用决定是否脱敏、采样及保存,避免在这里递归调用 AmsLogger。
}
@Override public void e(String tag, String msg, Throwable tr, int flag) {}
});AmsLogger.addListener(object : LoggerListener {
override fun d(tag: String?, msg: String?, tr: Throwable?, flag: Int) {}
override fun i(tag: String?, msg: String?, tr: Throwable?, flag: Int) {}
override fun w(tag: String?, msg: String?, tr: Throwable?, flag: Int) {}
override fun e(tag: String?, msg: String?, tr: Throwable?, flag: Int) {}
})持久化或上传日志时,请按需采样,并设置单次日志量、文件大小和保存周期。正式环境建议仅收集排查所需的日志等级。
通知权限辅助接口
请求 Android 13 及以上的通知权限。所属类:CloudPushService。IPushPermissionCallback 位于 com.alibaba.sdk.android.push。
接口定义
void requestNotificationPermission(Activity activity, int requestCode, IPushPermissionCallback callback);
参数说明
|
参数 |
类型 |
是否必填 |
说明 |
|
activity |
Activity |
是 |
当前可交互的 Activity。 |
|
requestCode |
int |
是 |
Android 运行时权限请求码。 |
|
callback |
IPushPermissionCallback |
否 |
权限状态提示回调。可传 null;最终授权结果仍需在 Activity 中处理。 |
返回值和回调
无直接返回值(void)。onPushPermissionForbidden() 和 onPushPermissionGranted() 均无参数、无返回值。
此接口用于 Android 13 及以上的 POST_NOTIFICATIONS 权限请求。4.0.0 的权限回调覆盖范围有限,应用应在 Activity 的权限结果处理处检查系统授权状态,并在已授权或低版本场景中直接查询当前权限状态。
代码示例
PushServiceFactory.getCloudPushService().requestNotificationPermission(
activity, 1001, new IPushPermissionCallback() {
@Override public void onPushPermissionForbidden() {
// 向用户说明通知权限用途,按应用交互流程引导处理。
}
@Override public void onPushPermissionGranted() {}
});
// 在 Activity 的 onRequestPermissionsResult 中处理 requestCode=1001,
// 并通过 Android 权限 API 检查 POST_NOTIFICATIONS 的最终状态。PushServiceFactory.getCloudPushService().requestNotificationPermission(
activity, 1001, object : IPushPermissionCallback {
override fun onPushPermissionForbidden() {}
override fun onPushPermissionGranted() {}
}
)
// 在 Activity 权限结果处理中重新检查最终授权状态。与 3.x 的区别
|
接口或配置 |
4.0.0 状态 |
|
disableChannelProcess、disableChannelProcessHeartbeat、loopStartChannel、loopInterval |
已移除。 |
|
PushControlService 和 getPushControlService |
已移除,不再提供手动重连、重置或连接状态监听接口。 |
相关文档
接入流程请参见Android SDK接入(4.x)。
使用 3.x 的应用请参见基础配置接口(3.x)。