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

1. 移动推送服务概述

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

移动推送的核心价值体现在双通道保障机制上：一方面通过自建长连接通道保证消息的实时性，另一方面在自建通道不可用时自动降级到厂商通道，实现双通道保障。同时，服务端提供完善的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文件），上传至控制台。此种方式更为便捷，无需每年更新证书。

3. 客户端SDK集成

3.1 Android SDK集成

移动推送Android SDK支持原生AAR和组件化两种接入方式。在项目的build.gradle文件中添加SDK依赖：

dependencies {
    implementation 'com.aliyun.ams:alicloud-android-push:3.9.5'
    // 厂商通道扩展包（可选，用于增强送达率）
    implementation 'com.aliyun.ams:alicloud-android-third-push:3.9.2'
}

在AndroidManifest.xml中配置必要的权限和服务声明。初始化推送服务的示例代码如下：

// 在Application的onCreate中初始化
CloudPushService pushService = CloudPushService.getInstance();
pushService.register(applicationContext, new CommonCallback() {
    @Override
    public void onSuccess(String response) {
        // 注册成功，获取deviceId
        String deviceId = pushService.getDeviceId();
        Log.d("Push", "DeviceId: " + deviceId);
    }
    @Override
    public void onFailed(String errorCode, String errorMessage) {
        Log.e("Push", "注册失败: " + errorCode + " - " + errorMessage);
    }
});

3.2 iOS SDK集成

iOS SDK支持CocoaPods方式集成。在Podfile中添加：

pod 'AlicloudPush', '~> 2.0.4'

在AppDelegate中初始化推送服务：

#import <CloudPushSDK/CloudPushSDK.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // APNs注册
    [CloudPushSDK registerApns:application];
    // 初始化推送SDK
    [CloudPushSDK asyncInit:@"your-appkey" appSecret:@"your-appsecret" callback:^(CloudPushCallbackResult *res) {
        if (res.success) {
            NSString *deviceId = [CloudPushSDK getDeviceId];
            NSLog(@"DeviceId: %@", deviceId);
        } else {
            NSLog(@"初始化失败: %@", res.error);
        }
    }];
    return YES;
}

3.3 HarmonyOS SDK集成

移动推送已全面支持HarmonyOS NEXT版本。HarmonyOS SDK是专为HarmonyOS应用程序量身定制的解决方案。集成方式类似Android，需在entry模块的oh-package.json5中添加依赖，并在Ability的onCreate中进行初始化。

4. 服务端API对接

4.1 PushV2接口概述

阿里云移动推送推荐使用PushV2接口，相较于旧版Push接口（V1），新版采用结构化请求体设计，将众多参数分类组织，便于开发者按需灵活传参。PushV2的核心优势包括：

结构化的参数设计：采用层次化的参数结构，将推送配置分为Target（目标）、Message（透传消息）、Notification（通知消息）、Options（选项）等清晰的模块。
精简高效的参数体系：移除所有废弃参数，只保留有效和必要的配置项，减少参数冗余，降低学习和使用成本。
增强的推送能力：新增持续推送（Continuous Push）功能，支持创建一次消息模板后向多批设备推送，大幅提升大规模推送的效率。

4.2 前置准备

在调用API之前，需要完成以下准备工作：

登录阿里云移动推送控制台，创建应用并获取AppKey。
获取阿里云AccessKey ID和AccessKey Secret。
设置环境变量：

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

4.3 Java SDK示例

在Maven项目的pom.xml中添加依赖：

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

完整的推送示例代码：

import com.aliyun.push20160801.Client;
import com.aliyun.push20160801.models.PushV2Request;
import com.aliyun.teaopenapi.models.Config;
import com.alibaba.fastjson.JSON;
public class PushDemo {
    public static void main(String[] args) throws Exception {
        // 1. 创建客户端
        Config config = new Config()
            .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
            .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
            .setEndpoint("cloudpush.aliyuncs.com")
            .setRegionId("cn-hangzhou");
        Client client = new Client(config);
        
        // 2. 构建推送请求（方式一：使用JSON快速构建）
        String payload = "{"
            + "\"AppKey\": 233586006,"
            + "\"PushTask\": {"
            + "  \"Target\": {"
            + "    \"Type\": \"DEVICE\","
            + "    \"Value\": \"your-device-id\","
            + "    \"Platform\": \"ANDROID\""
            + "  },"
            + "  \"Message\": {"
            + "    \"Title\": \"测试消息\","
            + "    \"Body\": \"这是一条透传消息\""
            + "  },"
            + "  \"Notification\": {"
            + "    \"Title\": \"通知标题\","
            + "    \"Body\": \"通知内容\""
            + "  }"
            + "}"
        + "}";
        
        java.util.Map<String, Object> parameters = JSON.parseObject(payload);
        PushV2Request request = PushV2Request.build(parameters);
        
        // 3. 发送推送
        PushV2Response response = client.pushV2(request);
        System.out.println("推送成功! MessageId: " + response.getBody().getMessageId());
    }
}

