单次推送
前提條件¶
要與單一推送 API 同步,請確保發出授權令牌(API KEY)。如果您已經擁有該密鑰,請請求額外的權限。請參考 Hive 伺服器 API > 通知 > 推送 v4 > 認證 以查看如何請求和發出授權令牌。
Note
單一 Puch API 是非同步的,並按順序處理,API 請求 > 令牌查找 > 發送。
- API 請求:驗證請求數據並返回請求的響應代碼。
- 令牌查找:查找請求數據的推送令牌。可能會出現沒有令牌的情況。
- 發送:將數據傳輸到每個市場的推送伺服器(例如 ADM、APNS、FCM 和 Facebook)。從市場收到的響應顯示處理結果。
- 當在令牌查找和發送步驟中處理失敗時,不會將響應傳輸給調用推送伺服器的客戶端。 如果您在發送數據後 10 分鐘內未收到推送,請聯繫 解決方案架構師團隊,Com2uS 平台。
網址¶
伺服器 | 網址 |
---|---|
生產 | 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 公告和夜間通知是獲得用戶協議所需的項目。
| 布林值 | O | |
identifiers | 標識符信息(最多100個)查看標識符結構和下面的示例。 | identifier[] | O | ||
遊戲 | gameid | 遊戲ID | 字串 | O | |
appids | AppID列表如果映射的AppID無效,則不會發送任何內容。 建議
| String[] | X | ||
enableLocale | 是否啟用每種語言的區域設置
true
false | 布林值 | O | ||
有效負載 | single | 如果enableLocale=false 請求單一欄位,查看下面的消息結構。 | 消息 | O | |
defaultLanguage | 如果enableLocale=true ,則設置為默認語言的值。 | 字串 | |||
locale {{LANGUAGE}} | 如果enableLocale=true ,則設置為區域欄位的值,與單一欄位的消息信息相同。 | 消息 | |||
option | 參考下面的可選信息。 | 選項 | X |
Note
- 為了適當的單次推送接收,建議在 appids 和 identifiers 欄位中僅輸入一個數據。
- 由於無法指定搜索條件,如果請求包含多個 identifiers 和 appids,推送交付可能會延遲。
- 建議為 identifier 值指定一個高優先級的值,並避免僅使用 did 值來配置 identifier。
- 必須避免在遊戲欄位中僅指定 gameid 的請求。
- 如果 appids 欄位中沒有信息,則推送交付可能會延遲,因為所有包含在 gameid 中的 appids 都會被搜索。
- 選項欄位不適用於 Facebook。
識別符結構¶
區域 | 欄位名稱 | 描述 | 類型 | 必要 | |
---|---|---|---|---|---|
識別碼 | 識別碼 | playerId | 應包含四個識別碼中的一個,優先順序為 playerId、vid、uid 和 did。 | 長整數 | O |
vid | |||||
uid | |||||
did |
識別碼範例¶
訊息結構¶
iostitleTitleStringOfacebooktitleTitle(在1~30個字母內)StringO
部門 | 字段名稱 | 描述 | 類型 | 必需 | |
---|---|---|---|---|---|
訊息 | android | 標題 | 標題 | 字符串 | O |
訊息 | 訊息 | 字符串 | O | ||
擴展訊息 | 擴展訊息 | 字符串 | O | ||
圖片網址 | 圖片網址 | 字符串 | X | ||
滾動條 | 滾動條 | 字符串 | X | ||
摘要文本 | 摘要訊息 | 字符串 | X | ||
訊息 | 訊息 | 字符串 | O | ||
媒體網址 | 圖片路徑 | 字符串 | X | ||
主體 | 主體(在10~180個字母內) | 字符串 | O | ||
媒體 | 圖片網址 | 字符串 | O |
選項資訊¶
類別 | 欄位名稱 | 描述 | 類型 | 必填 | |
---|---|---|---|---|---|
選項 | badge | 當收到推播通知時,在應用程式圖示上顯示的數值(預設:1) | 整數 | X | |
overwrite | 是否在 Android 上使用推播覆蓋功能(預設:false) | 布林值 | X | ||
collapseKey | 當啟用推播覆蓋功能時使用的鍵值(數字的字串格式:"123") | 字串 | X | ||
engagement | 用戶參與度 | 字串 | X | ||
comment | 文字 | 字串 | X | ||
groupKey | 這是用於在 iOS 和 Android 設備上接收通知時將通知分組在一起的組鍵值。設備操作系統上設置的通知選項將默認應用。欲了解有關選項的更多詳細信息,請參閱以下文檔。 | String | X | ||
android | 圖示 | 當用戶的設備收到推播通知時顯示的圖示影像的檔案名稱。圖像檔案必須存在於/src/main/res/drawable中。支援的圖像檔案格式可以在這裡找到。 如果您想從網路顯示圖像,請在此欄位中輸入圖像的URL,而不是檔案名稱。如果此欄位為空,則會顯示應用程式圖示影像。 | 字串 | X | |
聲音 | 當用戶的設備收到推播通知時將播放的通知聲音的檔案名稱。您可以指定包含在應用程式包中的聲音檔案,該聲音檔案必須存在於/src/main/res/raw中。如果此欄位為空,則將使用系統預設聲音。 | 字串 | X | ||
優先級 | 發送到Android設備的消息的優先級。此優先級控制消息傳遞的時機,這是FCM的一個概念。它可以具有NORMAL或HIGH的值,預設為NORMAL。更多詳細資訊,請參考Firebase指南。
| 枚举(NORMAL, HIGH) | X | ||
ios | 声音 | 当用户的设备收到推送通知时,将播放的通知声音的文件名。声音文件必须存在于应用程序容器的 Library/Sounds 或主应用程序包中。如果此字段为空,将自动设置为“默认”,使用用户 Apple 设备上的 系统默认声音。 | 字符串 | 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":"測試","message":"測試","messageExpanded":"","imageUrl":"","ticker":"","summaryText":""},"ios":{"title":"","message":"","mediaUrl":""},"facebook":{"title":"測試", "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":"測試","message":"測試","messageExpanded":"","imageUrl":"","ticker":"","summaryText":""},"ios":{"title":"","message":"","mediaUrl":""},"facebook":{"title":"測試", "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
- 回應