阿里云移动推送（智能推送）完全对接指南：从控制台配置到服务端API深度集成

1. 移动推送（智能推送）概述

阿里云移动推送（Alibaba Cloud Mobile Push）是一款基于大数据的移动智能推送服务，帮助App开发者快速集成推送功能，实现高效、精准、实时的消息推送。该服务支持Android、iOS、HarmonyOS三大主流平台，提供通知推送与透传消息两种模式，并深度整合了小米、华为、荣耀、vivo、OPPO、魅族、谷歌等主流手机厂商的推送通道，以保障应用在后台或被杀状态下的消息送达率。

移动推送的核心价值在于：一方面通过自建长连接通道保证实时性，另一方面在自建通道不可用时自动降级到厂商通道，实现双通道保障。同时，服务端提供完善的OpenAPI体系，支持设备维度的精准推送、账号维度的用户关联推送、别名维度的业务标识推送，以及标签维度的分群推送。

需要先登录阿里云控制台，点击：阿里云控制台

2. 控制台准备与基础配置

2.1 创建EMAS项目与应用

移动推送服务隶属于阿里云移动研发平台EMAS（Enterprise Mobile Application Studio）。接入的第一步是在EMAS控制台中创建项目和应用。

登录EMAS管理控制台后，点击创建项目，填写项目名称与描述。在项目下创建应用时，需要选择平台类型（Android、iOS或HarmonyOS），并填写应用名称和包名（Bundle ID）。创建完成后，系统会为每个应用分配唯一的AppKey，这是后续所有API调用和SDK初始化中必需的核心标识符。

2.2 Android厂商通道配置

针对Android平台，若要使用厂商通道提升送达率，必须在控制台配置各厂商的推送密钥。不同厂商的配置流程略有差异：

• 小米：登录小米开放平台，在推送运营平台创建应用，获取AppID、AppKey、AppSecret，然后在EMAS控制台填入小米推送密钥。
• 华为：登录华为开发者联盟，注册应用并获取APP ID和SecretKey，同时在华为开发者联盟配置应用的SHA256证书指纹。消息回执地址需配置为https://amspush-ack.aliyuncs.com/hw/。
• 荣耀：登录荣耀开发者平台，在应用服务→推送服务中获取App ID、Client ID、Client Secret等信息，配置签名证书指纹。回执地址为https://amspush-ack.aliyuncs.com/ho/。
• vivo：登录vivo开放平台，在应用信息中获取AppID、AppKey、AppSecret，开通APP回执地址并配置为https://amspush-ack.aliyuncs.com/vivo/。
• OPPO：登录OPPO开放平台，在推送服务中注册应用，获取AppKey、AppSecret和MasterSecret。
• 魅族：登录魅族开放平台，在消息推送服务中注册应用，获取AppID和AppSecret，配置回执链接为http://amspush-ack.aliyuncs.com/mz/及https://amspush-ack.aliyuncs.com/mz/。

2.3 iOS推送证书配置

iOS应用使用Apple Push Notification Service（APNs）进行推送，需要在移动推送控制台上传推送证书。证书配置支持两种方式：

• P12证书鉴权（Certificate-based）：通过Apple Developer账号生成推送证书（.p12格式），上传至控制台。需区分开发环境（Development）和生产环境（Production）。
• P8证书鉴权（Token-based）：生成APNs Auth Key（.p8文件），上传至控制台。此种方式更为便捷，无需每年更新证书。

无论采用哪种方式，证书上传完成后控制台会进行验证，确认证书有效后方可使用iOS推送功能。

3. 客户端SDK集成

3.1 Android SDK集成

Android端集成移动推送SDK需在项目的build.gradle文件中添加依赖。SDK版本请参考阿里云SDK中心获取最新版本号。

