跳转至

单推

先决条件

要与单推送 API 同步，请确保发出授权令牌（API 密钥）。如果您已经拥有密钥，请请求额外的权限。请参考 Hive 服务器 API > 通知 > 推送 v4 > 身份验证 以查看如何请求和发出授权令牌。

Note

单次 Puch API 是异步的，并按顺序处理，API 请求 > 令牌查找 > 发送。

  • API请求：验证请求数据并返回请求的响应代码。
  • 令牌查找：查找请求数据的推送令牌。可能会出现没有令牌的情况。
  • 发送：将数据传输到各个市场的推送服务器（如ADM、APNS、FCM）。从市场收到的响应显示处理结果。
  • 当在令牌查找和发送步骤中处理失败时，不会将响应传输给调用推送服务器的客户端。如果您在发送数据后10分钟内没有收到推送，请联系**解决方案架构师团队，Com2uS平台**。

按环境访问 URL

服务器 URL
生产环境 https://notification.withhive.com
沙盒 https://sandbox-notification.withhive.com

基本信息和请求参数

方法 POST
URL /push/send
部分 字段名称 描述 类型 必填
头部 Content-Type application/json;charset=utf-8
Authorization bearer {{API KEY}}
正文 notice 是否为通知警报（默认：false）。
• true：作为通知警报发送。
不会发送给未同意接收通知的收件人。如果在夜间（21:00~08:00）发送，则需要额外的夜间同意。有关详细信息，请参见通知警报工作流程。
• false：作为游戏警报发送（必需的操作警报）。无论是否同意接收通知，都会发送。
※ 如果在设备/操作系统级别阻止通知，则可能无法送达警报，无论通知设置如何。		 布尔值 O
identifiers 标识符信息（最多100个） 标识符结构 和 示例 可以在下面找到 identifier[] O
game gameid 游戏ID 字符串 O
appids AppID 列表
如果映射到标识符的 AppID 无效，则不会发送

建议

  • 对于基于设备的标识符（did）：添加映射的 AppID
  • 对于基于账户的标识符（playerId）：添加所有映射的 AppIDs
  • 如果存在多种标识符：检查 标识符 结构中的优先级
字符串[] X
enableLocale 是否应用语言区域

    true

  • 以推送接收者设置的语言发送消息。基于与令牌信息保存的语言代码
  • 保存令牌时确定语言的标准
  • 第1: 游戏语言
  • 第2: 设备语言（如果没有提供游戏语言）

    • false

  • 忽略语言区域，仅通过有效负载中的单一值发送
布尔值 O
payload single 如果 enableLocale=false，请求单个字段。 消息结构 如下。 消息 O
defaultLanguage 如果 enableLocale=true，设置为默认语言 字符串
locale {{LANGUAGE}} 如果 enableLocale=true，通过区域字段设置。与单个字段中的消息信息相同 消息
option 选项信息 如下 选项 X
actionInfo android ActionPayload 信息 如下 ActionPayload X
ios ActionPayload 信息 如下 ActionPayload X

通知警报工作流程

通知警报仅发送给已同意接收的游戏应用用户。如果通知警报在 21:00~08:00 之间发送，则需要额外的夜间警报同意。

通知警报工作流的详细信息如下：

  • 如果用户不同意接收通知提醒，则所有设置为通知的消息将不会发送。
  • 只有同意接收通知提醒的用户才能同意夜间提醒。
Warning

向韩国用户的广告通知警报的规定

当向韩国用户发送通知警报时，这些警报被视为广告警报，必须遵守《信息与通信网络法》第50条。广告警报消息必须包含表明这是广告的短语以及退出的说明。

  • 广告提醒消息示例: (广告) {message_body} (选择退出: 在设置中更改)
Note
  • 为了顺利接收单次推送，建议在appids和identifiers字段中仅输入一个数据项。
  • 如果请求中包含多个identifiers或appids，可能会导致推送延迟，因为无法指定搜索条件。
  • 建议指定优先级最高的标识符值，并避免仅配置具有did值的标识符。
  • 避免在游戏字段中仅指定gameid的请求。
  • 如果appids字段中没有数据，将搜索gameid中包含的所有appids，这可能会导致推送延迟。

标识符结构

部门 字段名称 描述 类型 必需
identifier identifier 至少必须包含两个中的一个
优先级：playerId，然后是did		 长整型 O
playerId
did

标识符示例

    [
        {
            "playerId":51234,
            "did":1234
        }
    ]

消息结构

部门 字段名称 描述 类型 是否必需
消息 android title 标题 字符串 是
message 正文 字符串 是
messageExpanded 扩展正文 字符串 是
imageUrl 图片 URL 字符串 否
ticker 票据 字符串 否
summaryText 摘要 字符串 否
ios title 标题 字符串 是
message 正文 字符串 是
mediaUrl 图片 URL 字符串 否

