Android SDK 4.x升级指南-阿里云帮助中心

本文介绍移动推送 Android SDK 从 3.x 版本升级到 4.x 及以上版本时，应用侧需要修改的内容。

前言

移动推送 Android SDK 4.x 版本升级了底层长连接能力，部分客户端接口和通知回调行为发生变化。如果您的应用当前使用 3.x 版本 SDK，请参考本文完成升级适配。

升级变更

升级到 4.X 版本后，您需要重点关注以下变更：

阿里云自有通道通知点击和通知到达相关回调有调整。
厂商通道通知点击回调不再使用辅助弹窗的onSysNoticeOpened，迁移到 MessageReceiver或AliyunMessageIntentService的onNotificationOpened。
标签接口仅支持设备标签，不再支持账号标签与别名标签。
channel 进程相关配置接口已删除。
PushControlService 相关长连接控制接口已删除。

第一步：升级 SDK 依赖

在应用模块的 build.gradle 中，将移动推送主 SDK 升级到 4.0.0 及以上版本。

dependencies {
    implementation 'com.aliyun.ams:alicloud-android-push:4.0.0'
}

如果您的应用集成了厂商通道，请同步升级厂商通道依赖。

dependencies {
    implementation 'com.aliyun.ams:alicloud-android-third-push:4.0.0'

    // 按需接入对应厂商通道。
    implementation 'com.aliyun.ams:alicloud-android-third-push-xiaomi:4.0.0'
    implementation 'com.aliyun.ams:alicloud-android-third-push-huawei:4.0.0'
    implementation 'com.aliyun.ams:alicloud-android-third-push-honor:4.0.0'
    implementation 'com.aliyun.ams:alicloud-android-third-push-oppo:4.0.0'
    implementation 'com.aliyun.ams:alicloud-android-third-push-vivo:4.0.0'
    implementation 'com.aliyun.ams:alicloud-android-third-push-meizu:4.0.0'
    implementation 'com.aliyun.ams:alicloud-android-third-push-fcm:4.0.0'
}

说明

请使用固定版本号接入，不建议使用 4.+ 等动态版本。

第二步：调整消息和通知回调

新版 SDK 调整了部分通知回调接口。请先根据下表确认您的旧版代码是否使用了相关回调，再按新版接口修改。

旧版回调	新版处理方式
`onNotificationOpened(Context, String, String, String)`	改为 `onNotificationOpened(Context, String, String, Map<String, String>)`。
`onNotificationClickedWithNoAction(...)`	删除。无跳转通知点击统一回调到 `onNotificationOpened`。
`onNotificationReceivedInApp(...)`	删除。通知到达统一回调到 `onNotification`。

如果旧版代码中使用 extraMap 字符串，请改为直接使用 Map<String, String>。

Java

@Override
public void onNotificationOpened(Context context, String title, String summary, Map<String, String> extraMap) {
    String value = extraMap == null ? null : extraMap.get("key");
}

Kotlin

override fun onNotificationOpened(
    context: Context,
    title: String,
    summary: String,
    extraMap: Map<String, String>
) {
    val value = extraMap["key"]
}

方式一：使用 `MessageReceiver` 接收消息和通知

新版 SDK 仍然支持通过 MessageReceiver 接收消息和通知。示例如下。

Java

public class MyMessageReceiver extends MessageReceiver {
    // 阿里云自有通道消息到达回调
    @Override
    public void onMessage(Context context, CPushMessage message) {
    }

    // 阿里云自有通道通知到达回调
    @Override
    public void onNotification(Context context, String title, String summary, Map<String, String> extraMap) {
    }

    // 阿里云自有通道和厂商通道通知点击回调
    @Override
    public void onNotificationOpened(Context context, String title, String summary, Map<String, String> extraMap) {
    }

    // 阿里云自有通道通知清除回调
    @Override
    public void onNotificationRemoved(Context context, String messageId) {
    }
}

Kotlin

class MyMessageReceiver : MessageReceiver() {
    // 阿里云自有通道消息到达回调
    override fun onMessage(context: Context, message: CPushMessage) {
    }
    
