基础配置接口(4.x)

更新时间:
复制 MD 格式

本文介绍 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)。