消息过期的绝对日期时间,需为 UTC 时间且符合 ISO8601 格式要求,例如:"2019-04-01T06:19:29.000Z"
notification_id
可选
自定义推送 id,最长 16 个字符且只能由英文字母和数字组成,不提供该参数时我们会为每个推送请求随机分配一个唯一的推送 id,用于区分不同推送。我们会根据推送 id 来统计推送的目标设备数和最终消息到达数,并展示在 推送记录 当中。用户自定义推送 id 可以将多个不同的请求并入同一个推送 id 下从而整体统计出这一批推送请求的目标设备数和最终消息到达数。
push_time
可选
设置定时推送的发送时间,需为 UTC 时间且符合 ISO8601 格式要求,例如:"2019-04-01T06:19:29.000Z"。请注意发送时间与当前时间如果小于 1 分钟则推送会立即发出,不会遵循 push_time 参数要求。
仅对使用 Token Authentication 鉴权方式的 iOS 推送有效。当使用 Token Authentication 鉴权方式发 iOS 推送时需要提供设备对应的 Team ID 做鉴权。一般情况下如果您配置的所有 Team ID 下的 APNs Topic 均不重复,或在存储 Installation 时主动设置过 apnsTeamId 值,则无需提供本参数,我们会为每个设备匹配对应的 Team ID 来发推送。否则必须提供本参数且需要通过 where 查询条件保证单次推送请求的目标设备均属于本参数指定的 Team Id,以保证推送正常进行。
目标设备 ID 列表。对于 iOS 设备来说,设备 ID 是 _Installation 表中的 deviceToken 字段;对于使用混合推送的 Android 设备来说,设备 ID 是 _Installation 表中的 registrationId 字段;对于非混合推送的 Android 设备来说,设备 ID 是 _Installation 表中的 installationId 字段;对于 Windows Phone 设备来说,设备 ID 是 _Installation 表中的 subscriptionUri 字段。
expiration_interval
可选
消息过期的相对时间,从调用 API 的时间开始算起,单位是秒。
expiration_time
可选
消息过期的绝对日期时间,需为 UTC 时间且符合 ISO8601 格式要求,例如:"2019-04-01T06:19:29.000Z"
notification_id
可选
自定义推送 id,最长 16 个字符且只能由英文字母和数字组成,不提供该参数时我们会为每个推送请求随机分配一个唯一的推送 id,用于区分不同推送。我们会根据推送 id 来统计推送的目标设备数和最终消息到达数,并展示在 推送记录 当中。用户自定义推送 id 可以将多个不同的请求并入同一个推送 id 下从而整体统计出这一批推送请求的目标设备数和最终消息到达数。
如果权限也没有问题,请确保使用了正确的 provisioning profile。 打包你的应用。如果你上传了开发证书并使用开发证书推送,那么必须使用 Development Provisioning Profile 构建你的应用。如果你上传了生产证书,并且使用生产证书推送,请确保你的应用使用 Distribution Provisioning Profile 签名打包。Ad Hoc 和 App Store Distribution Provisioning Profile 都可以接收使用生产证书发送的消息。
当在一个已经存在的 Apple ID 上启用推送,请记得重新生成 provisioning profile,并到 XCode Organizer 更新。
生产环境的推送证书必须在提交到 App Store 之前启用推送并生成,否则你需要重新提交 App Store。
请在提交 App Store 之前,使用 Ad Hoc Profile 测试生产环境推送,这种情况下的配置最接近于 App Store。
消息推送服务总览
消息推送,使得开发者可以即时地向其应用程序的用户推送通知或者消息,与用户保持互动,从而有效地提高留存率,提升用户体验。平台提供整合了 Android 推送、iOS 推送和 Windows Phone 推送的统一推送服务。
除了 iOS、Android SDK 做推送服务之外,你还可以通过 REST API 来发送推送请求。
基本概念
Installation
Installation 表示一个允许推送的设备的唯一标示,对应 数据管理 平台中的
_Installation
表。它就是一个普通的对象,主要属性包括:deviceProfile
的值必须以字母开头,由大小写字母、数字和下划线组成的字符串,或为空值。增删改查设备,请看后面的 SDK 说明和 REST API 一节。
Notification
对应 控制台 > 消息 > 推送记录 里的一条记录,表示一条推送消息,它包括下列属性:
_Installation
表中符合查询条件且有效的总设备数。有效是指_Installation
表的 valid 字段为 true 且 updatedAt 字段时间在最近三个月以内。目标设备数可能会包含大量的非活跃用户(如已卸载 App 的用户),这部分用户可能无法收到推送。_Installation
表的条件,符合这些查询条件的设备将接收本条推送消息。如何发送消息也请看下面的详细指南。
推送本质上是根据一个 query 条件来查询
_Installation
表里符合条件的设备,然后将消息推送给设备。因为_Installation
是一个可以完全自定义属性的 Key-Value Object,因此可以实现各种复杂条件推送,例如频道订阅、地理位置信息推送、特定用户推送等。对于 devices 和 successes 这两个属性,当 devices 值为 0 时,表示没有找到任何符合目标条件的设备,需要检查一下推送查询条件,这时没有设备能收到推送通知;当 devices 值不为 0 时,该值仅仅说明找到了这么多符合条件的设备,但并不保证这些设备都能收到推送通知,所以 successes 很可能是会小于 devices 的。特别是当查询出来的设备中含有大量的非活跃设备时,successes 可能会和 devices 有很大差距。
如果某个设备不想收到推送提醒,可以将
_Installation
表中相应安装对象的valid
字段修改为false
。注意:我们只保留最近一周的推送记录,并会对过期的推送记录定时进行清理。推送记录清理和推送消息过期时间无关,也就是说即使推送记录被清理,没有过期的推送消息依然是有效的,目标用户依然是能够收到消息。推送过期时间设置请参考 推送消息 一节。
iOS 消息推送
请阅读 iOS 推送开发文档。
Android 消息推送
请阅读 Android 推送开发文档。
Android 混合推送
在部分 Android ROM 上,由于系统对后台进程控制较严,Android 推送的到达率会受到影响。为此我们专门设计了一套称为「混合推送」的高级推送机制,用以提高在这部分 Android ROM 上推送的到达率。
目前 Android 混合推送功能仅对商用版应用开放,如果希望使用该功能,请进入 控制台 > 消息 > 推送 > 设置 > 混合推送,打开混合推送的开关。
请注意,开启混合推送 选项可以根据需要随时进行切换,这样做并不会产生不良影响。当该选项关闭后,下一次 Android 推送会与普通推送一样自动选择 LeanCloud 自有通道送达客户端,除了会再次遇到上面提到的自有通道在部分 ROM 上会受到限制的问题之外,不会有别的影响。而当该选项再次开启后,Android 推送又会去选择第三方推送渠道。
关于混合推送的接入方法和使用方式请阅读 Android 混合推送使用文档。
云引擎和 JavaScript 创建推送
请阅读 JavaScript SDK 指南 · Push 通知。
使用 REST API 推送消息
Installation
当 App 安装到用户设备后,如果要使用消息推送功能,LeanCloud SDK 会自动生成一个 Installation 对象。Installation 对象包含了推送所需要的所有信息。你可以使用 REST API,通过 Installation 对象进行消息推送。
保存 Installation
DeviceToken
iOS 设备通常使用 DeviceToken 来唯一标识一台设备。
installationId
对于 Android 设备,LeanCloud SDK 会自动生成 uuid 作为 installationId 保存到云端。使用 REST API 来保存 installationId 的方法如下:
installationId
必须在应用内唯一。订阅和退订频道
通过设置
channels
属性来订阅某个推送频道,下面假设mrmBZvsErB
是待操作 Installation 对象的 objectId:退订一个频道:
channels
本质上是数组属性,因此可以使用标准 REST API 操作。添加自定义属性
假设
mrmBZvsErB
是待操作 Installation 对象的 objectId,待添加的自定义属性是 userObjectId,值为<用户的 objectId>
:推送消息
通过查询条件发推送
本接口用于根据提供的查询条件,给在 _Installation 表内所有符合查询条件的有效设备记录发推送消息。例如下面是给所有在 _Installation 表中 "channels" 字段包含 "public" 值的有效设备推送一条内容为 "Hello from LeanCloud" 的消息。
本接口支持的参数如下:
_Installation
表使用的查询条件,JSON 对象。如果查询条件内包含日期或二进制等需要做编码的特殊类型数据,查询条件内需要包含编码后的数据。如查询createdAt
字段大于某个时间的设备,where 条件需要为{"createdAt":{"$gte":{"__type":"Date","iso":"2015-06-21T18:02:52.249Z"}}}
。更多信息请参看:数据编码说明通过设备 ID 列表发推送
本接口用于给一批指定的设备 ID 发推送,推送过程因为不用查询目标设备的 Installation 记录,推送速度相对查询方式来说会更快,延迟相对更低。例如下面是给 device token 为 "device_token1", "device_token2", "device_token3" 的 iOS 设备推送一条内容为 "Hello from LeanCloud" 的消息。
本接口的参数由推送渠道无关的通用参数和推送渠道相关的渠道参数两部分组成。通用参数因为跟具体推送渠道无关,无论是给 iOS 设备还是混合推送、非混合推送的 Android 设备发推送都可以带上。
支持的通用参数如下:
如果目标设备为 iOS 设备,则在上述通用参数之外,还可以附带如下参数:
prod
参数值来使用对应的证书。如果目标为 Android 设备,则在前述通用参数之外,还可以附带如下参数:
master key 校验
当在 控制台 > 消息 > 推送 > 设置 > 推送选项 中点选了 禁止从客户端进行消息推送 后,推送消息接口必须增加 master key 校验才能成功发送推送,从而避免了客户端可以不经限制的给应用内任意目标设备推送消息的可能。我们建议用户都将此限制启用。
过期时间
我们建议给 iOS 设备的推送都设置过期时间,这样才能保证在推送的当时,如果用户与 APNs 之间的连接恰好断开(如关闭了手机网络、设置了飞行模式等),在连接恢复之后消息过期之前,用户仍然可以收到推送消息。可以参考 Stackoverflow · Push notification is not being delivered when iPhone comes back online。
过期时间的用法请参考 过期时间和定时推送。
消息内容 Data
iOS 设备推送消息内容
对于 iOS 设备,消息内容参数 data 内属性可以是:
并且 iOS 设备支持
alert
本地化消息推送,只需要将上面alert
参数从 String 替换为一个由本地化消息推送属性组成的 JSON 即可:iOS 支持通过 sound 参数设置推送声音,可以是字符串类型的声音文件名,指向一个在应用内存在的声音文件,或是 JSON 类型:
data 和 alert 内属性的具体含义请参考 Apple 官方关于 Payload Key 的文档,Apple 关于推送提醒本地化的文档,以及 Apple 官方关于 Request Header 的文档。
另外,我们也支持按照上述 Apple 官方文档的方式构造推送参数,如:
Android 设备通用推送消息内容
如果是 Android 设备,默认的消息栏通知消息内容参数支持下列属性:
如果自定义 Receiver,需要设置
action
:关于自定义 Receiver 请参看自定义 Receiver。
Windows Phone 设备推送消息内容
Windows Phone 设备类似,也支持
title
和alert
,同时支持wp-param
用于定义打开通知的时候打开的是哪个 Page:为多种类型设备设置不同推送内容
单次推送中,如果查询条件覆盖的目标推送设备包含多种类型,如既包含 iOS 设备,又包含 LeanCloud 自有渠道的 Android 设备,又有混合推送的小米华为设备等,可以为不同推送设备单独填写推送内容参数,我们会按照设备类型取出对应设备类型的推送内容来发推送,例如:
其中属性名称和推送平台对应关系如下:
iOS 测试和生产证书区分
我们现在支持上传两个环境的 iOS 推送证书:测试和生产环境,你可以通过设定
prod
属性来指定使用哪个环境证书。如果是
dev
值就表示使用开发证书,prod
值表示使用生产证书。如果未设置prod
属性,且使用的不是 JavaScript 数据存储 SDK,我们默认使用生产证书来发推送。如果未设置prod
属性,且使用的是 JavaScript 数据存储 SDK ,则需要在发推送之前执行 AV.setProduction 函数才会使用生产证书发推送,否则会以开发证书发推送。注意,当设备设置了deviceProfile
时我们优先按照deviceProfile
指定的证书推送。Android 推送区分透传和通知栏消息
Android 推送(包括 Android 混合推送)支持透传和通知栏两种消息类型。透传消息是指消息到达设备后会先交给 LeanCloud Android SDK,再由 SDK 将消息通过 自定义 Receiver 传递给开发者,收到消息后的行为由开发者定义的 Receiver 来决定,SDK 不会自动弹出通知栏提醒。而通知栏消息是指消息到达设备后会立即自动弹出通知栏提醒。
LeanCloud 推送服务通过推送请求中
data
参数内的silent
字段区分透传和通知栏消息。如果silent
是true
则表示这个消息是透传消息,为false
表示消息是通知栏消息。如果不传递silent
则默认其值为false
。另外请注意,如果希望接收透传消息请不要忘记自行实现 自定义 Receiver。推送请求中的
data
参数请参考 消息内容 Data。Android 混合推送多配置区分
如果使用了混合推送功能,并且在 控制台 > 消息 > 推送 > 设置 > 混合推送 增加了多个混合推送配置,那么在向
_Installation
表保存设备信息时就需要将当前设备所对应的混合推送配置名存入deviceProfile
字段。系统会按照该字段指定的唯一配置名为每个目标设备进行混合推送。如果
deviceProfile
字段为空,系统会默认使用名为_default
的混合推送配置来进行推送,所以一定要保证在控制台的混合推送设置中,存在以_default
命名的 Profile 并且已被正确配置,否则系统会拒绝推送。deviceProfile
的值必须以字母开头,由大小写字母、数字和下划线组成的字符串,或为空值。推送查询条件
_Installation
表中的所有属性,无论是内置的还是自定义的,都可以作为查询条件通过 where 来指定,并且支持 REST API 定义的各种复杂查询。下面会举一些例子,更多例子请参考 REST API 查询文档。
推送给所有的设备
发送给特定的用户
或者更简便的方式
用
where
查询的都是_Installations
表中的属性。这里假设该表存储了inStock
的布尔属性。上面的例子假设 installation 有个 owner 属性指向
_User
表的记录,并且用户有个location
属性是 GeoPoint 类型,我们就可以根据地理信息位置做推送。过期时间和定时推送
expiration_time
属性用于指定消息的过期时间,如果客户端收到消息的时间超过这个绝对时间,那么消息将不显示给用户。expiration_time
是一个 UTC 时间的字符串,格式为YYYY-MM-DDTHH:MM:SS.MMMZ
。expiration_interval
也可以用于指定过期时间,不过这是一个相对时间,以秒为单位,从 API 调用时间点开始计算起:push_time
是定时推送的时间,格式为YYYY-MM-DDTHH:MM:SS.MMMZ
的 UTC 时间,也可以结合expiration_interval
设定过期时间:推送消息属性
消息过期
过期时间,可以是绝对时间:
也可以是相对时间(从推送 API 调用开始算起,结合 push_time 做定期推送):
定制消息属性:
推送记录查询
/push
接口在推送后会返回代表该条推送消息的objectId
,你可以使用这个 ID 调用下列 API 查询推送记录:其中 URL 里的
:objectId
替换成/push
接口返回的 objectId 。将返回推送记录对象,推送记录各字段含义参考 Notification 说明。
推送状态查看和取消
在发推送的过程中,我们会随着推送任务的执行更新推送状态到 控制台 > 消息 > 推送记录 中,可以在这里查看推送的最新状态。对不同推送状态的说明请参看 Notification 表详解。
在一条推送记录状态到达 done 即完成推送之前,其状态信息旁边会显示 “取消推送” 按钮,点击后就能将本次推送取消。并且取消了的推送会从推送记录中删除。
请注意取消推送的意思是取消还排在队列中未发出的推送,已经发出或已存入离线缓存的推送是无法取消的。同理,推送状态显示已经完成的推送也无法取消。请尽力在发推送前做好测试,确认好发送内容和目标设备查询条件。
定时推送任务查询和取消
可以使用 master key 查询当前正在等待推送的定时推送任务:
查询出来的结果类似:
其中
push_msg
就是该推送消息的详情,expire_time
是消息设定推送时间的 unix 时间戳。取消一个定时推送任务,要使用返回结果中最外层的 id。以上面的结果为例,即为
results[0].id
,而不是results[0].push_msg.id
:限制与费用
推送消息接口
推送消息接口的调用受频率限制,限制如下:
超过频率限制后 1 分钟内 LeanCloud 会拒绝请求持续返回 429 错误码,一分钟后会重新处理请求。
商用版应用默认上限可以在 控制台 > 消息 > 推送 > 设置 > 推送选项 > 消息推送 API 调用频率上限 修改。 按照每日调用频率峰值实行阶梯收费,费用如下:
国际版
每日调用频率峰值可在 控制台 > 消息 > 推送 > 统计 > API 请求频率峰值 中查看。
每日推送人次
限制如下:
达到限制后,当天将无法再推送消息。
商用版应用默认上限可以在 控制台 > 消息 > 推送 > 设置 > 推送选项 > 每日推送上限 修改。 费用如下(其中不足一万人次的部分,按一万人次计算):
国际版
每日推送人次可在 控制台 > 消息 > 推送 > 统计 > 推送人次 中查看。
其它
_Installation
表内updatedAt
时间在最近三个月以内的设备推送消息。我们会在根据推送查询条件查出目标设备后自动将不符合条件的设备从目标设备中剔除,并且被剔除的设备不会计入 控制台 > 消息 > 推送记录 内的目标设备数中。商用版用户如有特别需求,可提交工单联系我们付费延长有效期(最长可延长至一年)。如果推送失败,在 控制台 > 消息 > 推送记录 > 状态 一栏中会看到错误提示。
Installation 自动过期和清理
每当用户打开应用,我们都会更新该设备的
_Installation
表中的updatedAt
时间戳。如果用户长期没有更新_Installation
表的updatedAt
时间戳,也就意味着该用户长期没有打开过应用。当超过 90 天没有打开过应用时,我们会将这个用户在_Installation
表中的记录删除。不过请不要担心,当用户再次打开应用的时候,仍然会自动创建一个新的 Installation 用于推送。对于 iOS 设备,除了上述过期机制外还多拥有一套过期机制。当我们根据 Apple 推送服务的反馈获取到某设备的 deviceToken 已过期时,我们也会将这个设备在
_Installation
表中的信息删除,并标记这个已过期的 deviceToken 为无效,丢弃后续所有发送到该 deviceToken 的消息。推送问题排查
推送因为环节较多,跟设备和网络都相关,并且调用都是异步化,因此问题比较难以查找,这里提供一些有用助于排查消息推送问题的技巧。
推送结果查询
所有经过
/push
接口发出的消息的都可以在控制台的消息菜单里的推送记录看到。每次调用/push
都将产生一条新的 推送记录表示一次推送。该表的各属性含义请参考 Notification 表详解 。/push
接口会返回新建的推送记录的objectId
,你就可以在推送记录里根据 ID 查询消息推送的结果。iOS 推送排查建议
iOS 推送问题的一些排查建议:
devices
和status
,确认推送状态和接收设备数目正常。invalidTokens
字段,如果该数字异常大,可能证书选择错误,跟设备 build 的 provisioning profile 不匹配。Android 排查建议
Android 推送问题的一些建议和提示:
AVInstallation
保存了设备信息到 _Installation 表。installationId
查询设备是否在线。com.avos.avoscloud.PushService
添加到 AndroidManifest.xml 文件中。