消息过期的绝对日期时间,需为 UTC 时间且符合 ISO8601 格式要求,例如:"2019-04-01T06:19:29.000Z"。如果客户端收到消息的时间超过消息过期的时间,那么消息将不显示给用户。
expiration_interval
可选
消息过期的相对时间,单位是秒。从 push_time 开始算起,未指定 push_time 时从调用 API 的时间开始算起。建议推送都设置 expiration_time 或 expiration_interval,避免用户长时间断网并重新联网后收到一大堆已失效的推送信息。
notification_id
可选
自定义推送 id,最长 16 个字符且只能由英文字母和数字组成,不提供该参数时我们会为每个推送请求随机分配一个唯一的推送 id,用于区分不同推送。我们会根据推送 id 来统计推送的目标设备数和最终消息到达数,并展示在云服务控制台的推送记录中。用户自定义推送 id 可以将多个不同的请求并入同一个推送 id 下从而整体统计出这一批推送请求的目标设备数和最终消息到达数。
仅对使用 Token Authentication 鉴权方式的 iOS 推送有效。当使用 Token Authentication 鉴权方式发 iOS 推送时需要提供设备对应的 Team ID 做鉴权。一般情况下如果您配置的所有 Team ID 下的 APNs Topic 均不重复,或在存储 Installation 时主动设置过 apnsTeamId 值,则无需提供本参数,我们会为每个设备匹配对应的 Team ID 来发推送。否则必须提供本参数且需要通过 where 查询条件保证单次推送请求的目标设备均属于本参数指定的 Team ID,以保证推送正常进行。
推送 REST API 使用指南
当 App 安装到用户设备后,如果要使用推送功能,云服务 SDK 会自动生成一个 Installation 对象。Installation 对象包含了推送所需要的所有信息。你可以使用 REST API,通过 Installation 对象进行推送。
请求的 Base URL 可以在云服务控制台 > 设置 > 应用凭证 > 服务器地址查看。 对于 POST 和 PUT 请求,请求的主体必须是 JSON 格式,而且 HTTP Header 的 Content-Type 需要设置为
application/json
。 请求的鉴权是通过 HTTP Header 里面包含的键值对来进行的,详见《存储 REST API 使用指南》中《请求格式》一节的说明。Installation
你可以通过 REST API 在云端增加安装对象。 使用 REST API 还可以达成一些客户端 SDK 无法完成的操作,比如查询所有的 installation 来找到一个 channel 的订阅者的集合。
增加 Installation
创建一个安装对象和普通的对象差不多,只是不同平台有不同的字段。
创建成功后,HTTP 的返回值为 201 Created,Location header 包括了新的安装的 URL:
返回的 body 是一个 JSON 对象,包括了 objectId 和 createdAt 这个创建对象的时间戳。
DeviceToken
iOS 设备通常使用 DeviceToken 来唯一标识一台设备。
installationId
对于 Android 设备,SDK 会自动生成 uuid 作为 installationId 保存到云端。
installationId
必须在应用内唯一。获取 Installation
你可以通过 GET 方法请求创建的时候 Location 表示的 URL 来获取 Installation 对象。比如,获取上面创建的对象:
返回的 JSON 对象所有用户提供的字段,加上 createdAt、updatedAt 和 objectId 字段:
更新 Installation
安装对象可以向相应的 URL 发送 PUT 请求来更新。例如,通过设置
channels
属性来订阅某个推送频道:再比如退订一个频道:
channels
本质上是数组属性,因此可以使用标准的数组操作。又比如添加自定义属性:
查询 Installation
你可以一次通过 GET 请求到 installations 的根 URL 来获取多个安装对象。这项功能在 SDK 中不可用。
没有任何 URL 参数的话,一个 GET 请求会列出所有安装:
返回的 JSON 对象的 results 字段包含了所有的结果:
所有对普通的对象的查询都对 installation 对象起作用,所以可以查看之前的查询部分以获取详细信息。通过做 channels 的数组查询,你可以查找一个订阅了给定的推送频道的所有设备。
出于安全性考虑,默认情况下,云端未开放 installation 查找权限,所以通常这个接口需要使用 master key 鉴权。
删除 Installaion
为了从 LeanCloud 中删除一个安装对象,可以发送 DELETE 请求到相应的 URL。这个功能在客户端 SDK 也不可用。举例:
出于安全性考虑,默认情况下,云端未开放 installation 删除权限,所以通常这个接口需要使用 master key 鉴权。
Installation 自动过期和清理
每当用户打开应用,我们都会更新该设备的
_Installation
表中的updatedAt
时间戳。如果用户长期没有更新_Installation
表的updatedAt
时间戳,也就意味着该用户长期没有打开过应用。当超过 90 天没有打开过应用时,我们会将这个用户在_Installation
表中的记录删除。不过请不要担心,当用户再次打开应用的时候,仍然会自动创建一个新的 Installation 用于推送。对于 iOS 设备,除了上述过期机制外还多拥有一套过期机制。当我们根据 Apple 推送服务的反馈获取到某设备的 deviceToken 已过期时,我们也会将这个设备在
_Installation
表中的信息删除,并标记这个已过期的 deviceToken 为无效,丢弃后续所有发送到该 deviceToken 的消息。推送消息
API 接口一览
master key 校验
当在云服务控制台 > 推送 > 设置 > 推送设置中点选了 禁止从客户端进行消息推送 后, 必须通过 master key 才能发送推送,从而避免了客户端可以不经限制的给应用内任意目标设备推送消息的可能。 这一限制默认为启用状态。 我们建议用户都将此限制启用。
消息内容参数
iOS 设备推送消息内容参数
iOS 设备中 data 和 alert 内属性的具体含义请参考:
下面是对各属性的一些具体说明:
iOS 设备 data 各属性说明
示例:
iOS 设备 alert 各属性说明
并且 iOS 设备支持
alert
本地化消息推送,只需要将上面alert
参数从 String 替换为一个由本地化消息推送属性组成的 JSON 即可:示例:
iOS 设备 sound 各属性说明
iOS 支持通过 sound 参数设置推送声音,可以是字符串类型的声音文件名,指向一个在应用内存在的声音文件,或是 JSON 类型:
示例:
iOS 设备其他说明
另外,我们也支持按照上述 Apple 官方文档的方式构造推送参数例如:
更详细的描述如下面例子描述:
Android 设备通用推送消息内容参数
如果是 Android 设备,默认的消息栏通知消息内容参数支持下列属性:
通知栏消息
。示例:
关于
silent
参数请参看 Android 推送区分透传和通知栏消息,关于自定义 Receiver 请参看《Android 消息推送开发指南》的《自定义 Receiver》一节。为多种类型设备设置不同推送内容
单次推送中,如果查询条件覆盖的目标推送设备包含多种类型,如既包含 iOS 设备,又包含云服务自有渠道的 Android 设备,又有混合推送的小米华为设备等,可以为不同推送设备单独填写推送内容参数,我们会按照设备类型取出对应设备类型的推送内容来发推送。
其中属性名称和推送平台对应关系如下:
下面是一些推送消息举例:
混合推送会发送推送到不同厂商,而每个厂商所支持的参数都是不尽相同的,我们对最常用的参数做了适配,而如果需要有针对性的使用更精确的厂商推送参数,可以在对应类型的内容参数下进行设置。 举例来说,vivo 有一个
pushMode
来标记推送模式是正式推送还是测试推送,就可以使用如下方式来传递:通过查询条件发推送
本接口用于根据提供的查询条件,给在 _Installation 表内所有符合查询条件的有效设备记录发推送消息。例如下面是给所有在 _Installation 表中
channels
字段包含public
值的有效设备推送一条内容为Hello from LeanCloud
的消息。请注意,本接口限制请求的 HTTP Body 大小必须小于 4096 个字节,即您调用本接口传递的所有参数做 JSON 序列化后得到的结果不能超过此限制。
本接口支持的参数如下:
_Installation
表使用的查询条件,JSON 对象。如果查询条件内包含日期或二进制等需要做编码的特殊类型数据,查询条件内需要包含编码后的数据。如查询createdAt
字段大于某个时间的设备,where 条件需要为{"createdAt":{"$gte":{"__type":"Date","iso":"2015-06-21T18:02:52.249Z"}}}
。更多信息请参看《存储 REST API 使用指南》的《数据类型》一节的说明。2019-04-01T06:19:29.000Z
。请注意发送时间与当前时间如果小于 1 分钟则推送会立即发出,不会遵循 push_time 参数要求。如果需要实现周期推送,可以参照 使用云引擎实现周期推送 实现。push_time
开始算起,未指定push_time
时从调用 API 的时间开始算起。建议推送都设置expiration_time
或expiration_interval
,避免用户长时间断网并重新联网后收到一大堆已失效的推送信息。prod
时,如果传入了X-LC-Prod
HTTP 头,且其值不为 1,那么视同"prod": "dev"
,否则默认"prod": "prod"
。在使用证书鉴权方式下,当设备在 Installation 记录中设置了 deviceProfile 时我们优先按照 deviceProfile 指定的证书推送。_Installation
表中的所有属性,无论是内置的还是自定义的,都可以作为查询条件通过 where 来指定,并且支持各种复杂查询。成功时会返回本次推送的 objectId,后续可以用返回的 objectId 查询推送记录。
失败时会返回错误码和错误原因:
下面会举一些例子,更多例子请参考《存储 REST API 使用指南》的《查询》一节。
推送给所有的设备
推送给 android 设备
推送给 public 频道的设备
推送给不活跃的设备
推送给自定义属性符合条件的设备
用
where
查询的都是_Installations
表中的属性。这里假设该表存储了preOrder
的布尔属性。根据地理信息位置做推送
上面的例子假设 installation 有个 owner 属性指向
_User
表的记录,并且用户有个location
属性是 GeoPoint 类型,我们就可以根据地理信息位置做推送。通过设备 ID 列表发推送
本接口用于给一批指定的设备 ID 发推送,推送过程因为不用查询目标设备的 Installation 记录,推送速度相对查询方式来说会更快,延迟相对更低。例如下面是给 device token 为 "device_token1", "device_token2", "device_token3" 的 iOS 设备推送一条内容为
Hello
的消息。本接口的参数由推送渠道无关的通用参数和推送渠道相关的渠道参数两部分组成。通用参数因为跟具体推送渠道无关,无论是给 iOS 设备还是混合推送、非混合推送的 Android 设备发推送都可以带上。
支持的通用参数如下:
如果目标设备为 iOS 设备,则在上述通用参数之外,还可以附带如下参数:
prod
参数值来使用对应的证书。如果目标为 Android 设备,则在前述通用参数之外,还可以附带如下参数:
Android 混合推送多配置区分
如果使用了混合推送功能,并且在 云服务控制台 > 推送 > 设置 > 混合推送 增加了多个混合推送配置,那么在向
_Installation
表保存设备信息时就需要将当前设备所对应的混合推送配置名存入deviceProfile
字段。系统会按照该字段指定的唯一配置名为每个目标设备进行混合推送。如果
deviceProfile
字段为空,系统会默认使用名为_default
的混合推送配置来进行推送,所以一定要保证在控制台的混合推送设置中,存在以_default
命名的 Profile 并且已被正确配置,否则系统会拒绝推送。deviceProfile
的值必须以字母开头,由大小写字母、数字和下划线组成的字符串,或为空值。Android 推送区分透传和通知栏消息
Android 推送(包括 Android 混合推送)支持透传和通知栏两种消息类型。透传消息是指消息到达设备后会先交给 LeanCloud Android SDK,再由 SDK 将消息通过自定义 Receiver 传递给开发者,收到消息后的行为由开发者定义的 Receiver 来决定,SDK 不会自动弹出通知栏提醒。而通知栏消息是指消息到达设备后会立即自动弹出通知栏提醒。
推送服务通过推送请求中
data
参数内的silent
字段区分透传和通知栏消息。silent
为true
表示这个消息是透传消息,为false
表示消息是通知栏消息。 如果不传递silent
则默认其值为false
。 另外请注意,如果希望接收透传消息请不要忘记自行实现自定义 Receiver,参见《Android 消息推送开发指南》的《自定义 Receiver》一节的说明。过期时间和定时推送
如上所述,可以用
expiration_time
参数指定消息的过期时间:expiration_interval
也可以用于指定过期时间,一般结合定时推送使用:定时推送任务查询和取消
调用
POST /scheduledPushMessages
接口可以查询当前正在等待推送的定时推送任务,调用这个接口需要使用 master key:查询出来的结果类似:
其中
push_msg
就是该推送消息的详情,expire_time
是消息设定推送时间的 unix 时间戳。根据查询的结果,就可以取消一个定时推送任务。 注意需要使用返回结果中最外层的 id。 比如取消第一个定时推送,需要使用
results[0].id
,而不是results[0].push_msg.id
。 就上面的例子而言,应该使用1
而不是XRs9jmWnLd0GH2EH
:使用云引擎实现周期推送
可以配合
云引擎
的定时任务
功能实现周期推送,非常方便。请阅读《在云引擎中使用推送服务》。推送记录查询
/push
接口在推送后会返回代表该条推送消息的objectId
,你可以使用这个 ID 调用下列 API 查询推送记录:其中 URL 里的
:objectId
替换成/push
接口返回的 objectId 。将返回推送记录对象,推送记录各字段含义参考《推送服务总览》的《Notification》一节。
推送状态查看和取消
在发推送的过程中,我们会随着推送任务的执行更新推送状态到 云服务控制台 > 推送 > 推送记录 中,可以在这里查看推送的最新状态。对不同推送状态的说明请参看《推送服务总览》的《Notification》一节。
在一条推送记录状态到达 done 即完成推送之前,其状态信息旁边会显示 “取消推送” 按钮,点击后就能将本次推送取消。并且取消了的推送会从推送记录中删除。
请注意取消推送的意思是取消还排在队列中未发出的推送,已经发出或已存入离线缓存的推送是无法取消的。同理,推送状态显示已经完成的推送也无法取消。请尽量在发推送前做好测试,确认好发送内容和目标设备查询条件。
限制与费用
推送消息接口
推送消息接口的调用受频率限制,限制如下:
超过频率限制后 1 分钟内云端会拒绝请求持续返回 429 错误码,一分钟后会重新处理请求。
商用版应用默认上限可以在 云服务控制台 > 推送 > 设置 > 推送设置 > 消息推送 API 调用频率上限 修改。 按照每日调用频率峰值实行阶梯收费,费用如下:
国际版
每日调用频率峰值可在 云服务控制台 > 推送 > 统计 > REST API QPM 峰值 中查看。
每日推送人次
限制如下:
达到限制后,当天将无法再推送消息。
商用版应用默认上限可以在 云服务控制台 > 推送 > 设置 > 推送设置 > 每日推送上限 修改。 费用如下(其中不足一万人次的部分,按一万人次计算):
国际版
每日推送人次可在 云服务控制台 > 推送 > 统计 > 推送人次 中查看。
其它
_Installation
表内updatedAt
时间在最近三个月以内的设备推送消息。我们会在根据推送查询条件查出目标设备后自动将不符合条件的设备从目标设备中剔除,并且被剔除的设备不会计入 云服务控制台 > 推送 > 推送记录 内的目标设备数中。商用版用户如有特别需求,可提交工单联系我们付费延长有效期(最长可延长至一年)。如果推送失败,在 云服务控制台 > 推送 > 推送记录 的 状态 一栏中会看到错误提示。