AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 移动研发平台 移动推送 实践教程 PushV2接口接入指南

PushV2接口接入指南

更新时间：
产品详情
我的收藏

本文档提供阿里云移动推送服务 PushV2 的接入指南和最佳实践，帮助你快速集成 SDK 并实现向 iOS、Android 和 HarmonyOS 设备推送消息和通知。如果您当前正在使用Push接口，请阅读这篇从Push接口到PushV2接口迁移指南。

快速入门

前置准备

  1. 登录阿里云移动推送控制台，创建应用并获取 AppKey

  2. 获取阿里云 AccessKey ID 和 AccessKey Secret

  3. 设置环境变量：

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

SDK集成

在pom.xml中添加依赖，最新版本请查看阿里云SDK中心：

<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

object QuickStart {
    @JvmStatic
    fun main(args: Array<String>) {
        // 1. 创建客户端
        val client = createClient()

        // 2. 构建推送请求
        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)

        // 3. 发送推送
        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)
    }
}

构建推送请求

请求结构预览

新版推送采用结构化请求体设计，将众多参数分类组织，便于开发者按需灵活传参。整体结构预览如下，详情参数请参考文档PushTask：

image

方式一：使用JSON快速构建请求

您可以通过 JSON 字符串快速定义推送请求内容，适用于配置简单、结构清晰的场景。示例如下：

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)
说明

示例代码使用fastjson库，需要添加依赖，您也可以使用其他任意json库：

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>${VERSION}</version>
</dependency>

方式二：使用结构体构建请求

您可以通过 SDK 提供的结构体，以链式或逐层赋值的方式清晰、安全地构建推送请求。该方式具备良好的可读性与类型安全性，便于在复杂业务逻辑中维护和扩展。示例如下：

val request = PushV2Request().apply {
    this.appKey = 233586006
    this.pushTask = PushTask().apply {
        this.target = PushTask.PushTaskTarget().apply {
            this.type = "DEVICE"
            this.value = "device-id"
            this.platform = "IOS"
        }
        this.message = PushTask.PushTaskMessage().apply {
            this.title = "消息标题"
            this.body = "消息内容"
        }
    }
}

常见推送场景

场景一：发送透传消息

透传消息直接发送到应用，由应用自行处理，不显示系统通知。

{
  "AppKey": 233586006,
  "PushTask": {
    "Target": {
      "Type": "DEVICE",
      "Value": "device-id",
      "Platform": "IOS"
    },
    "Message": {
      "Title": "数据同步",
      "Body": "{\"type\": \"sync\", \"data\": \"...\"}"
    }
  }
}

使用场景：

  • 应用在线时接收实时数据

  • 数据同步

  • 应用内消息

注意事项：

  • 设备离线时消息会丢失（除非设置过期时间 PushTask.Options.ExpireTime）

  • Body 建议使用 JSON 格式

  • 建议总长度不超过 4000 字节

场景二：发送通知消息

通知消息显示在设备通知栏，用户可点击查看。

  • iOS 通知示例：

{
  "AppKey": 233586006,
  "PushTask": {
    "Target": {
      "Type": "DEVICE",
      "Value": "device-id",
      "Platform": "IOS"
    },
    "Notification": {
      "Title": "订单提醒",
      "Body": "您有一笔新订单",
      "Ios": {
        "ApnsEnv": "DEV",
        "Badge": 1,
        "Music": "default",
        "ExtParameters": "{\"orderId\": \"123456\"}"
      }
    }
  }
}

  • Android 通知示例：

{
  "AppKey": 233586006,
  "PushTask": {
    "Target": {
      "Type": "DEVICE",
      "Value": "device-id",
      "Platform": "ANDROID"
    },
    "Notification": {
      "Title": "订单提醒",
      "Body": "您有一笔新订单",
      "Android": {
        "BadgeSetNum": 1,
        "VendorChannelActivity": "com.example.MainActivity",
        "ChannelId": "8.0up",
        "ExtParameters": "{\"orderId\": \"123456\"}",
        "TestMessage": true
      }
    }
  }
}

  • HarmonyOS 通知示例：

{
  "AppKey": 233586006,
  "PushTask": {
    "Target": {
      "Type": "DEVICE",
      "Value": "device-id",
      "Platform": "HMOS"
    },
    "Notification": {
      "Title": "订单提醒",
      "Body": "您有一笔新订单",
      "Hmos": {
        "BadgeSetNum": 1,
        "ExtParameters": "{\"orderId\": \"123456\"}"
      }
    }
  }
}

场景三：消息离线转通知