方式二：使用结构体构建请求。SDK提供的结构体支持链式或逐层赋值的方式，具备良好的可读性与类型安全性：

PushV2Request request = new PushV2Request()
    .setAppKey(233586006L)
    .setPushTask(new PushV2Request.PushTask()
        .setTarget(new PushV2Request.PushTaskTarget()
            .setType("DEVICE")
            .setValue("your-device-id")
            .setPlatform("ANDROID"))
        .setMessage(new PushV2Request.PushTaskMessage()
            .setTitle("测试消息")
            .setBody("这是一条透传消息"))
        .setNotification(new PushV2Request.PushTaskNotification()
            .setTitle("通知标题")
            .setBody("通知内容")));

4.4 Python SDK示例

安装Python SDK：

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

Python调用示例：

from aliyunsdkcore.client import AcsClient
from aliyunsdkpush.request.v20160801 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.PushV2Request()
request.set_AppKey(233586006)
push_task = {
    "Target": {
        "Type": "DEVICE",
        "Value": "your-device-id",
        "Platform": "ANDROID"
    },
    "Message": {
        "Title": "测试消息",
        "Body": "这是一条透传消息"
    },
    "Notification": {
        "Title": "通知标题",
        "Body": "通知内容"
    }
}
request.set_PushTask(json.dumps(push_task))
response = client.do_action_with_exception(request)
print(response)

4.5 PushV2请求参数详解

PushV2请求的核心结构如下：

AppKey：应用的唯一标识，在EMAS控制台创建应用时获取。
PushTask.Target：推送目标配置。

Type：目标类型，可选DEVICE（设备）、ACCOUNT（账号）、ALIAS（别名）、TAG（标签）、ALL（全量）。
Value：目标值，根据Type不同填写对应的设备ID、账号、别名或标签。
Platform：平台类型，可选ANDROID、IOS、HMOS（鸿蒙）。

PushTask.Message：透传消息配置。

Title：消息标题。
Body：消息内容。

PushTask.Notification：通知消息配置。

Title：通知标题。
Body：通知内容。
Android：Android平台特有参数，如厂商通道配置。
Ios：iOS平台特有参数，如角标、声音等。
Hmos：鸿蒙平台特有参数。

PushTask.Options：推送选项配置。

PushTime：定时推送时间。
ExpireTime：消息过期时间。
JobKey：任务标识，用于去重。

PushTask.Action：推送方式。

PUSH_IMMEDIATELY（默认）：立即推送。
SCHEDULED_PUSH：定时推送。
CREATE_CONTINUOUS_PUSH：创建持续推送任务。
CONTINUOUS_PUSH：执行持续推送批次。

5. 高级功能与最佳实践

5.1 设备绑定与别名管理

服务端接收到客户端上报的用户ID和设备ID后，可以调用移动推送API将用户与设备进行绑定。绑定后即可通过账号或别名进行精准推送。别名一次最多只能绑定10个，多个别名用逗号分隔，别名最长128个字节。

绑定别名的Java示例：

// 调用BindAlias API
BindAliasRequest request = new BindAliasRequest()
    .setAppKey(appKey)
    .setDeviceId(deviceId)
    .setAliasName("user_12345");
BindAliasResponse response = client.bindAlias(request);

5.2 模板推送与批量推送

消息模板由模板主体、占位符以及其他消息属性组成。占位符为模板中的动态化内容，不包含占位符的模板将不具有个性化消息推送的能力。模板功能可以增加消息配置的灵活性，减少重复内容的输入。配置模板时，可以通过 #占位符名称# 的写法来标识模板中的动态化部分，占位符可以出现在模板标题、模板正文和跳转地址中。

