API
注意
该门户网站正在开发中。文档的完整版本请看这里.
此API旨在提供通过多个推送提供商同时通过主题发送通知的能力。
要发送推送通知,需要使用POST方法 https://vkpns-universal.rustore.ru/v1/send/topic
。
要向主题发送推送通知,请为计划发送推送的每个提供商指定"项目ID"和"授权令牌"。
RuStore
使用project_id(项目ID)和ss_token(服务令牌)。您可以在RuStore控制台系统中获取这些值。为此,请在应用程序页面转到"Push通知"部分并选择"项目"。发送推送通知
FCM
您可以在RuStore控制台系统中获取这些值。获取令牌的示例在FCM文档中有描述。
- https://firebase.google.com/docs/cloud-messaging/migrate-v1#use-credentials-to-mint-access-tokens
- https://firebase.google.com/docs/cloud-messaging/auth-server
uStore不存储"项目ID"和"授权令牌"。请自行验证令牌。
HMS
您可以在RuStore控制台系统中获取这些值。获取"授权令牌"的示例在文档中有说明。"项目ID"可以在开发者控制台中获取,不要与"应用程序ID"混淆,文档中有相关描述。
RuStore不存储"项目ID"和"授权令牌"。请自行验证令牌。
请求正文
参数 | 类型 | 必须的 | 描述 |
---|---|---|---|
providers | object (providers) | 是 | 用于发送push通知的提供商 |
topic | string | 是 | 主题名称 |
message | object (message) | 是 | Push通知的结构 |
providers
参数 | 类型 | 必须的 | 描述 |
---|---|---|---|
rustore | object (provider) | 否 | RuStore 提供商 |
fcm | object (provider) | 否 | 提供商Firebase |
hms | object (provider) | 否 | 提供商Huawei |
providers.provider
参数 | 类型 | 必须的 | 描述 |
---|---|---|---|
project_id | string | 是 | ID项目 |
auth_token | string | 是 | 授权令牌 |
message
参数 | 类型 | 必须的 | 描述 |
---|---|---|---|
data | map | 否 | 包含" key": value 对的对象value |
notification | object (message.notification) | 是 | 适用于所有平台的基本通知模板 |
android | object (message.android) | *否 | Android 消息的特殊参数 |
**在 hms 中是必须的
message.notification
参数 | 类型 | 必须的 | 描述 |
---|---|---|---|
title | string | 是 | 通知标题 |
body | string | 是 | 通知的主要文本 |
image | string | 否 | 包含将在通知中显示的图片的 URL 地址 |
message.android
参数 | 类型 | 必须的 | 描述 |
---|---|---|---|
ttl | string (duration format) | 否 | 消息在存储中保留的时间(以秒为单位)。例如:"3.5s" |
notification | object (message.android.notification) | *否 | 用于发送到 Android 设备的通知Android |
在 hms 中是必须的
message.android.notification
参数 | 类型 | 必须的 | 描述 |
---|---|---|---|
title | string | 是 | 通知标题 |
body | string | 是 | 通知的主要文本 |
icon | string | 否 | 通知图标 |
color | string | 否 | 通知图标的颜色,格式为 #rrggbb |
image | string | 否 | 包含将在通知中显示的图片的 URL 地址 |
channel_id | string | 否 | 通知渠道的标识符 |
*click_action | string | 否 | 用户点击通知时关联的动作 |
在 hms 中默认为类型 1 (intent)。
在 message 结 构体中,仅支持上述字段。
成功响应的正文
参数 | 类型 | 描述 |
---|---|---|
status | string | 在成功响应的情况下返回带有"OK"状态的消息 |
错误正文
参数 | 类型 | 描述 |
---|---|---|
code | int | 数字错误代码 (404, 400, 403, 401, ...) |
status | string | 错误的一般描述 |
errors | array (string) | 按提供商分类的错误或验证错误 |
TTPstatus对应于字段 code。
错误分为三种类型
- 消息验证错误。
- 按提供商发送的错误。
- 服务错误。
发送消息时可能出现的错误
VALIDATION_ERROR
- 当发送消息时,请求参数指定不正确。PROVIDER_ERROR
- 向推送提供商发送时出错。INTERNAL_ERROR
- 服务的内部错误。
发送消息时可能的验证错误
providers.%provider_name%
- 提供商中的错误。message.%field%
- 消息中的错误。
发送消息时可能的提供商错误,格式为 %provider_name%:%error%
internal
- 提供商的内部错误。validationerror
- 提供商端的验证错误。invalidauthtoken
- auth 令牌错误。toomanyrequests
- 请求过多。
验证算法
提供商必须有令牌。
Providers
- 必须至少有一个提供商,没有提供商请求是无效的。
Message
- 如果payload的message.data不为空(内部至少有一个键值对),那么该消息是有效的。message.notification和message.android部分可以不包含。
- 如果message. data字段不存在,则必须有notification。在这种情况下,将检查 message.notification 或 message.android.notification 字段的存在。这些字段中至少有一个必须存在,但两个都可以存在(如果两者都存在,某些字段将被覆盖)。
限制
- 如果推送中没有ttl字段或其值为0,则考虑默认值为4周。如果推送中缺少message.android部分,则会添加该部分并包含ttl字段。
- 消息的最大容量为4096 字节。
通用推送通知通过主题发送的示例
成功请求的示例
POST https: //vkpns-universal.rustore.ru/v1/send HTTP/2
Content-Type: application/json
{
"providers":{
"rustore": {
"auth_token": "AAAbbbCC123" ,
"project_id": "aabbcc"
},
"fcm": {
"auth_token": "321CCbbAAA" ,
"project_id": "ccbbaa"
}
},
"tokens": {
"rustore":["bk3RNwTe3H"],
"fcm":["CI2k_HHwgIpoDKC"]
},
"message":{
"notification":{
"body": "This is a notification message!" ,
"title": "Message"
}
}
}
HTTP/2 200
Content-Type: application/json
{
"Status": "OK"
}
无效提供商的示例
POST https: //vkpns-universal.rustore.ru/v1/send HTTP/2
Content-Type: application/json
{
"providers":{
"rustore": {
"auth_token": "AAAbbbCC123" ,
"project_id": "aabbcc"
},
"fcm": {
}
},
"tokens": {
"rustore":["bk3RNwTe3H"],
"fcm":["CI2k_HHwgIpoDKC"]
},
"message":{
"notification":{
"body": "This is a notification message!" ,
"title": "Message"
}
}
}
HTTP/2 400
Content-Type: application/json
{
"status": "VALIDATION_ERROR" ,
"code": 400,
"errors": [
"providers.fcm: project_id is a required field" ,
"providers.fcm: auth_token is a required field"
]
}
无效消息的示例
POST https: //vkpns-universal.rustore.ru/v1/send HTTP/2
Content-Type: application/json
{
"providers":{
"rustore": {
"auth_token": "AAAbbbCC123" ,
"project_id": "aabbcc"
},
"fcm": {
"auth_token": "321CCbbAAA" ,
"project_id": "ccbbaa"
}
},
"tokens": {
"rustore":["bk3RNwTe3H"],
"fcm":["CI2k_HHwgIpoDKC"]
},
"message":{
"notification":{
}
}
}
HTTP/2 400
Content-Type: application/json
{
"status": "VALIDATION_ERROR" ,
"code": 400,
"errors": [
"message.notification: title is a required field" ,
"message.notification: body is a required field"
]
}
提供商错误的示例
POST https: //vkpns-universal.rustore.ru/v1/send HTTP/2
Content-Type: application/json
{
"providers":{
"rustore": {
"auth_token": "AAAbbbCC123" ,
"project_id": "aabbcc"
},
"fcm": {
"auth_token": "321CCbbAAA" ,
"project_id": "ccbbaa"
}
},
"tokens": {
"rustore":["bk3RNwTe3H"],
"fcm":["CI2k_HHwgIpoDKC"]
},
"message":{
"data":{ "test": "test" }
}
}
HTTP/2 400
Content-Type: application/json
{
"status": "PROVIDER_ERROR" ,
"code": 400,
"errors": [
"fcm: invalid auth token"
]
}