选项信息

部分 字段名称 描述 类型 必需
选项 徽章 接收推送时在应用图标上显示的数字（默认：1） 整数 X
覆盖 是否使用Android推送覆盖功能（默认：false） 布尔值 X
collapseKey 使用推送覆盖时的键值（数字字符串：“123”） 字符串 X
参与度 用户参与度 字符串 X
评论 评论 字符串 X
组键 用于在iOS和Android设备上分组通知的组键。有关更多详细信息，请参阅以下文档。 字符串 X
安卓 图标 当推送通知出现在用户设备上时显示的图标图像文件名。图像文件必须存在于/src/main/res/drawable中。有关支持的图像文件格式，请参见这里。 要从网络显示图像，请在此字段中输入图像URL，而不是文件名。如果此字段为空，将显示应用图标图像。 字符串 X
声音 当推送通知出现在用户设备上时播放的声音文件名称。声音文件必须存在于/src/main/res/raw中。如果此字段为空，则使用系统默认声音。 字符串 X
优先级 发送到Android设备的消息优先级。这控制根据FCM的交付时机。可以是NORMAL或HIGH，默认是NORMAL。有关更多详细信息，请参见Firebase指南。
  • NORMAL = 数据消息的默认优先级。当设备不处于待机模式时，通常会立即交付。如果设备处于睡眠状态，可能会延迟以节省电池。用于时间不关键的消息。
  • HIGH = FCM尝试立即交付，可能会唤醒设备以退出待机模式。用于需要用户交互的消息。
 枚举(NORMAL, HIGH) X
ios 声音 当推送通知出现在用户设备上时播放的声音文件名称。声音文件必须存在于应用容器的Library/Sounds或主包中。如果为空，则使用“默认”，并播放系统默认声音。 字符串 X

ActionPayload

ActionPayload 是在使用推送操作按钮时传递的数据格式，这是单一推送 API 的一个附加功能。

推送操作按钮是SDK中可用的通知功能，在长按推送通知时显示为系统按钮。

有关推送操作按钮的更多详细信息，请参阅以下指南。

Warning

请注意使用推送操作按钮时的以下事项：

  • 仅在 SDK Android 和 iOS 4.25.5.0 或更高版本上可用。
  • identifiers 字段中仅一个 identifier 是有效的，并且 playerId 是必需的。
  • 开发者负责通过推送操作按钮调用的 URL 的安全验证。

ActionPayload 数据结构

在请求单个推送 API 时，ActionPayload 中包含的数据如下。

字段名称 描述 类型 必需
category 推送操作按钮集的类别标识符，用于识别该集合。Hive SDK 提供了默认的推送操作按钮集。 查看默认推送操作按钮集
有关类别的更多详细信息，请参见 Apple 开发者网站。
iOS: 必需，Android: 可选且被忽略		 字符串 O iOS
X Android
actions 在推送通知中显示的系统按钮列表
(Android: 最多 3 个 / iOS: 取决于推送操作按钮集)
请参见下面的 操作信息		 Action[] O

动作

操作是 ActionPayload 中每个系统按钮的数据。Action 中包含的参数如下。

字段名称 描述 类型 必填
actionId 操作标识符，用于推送操作按钮集，用于识别推送通知中的系统按钮。
有关更多详细信息，请参见Apple开发者指南。
iOS: 必填，Android: 可选且被忽略		 字符串 O iOS
X Android
titles 按钮多语言文本，根据enableLocale参数应用。如果未找到有效的语言代码，则使用default。
key = 语言代码，default键是必需的，值 = 按钮名称
如果按钮名称过长，可能会被截断。请设置适当的长度。
仅限Android		 Map O Android
X iOS
actionType 操作类型（CURL，CLOSE），默认值：CLOSE
CURL使用action字段的值执行URL调用。
CLOSE关闭推送。		 enum(CURL, CLOSE) O
action 根据操作类型执行的操作
例如，https://....
如果actionType为CURL，则必填。		 字符串 X

输出 > 响应参数结构

部分 字段名称 描述
头部 内容类型 application/json;charset=utf-8
UUID {{UUID}}
主体 - 如果成功则为空

响应状态代码

键 值 描述
200 成功 （主体为空）
400 错误请求 缺少POST数据，JSON格式错误，缺少或无效的必需元素
401 未授权 授权头缺失或无效，API密钥未注册，无法访问此API
403 禁止 授权头方案不是“Bearer”（仅支持Bearer）
404 未找到 请求URL不正确
500 内部服务器错误 服务器内部错误
502 错误网关 推送网关服务器超载，网络尝试了错误的连接
503 服务不可用 API服务器或认证服务器宕机