在消息推送控制台上创建好目标模板，并确保模板中存在占位符，否则将无法实现消息的个性化推送。批量推送通过替换模板占位符的方式，创建针对某一推送ID的个性化消息。与模板推送的区别在于，每一个推送ID可以收到内容不同的消息。

批量推送的请求参数包括：

taskName：推送任务名称。
deliveryType：目标ID类型，1为Android设备维度，2为iOS设备维度，3为用户维度。
templateName：模板名称，在控制台创建模板。
targetMsgs：目标对象列表，每个对象包含目标ID和对应的占位符替换内容。
expiredSeconds：消息有效期，单位为秒。

5.3 推送策略

消息推送支持即时推送、定时推送、循环推送三种不同推送策略。定时推送是在指定时间推送消息，循环推送是在指定时间范围内重复推送。

当推送目标为移动分析人群或自定义标签人群时，不支持定时和循环推送。定时推送任务分为定时推送和循环推送两种。

5.4 消息撤回

对已推送的消息可以进行撤回。通过极简推送或模板推送方式推送的消息可通过消息ID撤回。通过批量推送和群发推送方式推送的消息可通过任务ID撤回。消息撤回功能对于误推送或内容错误场景尤为实用。

5.5 统计分析

移动推送提供完善的统计分析能力。可以查询消息推送统计数据，包括总推送条数、推送成功数、推送到达数、消息开启数、消息忽略数等。通过控制台创建或通过调用API触发的批量推送任务和群发推送工作清单以及任务详情均可查询。同时支持查询定时推送工作清单、取消定时推送任务。

5.6 生命周期管理

建议对推送任务实施完整的生命周期管理：创建任务时设置合理的过期时间（ExpireTime），避免消息长期堆积；对于已推送的消息，通过消息ID或任务ID进行状态跟踪；对于不再需要的定时任务，及时取消以释放资源。

5.7 灰度发布与A/B测试

在实际生产环境中，建议采用灰度发布策略：先通过设备ID或标签圈定小范围用户进行测试推送，验证消息内容、跳转链接和展示效果无误后，再逐步扩大推送范围。标签推送支持按地域、设备类型、用户属性等维度进行精准分群，为A/B测试提供了良好的基础。

5.8 离线消息与厂商通道最佳实践

对于Android平台，厂商通道是保障应用后台消息送达的关键。建议对所有主流厂商通道进行完整配置。在没有配置厂商通道的情况下，通知只会在应用处于前台或SDK维持长连接时到达。

使用厂商通道推送时，服务端必须参考辅助弹窗文档进行服务端配置。服务端参数不设置，不会给厂商通道进行推送。

厂商通道的参数特殊限制因厂商而异：

华为/荣耀/鸿蒙：需在控制台配置应用证书和消息回执地址。
小米：需配置channelId（渠道ID）。
vivo：需配置消息类型（classification），0为运营类消息，1为系统类消息。
OPPO：需配置消息等级（notifyLevel）。

6. 常见问题与排查

问题1：设备在线时推送消息已到达，但App端始终没有收到

可能的原因包括：SDK集成不完整、初始化失败、广播回调未正确注册。解决方案是根据移动推送接入文档的集成步骤进行仔细检查。

问题2：厂商通道推送失败

检查控制台厂商通道配置是否正确（AppID、AppSecret等）。确认服务端调用时是否设置了厂商通道相关参数。检查厂商平台侧的证书配置和回执地址是否正确。

问题3：定时推送未生效

确认PushTask.Action是否设置为SCHEDULED_PUSH。检查Options.PushTime是否设置了正确的推送时间。注意当推送目标为移动分析人群或自定义标签人群时，不支持定时和循环推送。

问题4：设备ID获取失败

确认客户端SDK是否正确初始化。检查网络连接是否正常。在初始化回调中获取deviceId，确保在注册成功后再进行后续操作。

问题5：批量推送中部分设备未收到消息

检查目标设备列表是否超过限制（用户维度和设备维度的目标最多可以传100个）。确认模板中占位符是否正确配置。使用控制台的排查工具查看具体设备的推送状态。

7. 总结

