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、推送目标是否已正确绑定。