dependencies { implementation 'com.aliyun:alicloud-android-push:3.x.x' // 厂商通道扩展包（按需引入） implementation 'com.aliyun:alicloud-android-third-push:3.x.x' }

初始化代码如下：

// 在Application的onCreate中初始化 CloudPushService pushService = PushServiceFactory.getCloudPushService(); pushService.register(application, new CommonCallback<String>() { @Override public void onSuccess(String deviceId) { // 注册成功，deviceId为设备唯一标识 Log.d("Push", "DeviceId: " + deviceId); } @Override public void onFailed(String errorCode, String errorMessage) { Log.e("Push", "注册失败: " + errorCode + ", " + errorMessage); } });

3.2 iOS SDK集成

iOS端通过CocoaPods集成SDK：

pod 'AliyunPush', '~> 3.x.x'

初始化代码（在AppDelegate中）：

#import <CloudPushSDK/CloudPushSDK.h> - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [CloudPushSDK register:CloudPushSDKAppKey appSecret:CloudPushSDKAppSecret callback:^(CloudPushCallbackResult *res) { if (res.success) { NSLog(@"注册成功，DeviceId: %@", [CloudPushSDK getDeviceId]); } else { NSLog(@"注册失败: %@", res.error); } }]; return YES; }

iOS推送还需在控制台完成证书配置，并在Capabilities中开启Push Notifications功能。

3.3 HarmonyOS SDK集成

阿里云移动推送已全面支持HarmonyOS平台。集成方式与Android类似，需在控制台配置鸿蒙厂商通道的账号密钥文件。SDK依赖和初始化代码请参考官方文档的最新版本。

3.4 uni-app跨平台集成

对于使用uni-app框架的开发者，阿里云提供了专门的uni-app插件，简化跨平台推送集成。开发者无需处理复杂的原生集成问题，通过插件即可在Vue.js代码中调用推送功能。插件分为两个部分：Aliyun-Push为基础推送插件，阿里云移动推送-厂商通道为Android厂商通道扩展包。

4. 服务端API对接

4.1 认证与凭证准备

调用移动推送的OpenAPI需要阿里云账号的AccessKey ID和AccessKey Secret。出于安全考虑，强烈建议使用RAM子账号而非主账号进行API调用。在RAM控制台创建子账号并授予移动推送的管理权限后，获取该子账号的AccessKey。

设置环境变量以便SDK自动读取：

export ALIBABA_CLOUD_ACCESS_KEY_ID="your-access-key-id" export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-access-key-secret"

每个API请求都需要在请求中包含签名信息，服务端通过AccessKey Secret进行对称加密验证请求发送者身份。

4.2 PushV2接口概述

阿里云移动推送推荐使用PushV2接口，相较于旧版Push接口，新版采用结构化请求体设计，将众多参数分类组织，便于开发者按需灵活传参。PushV2还新增了持续推送（Continuous Push）功能，支持创建一次消息模板后向多批设备推送。

PushV2请求的整体结构如下：

{ "AppKey": long, "PushTask": { "Target": { "Type": string, "Value": string, "Platform": string }, "Message": { "Title": string, "Body": string, ... }, "PushTime": string, "ExpireTime": string, ... } }

4.3 Java SDK代码示例

在Maven项目中添加PushV2 SDK依赖：

<dependency> <groupId>com.aliyun</groupId> <artifactId>push20160801</artifactId> <version>${push-sdk-version}</version> </dependency>

完整推送示例（Kotlin）：

import com.aliyun.push20160801.Client import com.aliyun.push20160801.models.PushV2Request import com.aliyun.teaopenapi.models.Config import com.alibaba.fastjson.JSON object QuickStart { @JvmStatic fun main(args: Array<String>) { val client = createClient() val payload = """ { "AppKey": 233586006, "PushTask": { "Target": { "Type": "DEVICE", "Value": "your-device-id", "Platform": "IOS" }, "Message": { "Title": "测试消息", "Body": "这是一条透传消息" } } } """.trimIndent() val parameters = JSON.parseObject(payload) as Map<String, Any> val request = PushV2Request.build(parameters) val response = client.pushV2(request) println("推送成功! MessageId: ${response.body.messageId}") } private fun createClient(): Client { val config = Config().apply { accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID") accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET") endpoint = "cloudpush.aliyuncs.com" regionId = "cn-hangzhou" } return Client(config) } }

除了使用JSON字符串构建请求外，SDK也支持通过结构体以链式或逐层赋值的方式构建请求，具备更好的类型安全性。

4.4 Python SDK代码示例

Python开发者可通过pip安装SDK：

pip install aliyun-python-sdk-core pip install aliyun-python-sdk-push