    // 阿里云自有通道通知到达回调
    override fun onNotification(
        context: Context,
        title: String,
        summary: String,
        extraMap: Map<String, String>
    ) {
    }

    // 阿里云自有通道和厂商通道通知点击回调
    override fun onNotificationOpened(
        context: Context,
        title: String,
        summary: String,
        extraMap: Map<String, String>
    ) {
    }

    // 阿里云自有通道通知清除回调
    override fun onNotificationRemoved(context: Context, messageId: String) {
    }
}

在 AndroidManifest.xml 中注册：

<receiver
    android:name="您的MessageReceiver全限定类名"
    android:exported="false">
    <intent-filter>
        <action android:name="com.alibaba.push2.action.NOTIFICATION_OPENED" />
    </intent-filter>
    <intent-filter>
        <action android:name="com.alibaba.push2.action.NOTIFICATION_REMOVED" />
    </intent-filter>
    <intent-filter>
        <action android:name="com.alibaba.sdk.android.push.RECEIVE" />
    </intent-filter>
</receiver>

方式二：使用 `AliyunMessageIntentService` 接收消息和通知

Java

public class MyMessageIntentService extends AliyunMessageIntentService {
    // 阿里云自有通道消息到达回调
    @Override
    public void onMessage(Context context, CPushMessage message) {
    }

    // 阿里云自有通道通知到达回调
    @Override
    public void onNotification(Context context, String title, String summary, Map<String, String> extraMap) {
    }

    // 阿里云自有通道和厂商通道通知点击回调
    @Override
    public void onNotificationOpened(Context context, String title, String summary, Map<String, String> extraMap) {
    }

    // 阿里云自有通道通知清除回调
    @Override
    public void onNotificationRemoved(Context context, String messageId) {
    }
}

Kotlin

class MyMessageIntentService : AliyunMessageIntentService() {
    // 阿里云自有通道消息到达回调
    override fun onMessage(context: Context, message: CPushMessage) {
    }
    
    // 阿里云自有通道通知到达回调
    override fun onNotification(
        context: Context,
        title: String,
        summary: String,
        extraMap: Map<String, String>
    ) {
    }

    // 阿里云自有通道和厂商通道通知点击回调
    override fun onNotificationOpened(
        context: Context,
        title: String,
        summary: String,
        extraMap: Map<String, String>
    ) {
    }

    // 阿里云自有通道通知清除回调
    override fun onNotificationRemoved(context: Context, messageId: String) {
    }
}

在 AndroidManifest.xml 中注册：

<service
    android:name="您的MessageIntentService全限定类名"
    android:exported="false">
    <intent-filter>
        <action android:name="com.alibaba.push2.action.NOTIFICATION_OPENED" />
    </intent-filter>
    <intent-filter>
        <action android:name="com.alibaba.push2.action.NOTIFICATION_REMOVED" />
    </intent-filter>
    <intent-filter>
        <action android:name="com.alibaba.sdk.android.push.RECEIVE" />
    </intent-filter>
</service>

并在初始化后设置：

Java

CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.setPushIntentService(MyMessageIntentService.class);

Kotlin

val pushService = PushServiceFactory.getCloudPushService()
pushService.setPushIntentService(MyMessageIntentService::class.java)

说明

如果设置了 setPushIntentService，消息和通知回调将通过 AliyunMessageIntentService 处理，不再通过 MessageReceiver 处理。
如果没有设置 setPushIntentService，默认通过 MessageReceiver 处理。

第三步：调整厂商通道点击回调

新版 SDK 将厂商通道点击回调合并到自有通道点击回调 onNotificationOpened 中。辅助弹窗 Activity 继续作为厂商通道通知点击的中转入口使用，但不再通过 onSysNoticeOpened、onNotPushData、onParseFailed 回调处理业务逻辑。

旧版处理方式	新版处理方式
继承 `AndroidPopupActivity`，在 `onSysNoticeOpened` 中处理厂商通道通知点击。	继续继承 `AndroidPopupActivity` 作为中转 Activity，但点击回调迁移到 `MessageReceiver.onNotificationOpened` 或 `AliyunMessageIntentService.onNotificationOpened`。
实现 `PopupNotifyClickListener`，在 `onSysNoticeOpened` 中处理厂商通道通知点击。	继续在已有 Activity 中使用 `PopupNotifyClick` 处理厂商点击 Intent，但不再实现 `PopupNotifyClickListener` 相关回调，点击回调迁移到 `onNotificationOpened`。