同时设置 Message 和 Notification，设备在线时发送透传消息，离线时发送通知。

{
  "AppKey": 233586006,
  "PushTask": {
    "Target": {
      "Type": "DEVICE",
      "Value": "device-id",
      "Platform": "IOS"
    },
    "Message": {
      "Title": "新消息",
      "Body": "{\"type\": \"chat\", \"content\": \"你好\"}"
    },
    "Notification": {
      "Title": "新消息",
      "Body": "你收到一条新消息",
      "Ios": {
        "ApnsEnv": "DEV",
        "Badge": 1,
        "ExtParameters": "{\"orderId\": \"123456\"}"
      }
    }
  }
}

使用场景：

  • 重要业务消息，确保送达

  • 既需要应用在线处理，又需要离线提醒

场景四：定时推送

在指定时刻推送消息和通知。

{
  "AppKey": 233586006,
  "PushTask": {
    "Action": "SCHEDULED_PUSH",
    "Target": {
      "Type": "DEVICE",
      "Value": "device-id",
      "Platform": "IOS"
    },
    "Notification": {
      "Title": "活动提醒",
      "Body": "您预约的活动即将开始",
      "Ios": {
        "ApnsEnv": "PRODUCT"
      }
    },
    "Options": {
      "PushTime": "2025-06-19T12:00:00Z"
    }
  }
}

场景五：持续推送

持续推送用于向不同批次的设备推送相同的消息内容，避免重复构建消息。

创建持续推送任务

配置要点

  • Action 设置为 CREATE_CONTINUOUS_PUSH

  • 只设置 Notification，不设置 Target

  • 配置完整的消息内容

返回结果

  • 获得 MessageId，用于后续推送

{
  "AppKey": 233586006,
  "PushTask": {
    "Action": "CREATE_CONTINUOUS_PUSH",
    "Notification": {
      "Title": "惊喜活动",
      "Body": "现在下单立享8折优惠",
      "Ios": {
        "ApnsEnv": "PRODUCT"
      }
    }
  }
}

执行持续推送

配置要点

  • Action 设置为 CONTINUOUS_PUSH

  • 设置 Target 指定推送目标

  • 在 Options 中设置 MessageId

目标限制

  • 仅支持 DEVICE、ACCOUNT、ALIAS 三种类型

  • 单次最多 1000 个目标

{
  "AppKey": 233586006,
  "PushTask": {
    "Action": "CONTINUOUS_PUSH",
    "Target": {
      "Type": "DEVICE",
      "Value": "device-id",
      "Platform": "IOS"
    },
    "Options": {
      "MessageId": 11747540331280012
    }
  }
}

常见问题

Q1：推送成功但设备未收到？

可能原因：

  • DeviceId 错误或设备未注册

  • iOS 环境配置错误（DEV/PRODUCT）

  • Android VendorChannelActivity 配置错误

  • 消息已过期

解决方案：

  • 检查 DeviceId 是否正确

  • 确认 iOS ApnsEnv 配置与证书环境一致

  • 验证 Android Activity 配置

  • 设置合理的过期时间

  • 使用控制台排查消息进行排查

Q2：如何提高 Android 推送到达率？

最佳实践：

  • 必须填写 VendorChannelActivity、ChannelId

  • 配置各厂商特定参数

  • 设置合理的消息分类和重要性

Q3：如何实现推送去重？

方案：

  • 使用 IdempotentToken 实现接口幂等

  • 使用 NotifyId（Android）或 CollapseId（iOS）实现通知覆盖

  • 业务层面控制推送频率

Q4：透传消息和通知消息如何选择？

选择建议：

  • 需要应用在线处理且不希望显示通知 → 透传消息

  • 需要系统通知栏提醒用户 → 通知消息

  • 既需要在线处理又需要离线提醒 → 同时设置

参数速查表

时间格式

所有时间参数使用 ISO8601 格式（UTC 时间）：

  • 格式：yyyy-MM-dd'T'HH:mm:ss'Z'

  • 示例：2025-10-17T16:00:00Z

长度限制

内容

限制

说明

Message 整体

4000 字节

UTF-8 编码

iOS/Harmony 通知标题

200 字节

UTF-8 编码

Android 通知标题

50 字符

-

通知正文

200 字符

-

ExtParameters

-

标准 JSON 格式

目标数量限制

目标类型

单次最大数量

DEVICE

1000

ACCOUNT

1000

ALIAS

1000

TAG

无限制（标签表达式）

ALL

全量

参考资料

上一篇：如何订阅/取消订阅iOS P12证书到期提醒下一篇：从Push接口到PushV2接口迁移指南