推送 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 的订阅者的集合。
URL | HTTP | 功能 |
---|---|---|
/1.1/installations | POST | 上传安 装数据 |
/1.1/installations/<objectId> | GET | 获取安装数据 |
/1.1/installations/<objectId> | PUT | 更新安装数据 |
/1.1/installations | GET | 查询安装数据 |
/1.1/installations/<objectId> | DELETE | 删除安装数据 |
增加 Installation
创建一个安装对象和普通的对象差不多,只是不同平台有不同的字段。
创建成功后,HTTP 的返回值为 201 Created,Location header 包括了新的安装的 URL:
Status: 201 Created
Location: https://{{host}}/1.1/installations/51ff1808e4b074ac5c34d7fd
返回的 body 是一个 JSON 对象,包括了 objectId 和 createdAt 这个创建对象的时间戳。
{
"createdAt": "2012-04-28T17:41:09.106Z",
"objectId": "51ff1808e4b074ac5c34d7fd"
}
DeviceToken
iOS 设备通常使用 DeviceToken 来唯一标识一台设备。
curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
-H "Content-Type: application/json" \
-d '{
"deviceType": "ios",
"deviceToken": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
"channels": [
"public", "protected", "private"
]
}' \
https://{{host}}/1.1/installations
installationId
对于 Android 设备,SDK 会自动生成 uuid 作为 installationId 保存到云端。
curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
-H "Content-Type: application/json" \
-d '{
"deviceType": "android",
"installationId": "12345678-4312-1234-1234-1234567890ab",
"channels": [
"public", "protected", "private"
]
}' \
https://{{host}}/1.1/installations
installationId
必须在应用内唯一。
获取 Installation
你可以通过 GET 方法请求创建的时候 Location 表示的 URL 来获取 Installation 对象。比如,获取上面创建的对象:
curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
https://{{host}}/1.1/installations/51ff1808e4b074ac5c34d7fd
返回的 JSON 对象包含所有用户提供的字段,加上 createdAt、updatedAt 和 objectId 字段:
{
"deviceType": "ios",
"deviceToken": "abcdefghijklmnopqrstuvwzxyrandomuuidforyourdevice012345678988",
"channels": [
""
],
"createdAt": "2012-04-28T17:41:09.106Z",
"updatedAt": "2012-04-28T17:41:09.106Z",
"objectId": "51ff1808e4b074ac5c34d7fd"
}
更新 Installation
安装对象可以向相应的 URL 发送 PUT 请求来更新。例如,通过设置 channels
属性来订阅某个推送频道:
curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
-H "Content-Type: application/json" \
-d '{
"deviceType": "ios",
"deviceToken": "abcdefghijklmnopqrstuvwzxyrandomuuidforyourdevice012345678988",
"channels": [
"",
"foo"
]
}' \
https://{{host}}/1.1/installations/51ff1808e4b074ac5c34d7fd
再比如退订一个频道:
curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
-H "Content-Type: application/json" \
-d '{
"channels": {
"__op":"Remove",
"objects":["customer"]
}
}' \
https://{{host}}/1.1/installations/51ff1808e4b074ac5c34d7fd
channels
本质上是数组属性,因此可以使用标准的数组操作。
又比如添加自定义属性:
curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
-H "Content-Type: application/json" \
-d '{
"userObjectId": "<用户的 objectId>"
}' \
https://{{host}}/1.1/installations/51ff1808e4b074ac5c34d7fd
查询 Installation
你可以一次通过 GET 请求到 installations 的根 URL 来获取多个安装对象。这项功能在 SDK 中不可用。
没有任何 URL 参数的话,一个 GET 请求会列出所有安装:
curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.1/installations
返回的 JSON 对象的 results 字段包含了所有的结果:
{
"results": [
{
"deviceType": "ios",
"deviceToken": "abcdefghijklmnopqrstuvwzxyrandomuuidforyourdevice012345678988",
"channels": [
""
],
"createdAt": "2012-04-28T17:41:09.106Z",
"updatedAt": "2012-04-28T17:41:09.106Z",
"objectId": "51ff1808e4b074ac5c34d7fd"
},
{
"deviceType": "ios",
"deviceToken": "876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9",
"channels": [
""
],
"createdAt": "2012-04-30T01:52:57.975Z",
"updatedAt": "2012-04-30T01:52:57.975Z",
"objectId": "51fcb74ee4b074ac5c34cf85"
}
]
}
所有对普通的对象的查询都对 installation 对象起作用,所以可以查看之前的查询部分以获取详细信息。通过做 channels 的数组查询,你可以查找一个订阅了给定的推送频道的所有设备。
出于安全性考虑,云端默认未开放 installation 查找权限,所以通常这个接口需要使用 master key 鉴权。
删除 Installation
为了从 LeanCloud 中删除一个安装对象,可以发送 DELETE 请求到相应的 URL。这个功能在客户端 SDK 也不可用。举例:
curl -X DELETE \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{masterkey}},master" \
https://{{host}}/1.1/installations/51fcb74ee4b074ac5c34cf85
出于安全性考虑,云端默认未开放 installation 删除权限,所以通常这个接口需要使用 master key 鉴权。
Installation 自动过期和清理
每当用户打开应用,我们都会更新该设 备的 _Installation
表中的 updatedAt
时间戳。如果用户长期没有更新 _Installation
表的 updatedAt
时间戳,也就意味着该用户长期没有打开过应用。当超过 90 天没有打开过应用时,我们会将这个用户在 _Installation
表中的记录删除。不过请不要担心,当用户再次打开应用的时候,仍然会自动创建一个新的 Installation 用于推送。
对于 iOS 设备,除了上述过期机制外还多拥有一套过期机制。当我们根据 Apple 推送服务的反馈获取到某设备的 deviceToken 已过期时,我们也会将这个设备在 _Installation
表中的信息删除,并标记这个已过期的 deviceToken 为无效,丢弃后续所有发送到该 deviceToken 的消息。
API 接口一览
Path | Method | 描述 |
---|---|---|
/1.1/push | POST | 推送通知 |
/1.1/notifications | GET | 查询推送记录 |
/1.1/notifications/:notification_id | GET | 根据 ID 查推送记录 |
/1.1/notifications/:notification_id | DELETE | 根据 ID 删推送记录 |
/1.1/scheduledPushMessages | GET | 查询应用下所有的定时推送 |
/1.1/scheduledPushMessages/:id | DELETE | 根据 ID 删定时推送 |
master key 校验
当在开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 推送通知 > 设置中点选了 禁止从客户端进行消息推送 后, 必须通过 master key 才能发送推送,从而避免了客户端可以不经限制的给应用内任意目标设备推送消息的可能。 这一限制默认为启用状态。 我们建议用户都将此限制启用。
消息内容参数
iOS 设备推送消息内容参数
iOS 设备中 data 和 alert 内属性的具体含义请参考:
下面是对各属性的一些具体说明:
iOS 设备 data 各属性说明
名称 | 格式 | 约束 | 描述 |
---|---|---|---|
alert | 普通字符串或 JSON 字符串 | 必填 | 表 示消息内容。如果目标设备中只包含 iOS 设备则还可以是 JSON 类型,下面详述 JSON 类型时支持的属性, |
title | 字符串 | 可选 | 表示推送内容标题,如果 alert 字段为字符串可以在此补充提供 title,如果 alert 是 JSON 类型则无需再提供本字段, |
category | 字符串 | 可选 | 通知类型, |
thread-id | 字符串 | 可选 | 通知分类名称, |
badge | 数字 | 可选 | 未读消息数目,应用图标边上的小红点数字,可以是数字,也可以是字符串 "Increment"(大小写敏感), |
sound | 普通字符串或 JSON 字符串 | 可选 | 指定推送声音信息,下面详述 JSON 类型时支持的属性, |
content-available | 数字 | 可选 | 如果使用 Newsstand,设置为 1 来开始一次后台下载, |
mutable-content | 数字 | 可选 | 用于支持 UNNotificationServiceExtension 功能,设置为 1 时启用, |
collapse-id | 字符串 | 可选 | 对应 APNs request header 的 apns-collapse-id 参数,用于多条推送合并展示,具体请点击下面 Apple 官方关于 Request Header 的文档链接进行查阅, |
apns-priority | 数字 | 可选 | 只能是 10 或 5,对应 APNs request header 的 apns-priority 参数,用于控制是否以节电模式发推送,具体请点击下面 Apple 官方关于 Request Header 的文档链接进行查阅, |
apns-push-type | 字符串 | 可选 | 用于设置推送展示类型,在 iOS 13 或 watchOS 6 以上设备支持,只能为 "background" 或 "alert",默认为 "alert", |
url-args | 字符串 | 可选 | 列表类型,用于 Safari 推送,详情见 APNs 文档 关于 url-args 参数的描述, |
target-content-id | 字符串 | 可选 | 详情见 APNs 文档关于 target-content-id 参数的描述, |
自定义属性 | 自定义类型 | 可选 | 由用户添加的自定义属性,字段名和字段类型任意。 |
示例:
{
"alert": "hi"
}