升级后，请将厂商通道通知点击业务逻辑迁移到 MessageReceiver 或 AliyunMessageIntentService 的 onNotificationOpened。

方式一：自定义Activity继承自`AndroidPopupActivity`

Java

public class MyPopupActivity extends AndroidPopupActivity {
}

Kotlin

class MyPopupActivity : AndroidPopupActivity()

方式二：已有Activity实现辅助弹窗

Java

public class MyPopupActivity extends Activity {
    private final PopupNotifyClick popupNotifyClick = new PopupNotifyClick();

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        popupNotifyClick.onCreate(this, getIntent());
    }

    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        popupNotifyClick.onNewIntent(intent);
    }
}

Kotlin

class MyPopupActivity : Activity() {
    private val popupNotifyClick = PopupNotifyClick()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        popupNotifyClick.onCreate(this, intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        popupNotifyClick.onNewIntent(intent)
    }
}

在AndroidManifest.xml文件中注册您自定义实现的辅助弹窗Activity，在application节点下添加。

<activity
    android:name="辅助弹窗Activity的全限定类名"
    android:exported="true">
    
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data
            android:host="${applicationId}"
            android:path="/thirdpush"
            android:scheme="agoo" />
    </intent-filter>
    
</activity>

新版点击业务处理，以MessageReceiver为例：

Java

public class MyMessageReceiver extends MessageReceiver {
    // 阿里云自有通道和厂商通道通知点击回调
    @Override
    public void onNotificationOpened(Context context, String title, String summary, Map<String, String> extraMap) {
        // 统一处理自有通道和厂商通道通知点击。
    }
}

Kotlin

class MyMessageReceiver : MessageReceiver() {
    // 阿里云自有通道和厂商通道通知点击回调
    override fun onNotificationOpened(
        context: Context,
        title: String,
        summary: String,
        extraMap: Map<String, String>
    ) {
        // 统一处理自有通道和厂商通道通知点击。
    }
}

说明

新版仍需要在服务端配置辅助弹窗 Activity，用于厂商通道通知点击后的中转。
点击数据解析成功后，SDK 会将通知点击事件发送给 MessageReceiver 或 AliyunMessageIntentService中的onNotificationOpened回调。
应用侧不再需要实现 onSysNoticeOpened、onNotPushData、onParseFailed 处理厂商通道点击业务。

第四步：调整标签接口

新版 SDK 仅支持设备标签，不再支持账号标签、别名标签，接口入参只保留 tags 和 callback。

旧版接口	新版接口
`bindTag(int target, String[] tags, String alias, CommonCallback callback)`	`bindTag(String[] tags, CommonCallback callback)`
`unbindTag(int target, String[] tags, String alias, CommonCallback callback)`	`unbindTag(String[] tags, CommonCallback callback)`
`listTags(int target, CommonCallback callback)`	`listTags(CommonCallback callback)`

Java

// 新版：绑定设备标签。
CloudPushService pushService = PushServiceFactory.getCloudPushService();
pushService.bindTag(tags, callback);

// 新版：解绑设备标签。
pushService.unbindTag(tags, callback);

// 新版：查询设备标签。
pushService.listTags(callback);

Kotlin

// 新版：绑定设备标签。
val pushService = PushServiceFactory.getCloudPushService()
pushService.bindTag(tags, callback)

// 新版：解绑设备标签。
pushService.unbindTag(tags, callback)

// 新版：查询设备标签。
pushService.listTags(callback)

第五步：删除 channel 进程相关配置

旧版 SDK 支持通过 PushInitConfig.Builder 配置 channel 进程和 channel 进程心跳。新版 SDK 底层长连接已升级，不再提供以下接口：