示例代码

  • 请求 ("enableLocale":false) 

      POST /push/send HTTP/1.1
    Host: sandbox-notification.qpyou.cn
    Content-Type: application/json
    Authorization: Bearer {API KEY}
    Content-Length: [auto calculated]

  {
      "notice": false,
      "identifiers": [
          {
              "playerId": 200001358,
              "did": 300010915
          }
      ],
      "game": {
          "gameid": "com.com2us.hivesdk",
          "appids": [
              "com.com2us.hivesdk.normal.freefull.google.global.android.common",
              "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal"
          ]
      },
      "enableLocale": false,
      "payload": {
          "single": {
              "android": {
                  "title": "安卓标题",
                  "message": "安卓消息",
                  "messageExpanded": "",
                  "imageUrl": "",
                  "ticker": "",
                  "summaryText": ""
              },
              "ios": {
                  "title": "iOS标题",
                  "message": "iOS消息",
                  "mediaUrl": ""
              }
          },
          "option": {
              "badge": "1",
              "overwrite": false,
              "collapseKey": "",
              "engagement": "",
              "groupKey": "",
              "android": {
                  "icon": "",
                  "sound": "",
                  "priority": "normal"
              },
              "ios": {
                  "sound": ""
              }
          }
      },
      "actionInfo": {
          "android": {
              "actions": [
                  {
                      "titles": {
                          "default": "确定"
                      },
                      "actionType": "CURL",
                      "action": "https://examplecurl.com"
                  },
                  {
                      "titles": {
                          "default": "取消"
                      },
                      "actionType": "CLOSE",
                      "action": ""
                  }
              ]
          },
          "ios": {
              "category": "确认类别",
              "actions": [
                  {
                      "actionId": "CONFIRM_ID",
                      "actionType": "CURL",
                      "action": "https://examplecurl.com"
                  },
                  {
                      "actionId": "CLOSE_ID",
                      "actionType": "CLOSE",
                      "action": ""
                  }
              ]
          }
      }
  }

  • 请求 ("enableLocale":true) 

    POST /push/send HTTP/1.1
Host: sandbox-notification.qpyou.cn
Content-Type: application/json
Authorization: Bearer {API KEY}
Content-Length: [auto calculated]

{
    "notice": false,
    "identifiers": [
        {
            "playerId": 200001358,
            "did": 300010915
        }
    ],
    "game": {
        "gameid": "com.com2us.hivesdk",
        "appids": [
            "com.com2us.hivesdk.normal.freefull.google.global.android.common",
            "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal"
        ]
    },
    "enableLocale": true,
    "payload": {
        "defaultLanguage": "en",
        "locale": {
            "ko": {
                "android": {
                    "title": "测试_韩语标题",
                    "message": "测试_韩语消息"
                },
                "ios": {
                    "title": "测试_韩语标题",
                    "message": "测试_韩语消息"
                }
            },
            "en": {
                "android": {
                    "title": "test_English title",
                    "message": "test_English message"
                },
                "ios": {
                    "title": "test_English title",
                    "message": "test_English message"
                }
            }
        },
        "option": {
            "badge": 1,
            "overwrite": true,
            "collapseKey": "99",
            "groupKey": "",
            "android": {
                "icon": "GoogleIcon",
                "sound": "GoogleSound",
                "priority": "normal"
            },
            "ios": {
                "sound": "AppleSound"
            }
        }
    },
    "actionInfo": {
        "android": {
            "actions": [
                {
                    "titles": {
                        "default": "确定",
                        "en": "OK",
                        "ko": "확인"
                    },
                    "actionType": "CURL",
                    "action": "https://examplecurl.com"
                },
                {
                    "titles": {
                        "default": "取消",
                        "en": "Cancel",
                        "ko": "취소"
                    },
                    "actionType": "CLOSE",
                    "action": ""
                }
            ]
        },
        "ios": {
            "category": "CONFIRM_CATEGORY",
            "actions": [
                {
                    "actionId": "CONFIRM_ID",
                    "actionType": "CURL",
                    "action": "https://examplecurl.com"
                },
                {
                    "actionId": "CLOSE_ID",
                    "actionType": "CLOSE",
                    "action": ""
                }
            ]
        }
    }
}

Note

建议将请求数据以单行发送，不要有换行，以便可以立即检查服务器日志。

  • 响应 
    HTTP/1.1 200 OK
Content-length: 0
Content-Type: application/json
UUID: 3bc6b414-e2df-40d6-8006-9d2308a6edf9