Python推送示例：

from aliyunsdkcore.client import AcsClient from aliyunsdkpush.request.v20160801.PushV2Request import PushV2Request import json client = AcsClient( os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID'), os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET'), 'cn-hangzhou' ) request = PushV2Request() payload = { "AppKey": 233586006, "PushTask": { "Target": { "Type": "DEVICE", "Value": "your-device-id", "Platform": "ANDROID" }, "Message": { "Title": "测试通知", "Body": "这是一条通知消息" } } } request.set_content(json.dumps(payload).encode('utf-8')) request.set_content_type('application/json') response = client.do_action_with_exception(request) print(response)

移动推送服务端SDK还支持Node.js、PHP、Go、C#等多种语言，开发者可根据技术栈选择合适的SDK。

5. 推送目标类型详解

5.1 按设备推送（DEVICE）

最基础的推送方式，直接指定设备的唯一标识DeviceId进行推送。DeviceId是SDK初始化成功后返回的32位字符串，由数字和小写字母组成。适用于单设备调试或精准定向场景。

5.2 按账号推送（ACCOUNT）

将设备与业务系统的用户账号绑定后，可按账号推送。推荐在用户登录时调用绑定接口，用户登出时解绑。一个账号可绑定多台设备，推送时所有关联设备均可收到消息。

客户端绑定账号示例：