旧版接口	新版处理方式
`disableChannelProcess(boolean)`	删除调用。
`disableChannelProcessHeartbeat(boolean)`	删除调用。
`loopStartChannel(boolean)`	删除调用。
`loopInterval(long)`	删除调用。

第六步：删除 PushControlService 相关逻辑

旧版 SDK 提供 PushControlService 用于查询、监听、重连或重置长连接。新版 SDK 不再提供该类及相关接口。

旧版接口	新版处理方式
`PushServiceFactory.getPushControlService()`	删除调用。
`PushControlService.isConnected()`	删除调用。
`PushControlService.setConnectionChangeListener(...)`	删除调用。
`PushControlService.reconnect()`	删除调用。
`PushControlService.reset()`	删除调用。
`PushControlService.disconnect()`	删除调用。

如果旧版代码中存在手动重连、重置连接、监听连接状态等逻辑，请删除相关调用。

按需修改项

厂商 token 查询接口

新版厂商通道增加了本地 token 查询接口。如果您的应用需要读取最近一次存储的厂商 token，可使用以下接口。

Java

String miToken = MiPushRegister.getToken(context);
String huaweiToken = HuaWeiRegister.getToken(context);
String honorToken = HonorRegister.getToken(context);
String oppoToken = OppoRegister.getToken(context);
String vivoToken = VivoRegister.getToken(context);
String meizuToken = MeizuRegister.getToken(context);
String fcmToken = GcmRegister.getToken(context);

Kotlin

val miToken = MiPushRegister.getToken(context)
val huaweiToken = HuaWeiRegister.getToken(context)
val honorToken = HonorRegister.getToken(context)
val oppoToken = OppoRegister.getToken(context)
val vivoToken = VivoRegister.getToken(context)
val meizuToken = MeizuRegister.getToken(context)
val fcmToken = GcmRegister.getToken(context)

说明

getToken 返回的是本地已存储的最近一次厂商 token。
如果厂商注册尚未成功，返回值可能为空。

通知声音设置接口

setNotificationSoundFilePath 在新版 SDK 中已废弃。如果旧版代码中使用了该接口，建议迁移为通过通知渠道（Notification Channel）配置通知声音。

升级验证

升级完成后，建议按以下方式验证：

启动应用，确认 register 回调成功。
调用 getDeviceId，确认可以获取设备标识。
通过控制台或 OpenAPI 下发通知，确认通知可以展示。
点击自有通道通知和厂商通道通知，确认 onNotificationOpened 被回调。
删除通知，确认 onNotificationRemoved 被回调。
下发消息类型，确认 onMessage 被回调。
如使用标签功能，确认设备标签绑定、解绑和查询接口调用成功。

常见问题

厂商通道通知点击为什么没有onSysNoticeOpened回调？

新版 SDK 将厂商通道点击回调统一合并到 onNotificationOpened。请将业务处理逻辑迁移到 MessageReceiver 或 AliyunMessageIntentService 的 onNotificationOpened 中。

升级后是否还需要配置 channel 进程？

不需要。4.x 及以上版本底层长连接已升级，不再使用旧版 channel 进程配置。

升级后是否还能手动控制长连接？

不再提供 PushControlService.reconnect、reset 等接口。新版 SDK 内部维护连接状态，应用侧无需手动控制。

前言

升级变更

第一步：升级 SDK 依赖

第二步：调整消息和通知回调

方式一：使用 MessageReceiver 接收消息和通知

方式二：使用 AliyunMessageIntentService 接收消息和通知

第三步：调整厂商通道点击回调

方式一：自定义Activity继承自AndroidPopupActivity

方式二：已有Activity实现辅助弹窗

第四步：调整标签接口

第五步：删除 channel 进程相关配置

第六步：删除 PushControlService 相关逻辑

按需修改项

厂商 token 查询接口

通知声音设置接口

升级验证

常见问题

厂商通道通知点击为什么没有onSysNoticeOpened回调？

升级后是否还需要配置 channel 进程？

升级后是否还能手动控制长连接？

方式一：使用 `MessageReceiver` 接收消息和通知

方式二：使用 `AliyunMessageIntentService` 接收消息和通知

方式一：自定义Activity继承自`AndroidPopupActivity`