跳转至

单推

先决条件

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

Note

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

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

URL

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

基本数据和请求变量

方法 POST
网址 /push/send
划分 字段名称 描述 类型 必需
头部 Content-Type application/json;charset=utf-8
授权 bearer {{API KEY}}
主体 notice

是否发送公告通知(默认:'false')

      true
    • 作为公告通知发送。
    • 根据用户协议发送通知。
      false
    • 作为游戏通知发送。
    • 无论用户协议如何发送通知。

公告和夜间通知是获取用户协议所需的项目。

  • 如果用户不同意接收公告通知,则所有设置为公告的通知都将被阻止发送。
  • 接收夜间通知的协议仅在同意接收公告通知后启用;除非所有设置为公告的通知在夜间被阻止发送。夜间时间为晚上9点到早上8点。

布尔值 O
identifiers 标识符信息(最多100个)请查看标识符结构和下面的示例 identifier[] O
游戏 gameid 游戏ID 字符串 O
appids

AppID列表如果映射的AppID无效,则不发送任何内容。

建议

  • 如果设备基础ID(did):添加映射的AppID。
  • 如果账户基础ID(playerId,vid,uid):添加整个映射的AppID列表。
  • 如果各种类型的ID:请参考标识符结构检查优先级。

字符串[] X
enableLocale

是否启用每种语言的区域设置

    true
  • 以目标用户设置的相同语言发送消息。基于令牌和设置的语言代码。
  • 在存储令牌时确定语言。
  • 优先级最高:游戏语言
  • 第二优先级:设备语言(除非发送游戏语言)
    false
  • 忽略语言区域设置,作为有效负载字段中的单一值发送。

布尔值 O
有效负载 single 如果enableLocale=false请求单个字段,请查看下面的消息结构 消息 O
defaultLanguage 如果enableLocale=true,则设置为默认语言的值。 字符串
locale {{LANGUAGE}} 如果enableLocale=true,则设置为区域字段的值,与单个字段的消息信息相同。 消息
option 请参考下面的可选信息 选项 X
Note
  • 为了适当接收单次推送,建议在appids和标识符字段中仅输入一个数据。
    • 由于无法指定搜索条件,如果请求包含多个标识符和appids,推送交付可能会延迟。
  • 建议为标识符值指定一个高优先级的值,并避免仅使用did值配置标识符。
  • 必须避免在游戏字段中仅指定gameid的请求。
    • 如果appids字段中没有信息,推送交付可能会延迟,因为所有包含在gameid中的appids都会被搜索。
  • 选项字段不适用于Facebook。

标识符结构

部门 字段名称 描述 类型 必需
标识符 标识符 playerId 应包含四个标识符中的一个,优先考虑playerId、vid、uid和did。 长整型
vid
uid
did

标识符示例

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

消息结构

iostitle标题字符串Ofacebook标题标题(在1~30个字母内)字符串O

部门 字段名称 描述 类型 必需
消息 android 标题 标题 字符串
消息 消息 字符串
扩展消息 扩展消息 字符串
图片网址 图片网址 字符串
滚动条 滚动条 字符串
摘要文本 摘要消息 字符串
消息 消息 字符串
媒体网址 图片路径 字符串
正文 正文(在10~180个字母内) 字符串
媒体 图片网址 字符串

选项信息

类别 字段名称 描述 类型 必需
选项 badge 收到推送通知时在应用图标上显示的数字值(默认:1) 整数 X
overwrite 是否在 Android 上使用推送覆盖功能(默认:false) 布尔值 X
collapseKey 启用推送覆盖功能时使用的键值(数字的字符串格式:“123”) 字符串 X
engagement 用户参与度 字符串 X
comment 文本 字符串 X
groupKey 这是用于在接收iOS和Android设备时将通知分组在一起的组键值。设备操作系统上设置的通知选项将默认应用。有关选项的更多详细信息,请参阅以下文档。 字符串 X
android 图标 当用户设备收到推送通知时显示的图标图像的文件名。图像文件必须存在于/src/main/res/drawable中。支持的图像文件格式可以在这里找到。 如果您想从网络上显示图像,请在此字段中输入图像的 URL,而不是文件名。如果此字段为空,将显示应用程序图标图像。 字符串 X
声音 当用户设备收到推送通知时播放的通知声音的文件名。您可以指定包含在应用程序包中的声音文件,并且声音文件必须存在于/src/main/res/raw中。如果此字段为空,将使用系统默认声音。 字符串 X
优先级 发送到 Android 设备的消息的优先级。此优先级控制消息传递的时机,这是 FCM 的一个概念。它可以具有 NORMAL 或 HIGH 的值,默认值为 NORMAL。有关更多详细信息,请参阅Firebase 指南
  • NORMAL = 数据消息的默认优先级。通常优先的消息在设备不处于睡眠模式时会立即发送。当设备处于睡眠模式时,为了节省电池,交付可能会延迟,直到设备退出睡眠模式。对于不敏感的消息,例如新电子邮件通知、保持 UI 同步和后台应用程序数据同步,选择正常交付优先级。
  • HIGH = FCM 尝试立即发送高优先级消息,并在必要时可能唤醒设备以执行有限的处理任务,包括非常有限的网络访问。高优先级消息通常涉及用户与应用程序的交互或通知。