pushService.bindAccount("user_12345", new CommonCallback() { @Override public void onSuccess(String s) { // 绑定成功 } @Override public void onFailed(String s, String s1) { // 绑定失败 } });

5.3 按别名推送（ALIAS）

别名是业务层自定义的标识符，一个设备可绑定多个别名，一个别名最多可绑定128个设备。别名最长128个字节（中文算三个字符）。每次绑定操作最多可绑定10个别名。

服务端绑定别名API（Java）：

BindAliasRequest request = new BindAliasRequest(); request.setAppKey(appKey); request.setDeviceId(deviceId); request.setAliasName("vip_user_001"); client.bindAlias(request);

别名推送适用于同一用户在不同设备间切换的场景，如用户登录后绑定别名，退出后解绑。

5.4 按标签推送（TAG）

标签是对设备、账号或别名进行分类标记的手段。通过标签可以将用户按地域、兴趣、行为等维度分群，实现精细化运营推送。

客户端绑定标签：

pushService.bindTag(CloudPushService.TARGET_DEVICE, new String[]{"sports", "news"}, new CommonCallback() { @Override public void onSuccess(String s) { } @Override public void onFailed(String s, String s1) { } });

5.5 全量推送（ALL）

向所有设备推送消息，也称全推。全推有频率限制：同一AppKey、同一操作系统，两次全推间隔至少1秒，连续10分钟内最多全推10次通知或30次消息。

6. 厂商通道与辅助弹窗

6.1 厂商通道的作用

在国内Android生态中，推送通道依赖于应用进程的存活状态。主流手机厂商在自家ROM中实现了系统级别的推送通道，由系统统一分发消息，可显著提升应用被杀死后的消息到达率。移动推送已接入小米、华为、荣耀、vivo、OPPO、魅族、谷歌等厂商通道。

推送策略上，移动推送优先使用自有通道下发消息，仅在自有通道断连时才会选择厂商通道。

6.2 辅助弹窗机制

厂商通道可以在App被终止的情况下将通知推送到手机通知栏。但点击通知后的响应处理需要接入辅助弹窗才能实现。辅助弹窗的本质是：当应用离线时，厂商通道将通知展示在通知栏，用户点击后由系统拉起应用，辅助弹窗组件捕获点击事件并传递推送数据给应用层处理。

接入辅助弹窗的步骤：

• 在客户端集成辅助弹窗SDK（通常包含在厂商通道扩展包中）
• 在EMAS控制台配置辅助弹窗参数：跳转Activity、弹窗标题、弹窗正文等
• 注意：辅助弹窗离线通知消息的处理不在MessageReceiver或AliyunMessageIntentService的回调中

7. 高级推送功能

7.1 定时推送

通过设置PushTime参数可实现定时推送，不设置则默认为立即发送。定时时间不能超过当前时间7天。

7.2 离线消息缓存

设备离线时，推送消息可在服务端缓存，待设备上线后再进行推送。离线保存时间最多可设置72小时。

7.3 通知样式定制

控制台推送通知时支持多种展示样式：

• 标准模式：默认通知样式
• 长文本模式：展示更多内容
• 大图模式：在通知中展示大图
• 列表模式：展示多个列表项

7.4 静默推送

静默推送（Silent Push）可在不打扰用户的情况下将数据推送到客户端，适用于后台数据同步等场景。

8. 数据统计与监控

8.1 控制台数据查看

在移动推送控制台的数据统计页面，可以按天查看推送请求的受理数、送出数、应用到达数、点击量、清除量及推送通道使用数据。

8.2 OpenAPI统计查询

通过OpenAPI可获取更详细的统计数据：

• QueryPushStatByApp：按天或小时维度查询App的推送统计信息，数据为T-1周期
• QueryPushStatByMsg：根据消息ID查询任务维度的统计信息，数据为T-1天
• QueryPushRecords：查看推送历史记录

注意：仅支持查看最近30天内的推送统计数据。

9. 排查工具与问题定位

当推送出现异常时，可使用EMAS控制台的排查工具进行自助诊断。在排查消息页面输入消息ID（必选）和设备ID（可选），即可查看消息的完整生命周期详情。

常见排查要点：

• 检查SDK初始化是否成功，DeviceId是否正常获取
• 检查控制台证书/密钥配置是否正确
• 检查设备是否在线（自有通道）或厂商通道是否就绪
• 对于Android，确认Android 8.0以上设备已设置ChannelId
• 检查推送目标（设备ID/账号/别名/标签）是否已正确绑定

10. 最佳实践与注意事项

10.1 安全建议

• 使用RAM子账号AccessKey调用API，避免主账号密钥泄露
• AccessKey Secret切勿硬编码在客户端代码中
• 服务端API调用建议在服务端进行，不暴露密钥给客户端

10.2 到达率优化

• 务必接入厂商通道并完成控制台配置
• 接入辅助弹窗以处理应用被杀后的通知点击
• 合理设置离线消息缓存时间，避免消息过期丢失

10.3 推送策略

• 避免过于频繁的全量推送，遵守频率限制
• 利用标签和别名实现精细化推送，减少对用户的无效打扰
• 定时推送避开用户休息时段，提升用户体验

10.4 成本控制

• 移动推送按量计费，主要费用来自推送请求次数和到达设备数
• 合理规划推送频率和受众范围，避免无效推送造成费用浪费
• 利用数据统计监控推送量，及时调整推送策略

常见问题问答

问：Android端推送消息在应用被杀后收不到怎么办？
答：需要在EMAS控制台配置对应手机厂商的推送密钥（小米、华为、荣耀、vivo、OPPO等），并在客户端集成厂商通道扩展包和辅助弹窗。这样当应用被杀死后，消息可通过厂商系统通道送达通知栏。

问：PushV2接口和旧版Push接口有什么区别？
答：PushV2采用结构化请求体设计，参数分类更清晰，开发者可按需灵活传参。此外，PushV2新增了持续推送功能，支持创建一次消息模板后向多批设备推送。建议新项目直接使用PushV2接口。

问：一个设备可以绑定多个别名吗？最多能绑定多少个？
答：可以。一个设备最多绑定128个别名，每次绑定操作最多可绑定10个别名。一个别名最多允许绑定128个设备。

问：推送消息可以定时发送吗？最长能定时多久？
答：可以。通过设置PushTime参数实现定时推送，不设置则默认为立即发送。定时时间不能超过当前时间之后的7天。

问：iOS推送证书有哪几种配置方式？
答：iOS推送证书支持两种配置方式：P12证书鉴权（Certificate-based）和P8证书鉴权（Token-based）。P8方式更为便捷，无需每年更新证书，推荐使用。

问：如何排查推送消息未到达的问题？
答：首先在EMAS控制台的排查工具中输入消息ID和设备ID查看消息状态。然后检查：SDK初始化是否成功、控制台证书/密钥配置是否正确、设备是否在线、Android 8.0以上是否设置了ChannelId、推送目标是否已正确绑定。