阿里云移动推送（智能推送）提供了从控制台配置到服务端API的全链路推送解决方案。通过EMAS控制台完成项目创建、厂商通道配置和证书上传后，开发者可以在Android、iOS、HarmonyOS三大平台快速集成客户端SDK。服务端推荐使用PushV2接口，其结构化参数设计和增强的推送能力（持续推送、定时推送等）大幅提升了开发效率和大规模推送的可靠性。结合设备绑定、模板推送、批量推送、消息撤回和统计分析等高级功能，开发者可以构建精准、高效、可运营的推送体系。在实际生产中，建议遵循生命周期管理、灰度发布、厂商通道完整配置等最佳实践，以保障推送的到达率和用户体验。

8. 常见问题问答

问：移动推送支持哪些平台？

答：移动推送支持Android、iOS、HarmonyOS三大主流平台。Android平台还深度整合了华为、小米、荣耀、vivo、OPPO、魅族、谷歌（FCM）等主流厂商通道。

问：PushV2接口相比旧版Push接口有哪些改进？

答：PushV2采用结构化参数设计，将参数分类组织为Target、Message、Notification、Options等模块；移除了所有废弃参数，精简了参数体系；新增了持续推送功能，支持创建一次消息模板后向多批设备推送。

问：如何保障Android应用在后台被杀状态下的消息送达？

答：需要在EMAS控制台配置各厂商通道的推送密钥。当应用自建长连接通道不可用时，系统会自动降级到厂商通道进行推送。没有配置厂商通道的情况下，通知只会在应用处于前台或SDK维持长连接时到达。

问：模板推送和批量推送有什么区别？

答：模板推送是对多个目标推送相同的消息内容，所有目标收到相同的消息。批量推送是通过替换模板占位符的方式，对各个推送ID推送不同的个性化消息，每一个推送ID可以收到内容不同的消息。

问：推送消息后如何撤回？

答：通过极简推送或模板推送方式推送的消息可通过消息ID撤回；通过批量推送和群发推送方式推送的消息可通过任务ID撤回。

问：定时推送和循环推送有什么区别？

答：定时推送是在指定时间推送一次消息；循环推送是在指定时间范围内重复推送，例如指定在6月1日至9月30日期间，每周五早上8:00推送。一个循环推送任务可能产生一个或多个定时推送任务。

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

1. 移动推送服务概述

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

2.1 创建EMAS项目与应用

2.2 Android厂商通道配置

2.3 iOS推送证书配置

3. 客户端SDK集成

3.1 Android SDK集成

3.2 iOS SDK集成

3.3 HarmonyOS SDK集成

4. 服务端API对接

4.1 PushV2接口概述

4.2 前置准备

4.3 Java SDK示例

4.4 Python SDK示例

4.5 PushV2请求参数详解

5. 高级功能与最佳实践

5.1 设备绑定与别名管理

5.2 模板推送与批量推送

5.3 推送策略

5.4 消息撤回

5.5 统计分析

5.6 生命周期管理

5.7 灰度发布与A/B测试

5.8 离线消息与厂商通道最佳实践

6. 常见问题与排查

问题1：设备在线时推送消息已到达，但App端始终没有收到

问题2：厂商通道推送失败

问题3：定时推送未生效

问题4：设备ID获取失败

问题5：批量推送中部分设备未收到消息

7. 总结

8. 常见问题问答

热门文章

最新文章

相关电子书

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

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

1. 移动推送服务概述

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

2.1 创建EMAS项目与应用

2.2 Android厂商通道配置

2.3 iOS推送证书配置

3. 客户端SDK集成

3.1 Android SDK集成

3.2 iOS SDK集成

3.3 HarmonyOS SDK集成

4. 服务端API对接

4.1 PushV2接口概述

4.2 前置准备

4.3 Java SDK示例

4.4 Python SDK示例

4.5 PushV2请求参数详解

5. 高级功能与最佳实践

5.1 设备绑定与别名管理

5.2 模板推送与批量推送

5.3 推送策略

5.4 消息撤回

5.5 统计分析

5.6 生命周期管理

5.7 灰度发布与A/B测试

5.8 离线消息与厂商通道最佳实践

6. 常见问题与排查

问题1：设备在线时推送消息已到达，但App端始终没有收到

问题2：厂商通道推送失败

问题3：定时推送未生效

问题4：设备ID获取失败

问题5：批量推送中部分设备未收到消息

7. 总结

8. 常见问题问答

热门文章

最新文章

相关电子书