enum(NORMAL, HIGH) X
ios sound 当用户的设备收到推送通知时将播放的通知声音的文件名。声音文件必须存在于应用程序容器的 Library/Sounds 或主应用程序包中。如果此字段为空,将自动设置为“default”,使用用户 Apple 设备上的 系统默认声音 String X

输出结果

部门 字段名称 描述
头部 内容类型 application/json;charset=utf-8
UUID {{UUID}}
正文 - 如果成功,正文为空

响应状态代码

描述
200 成功 (主体为空。)
400 错误请求 POST 数据被省略。JSON 格式错误。缺少或无效的必需元素。
401 未授权 请求消息中的授权头被省略或无效。授权密钥(API KEY)未注册。没有访问相关 API 的权限。
403 禁止 授权头的身份验证方案不是 "Bearer"。(仅支持 Bearer)
404 未找到 请求的 URL 错误。
500 服务器内部错误 服务器内部错误
502 错误网关 推送网关服务器超载。网络连接错误。
503 服务不可用 API 服务器或身份验证服务器已冻结。

示例代码

  • 调用 ("enableLocale":false)

    curl -L -v
    > -d '{"notice":false,"identifiers":[{"vid":19239,"did":300010915}],"game":{"gameid":"com.com2us.hivesdk","appids":["com.com2us.hivesdk.normal.freefull.google.global.android.common"]},"enableLocale":false,"payload":{"single":{"android":{"title":"TEST","message":"TEST","messageExpanded":"","imageUrl":"","ticker":"","summaryText":""},"ios":{"title":"","message":"","mediaUrl":""},"facebook":{"title":"TEST", "body":"TEST MESSAGE BODY", "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"}},"option":{"badge":"1","overwrite":false,"collapseKey":"","engagement":"","groupKey": "", "android":{"icon":"","sound":"", "priority": "normal"},"ios":{"sound":""}}}}'
    > -d '{"notice":false,"identifiers":[{"vid":19239,"did":300010915}],"game":{"gameid":"com.com2us.hivesdk","appids":["com.com2us.hivesdk.normal.freefull.google.global.android.common"]},"enableLocale":false,"payload":{"single":{"android":{"title":"TEST","message":"TEST","messageExpanded":"","imageUrl":"","ticker":"","summaryText":""},"ios":{"title":"","message":"","mediaUrl":""},"facebook":{"title":"TEST", "body":"TEST MESSAGE BODY", "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"}},"option":{"badge":"1","overwrite":false,"collapseKey":"","engagement":"","groupKey": "", "android":{"icon":"","sound":"", "priority": "normal"},"ios":{"sound":""}}}}'
    > -H "Content-Type: application/json"
    > -H "Authorization: Bearer {API KEY}"
    > https://sandbox-notification.qpyou.cn/push/send
    
  • 调用 ("enableLocale":true)

    {
        "notice": false,
        "identifiers": [
            {
                "playerId": 30000028045
    }
    ],
        "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": "test_Korean_title",
                        "message": "test_Korean_message"
                    },
                    "ios": {
                        "title": "test_Korean_title",
                        "message": "test_Korean_message"
                    },
                    "facebook": {
                        "title": "test_Korean_title",
                        "body": "test_Korean_message",
                        "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"
                    }
                },
                "en": {
                    "android": {
                        "title": "test_English title",
                        "message": "test_English message"
                    },
                    "ios": {
                        "title": "test_English title",
                        "message": "test_English message"
                    },
                    "facebook": {
                        "title": "test_English title",
                        "body": "test_English message",
                        "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"
                    }
                }
            },
            "option": {
                "badge": 1,
                "overwrite": true,
                "collapseKey": "99",
                "groupKey: "",
                "android": {
                    "icon": "GoogleIcon",
                    "sound": "GoogleSound",
                    "priority": "normal"
                },
                "ios": {
                    "sound": "AppleSound"
                }
            }
        }
    }
    
Note

建议**连续发送呼叫数据,不留任何空格**以便服务器立即检查日志。

  • 请求
> POST /push/send HTTP/1.1
> User-Agent: curl/7.29.0
> Host: sandbox-notification.qpyou.cn
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1NDE1NzMyOTcsImp0aSI6ImFkbWluaXN0cmF0b3IifQ.23nG9RnbuOwnMbRSebBi2i-Qt_fOfqU_vUKUZ2JJlWU
> Content-Length: 502
  • 响应
< HTTP/1.1 200 OK
< content-length: 0
< Content-Type: application/json
< UUID: 3bc6b414-e2df-40d6-8006-9d2308a6edf9