本章將詳細介紹TUTK P2P SDK中KPNS（Kalay Push Notification Service）核心指令（注冊、綁定、解綁、同步）的參數(shù)規(guī)范、使用示例及錯誤碼說明，為手機端集成KPNS推送能力提供完整技術(shù)指引。
一、手機端注冊
客戶端注冊是讓用戶 APP 在 KPNS 服務(wù)器注冊的過程，未注冊則無法進行設(shè)備綁定，且需定期更新從消息中心獲取的 token，用戶無白名單限制。
參數(shù)說明
| 參數(shù)名稱 | 是否可選 | 說明 |
|---|---|---|
cmd | 必須 | 客戶端 APP 注冊指令，固定使用 client |
appid | 必須 | 發(fā)送到第三方推送服務(wù)器所需的憑證 ID，需預(yù)先在 KPNS 配置 |
udid | 必須 | 手機唯一識別 ID，可由 APP 開發(fā)人員自定義，不同手機間不可重復（由算法生成，建議與手機強關(guān)聯(lián)，即每個手機不管什么時候，這個udid都是唯一的，相同的），注冊成功后作為唯一識別 ID，無需每次變更 |
os | 必須 | 客戶端的消息推送系統(tǒng)，可選值：android、ios、qqxg、baidu、jiguang、oppo、huawei、mi、wechat |
token | 必須 | APP 端從第三方推送中心獲取，第三方推送依據(jù)此 token 發(fā)送到指定設(shè)備，token 有實效性，建議每次開啟 APP 時檢查token是否失效，如果失效，需獲取并更新KPNS服務(wù)器端記錄 |
lang | 必須 | 手機語系，默認值為 enUS，其他主要語系：zh_CN(簡體中文)，fr(法語)，德語(de)，日語(ja) |
dev | iOS 必須 | dev=1（開發(fā)用，往 iOS sandbox gateway 發(fā)送）；dev=0（正式用，往 iOS production gateway 發(fā)送），其他平臺可不填，默認 dev=0 |
bgfetch | 可選 | 支持 iOS 的 Silent push（content-available），允許 APP 在后臺運行時獲取 payload 相關(guān)信息，0 為關(guān)閉（默認），1 為開啟（建議通過 custom_payload 實現(xiàn)，不推薦直接使用此參數(shù)） |
Model | 可選 | 客戶端型號（詳細描述） |
Appver | 可選 | APP 版本（詳細描述） |
指令示例
/tpns?cmd=client&os={%os%}&appid={%APPID%}&udid={%UDID%}&token={%TOKEN%}&lang={%LANG%}&dev=0&bgfetch=0
錯誤信息
| 錯誤碼/信息 | 說明 |
|---|---|
| 210 Success, But No Data. | 執(zhí)行成功但無返回數(shù)據(jù) |
| 第三方回復“Fail” | 將顯示第三方推送服務(wù)器返回的對應(yīng)錯誤信息 |
二、手機綁定設(shè)備
APP 用戶與設(shè)備綁定的操作，一個用戶可綁定多個設(shè)備，一個設(shè)備也可綁定多個用戶（量產(chǎn)環(huán)境下設(shè)備最多綁定 100 個 client，通常建議不超過 5 個）。若綁定的設(shè)備 UID 不在 KPNS 白名單內(nèi)，綁定操作將失敗。
參數(shù)說明
| 參數(shù)名稱 | 是否可選 | 說明 |
|---|---|---|
cmd | 必須 | 綁定 UID 的指令，固定使用 mapping |
os | 必須 | 需與 Client 注冊時的 os 一致，否則無法送達目標手機 |
appid | 必須 | 需與 Client 注冊時的 appid 一致，否則無法送達目標 |
udid | 必須 | 需與 Client 注冊時的 udid 一致，否則無法送達目標 |
uid | 必須 | 需綁定的 UID 編號 |
interval | 可選 | 每封消息的間隔時間，服務(wù)器默認 120 秒 |
sound | 可選 | 推送聲音配置文件，默認值為 sound.alf |
format | 可選 | 自定義 alert 消息格式，需將格式字符串以 base64 編碼發(fā)送，中文內(nèi)容需以 utf8 編碼送出，由 APP 端接收后轉(zhuǎn)換為目標編碼 |
alias | 可選 | 自定義推送通知消息中顯示的設(shè)備名稱 |
customized_payload | 可選 | 自定義 payload，未提供時將使用默認值 |
customized_payload_default | 可選 | 自定義 payload 默認值，當 customized_payload 參數(shù)未賦值時生效 |
message_type | 可選 | 消息類型（僅針對中國推送平臺），可選 Notify（通知）或 message（透傳，默認值）；若服務(wù)商不支持透傳（如 OPPO），默認值為 Notify |
格式使用示例（門磁傳感器）
希望顯示的 alert 消息：“Warning: {dev_name} {event_type}”（其中 dev_name 和 event_type 為設(shè)備端傳入的變量）。
設(shè)備為開門偵測器，發(fā)生開門事件時，設(shè)備發(fā)送指令：cmd=event&uid={UID}&dev_name=Door Sensor&event_type=1。
對應(yīng)的 alert 內(nèi)容將顯示為：“Warning: Door Sensor Open Alarm”。
注意事項
注意
1. 發(fā)送的字符串及系統(tǒng)傳輸內(nèi)容需遵守第三方推送中心的長度限制。
2. Alias 變更后，需重新執(zhí)行 mapping 程序。
指令示例
/tpns?cmd=mapping&os={%os%}&appid={%APPID%}&uid={%UID%}&udid={%UDID%}&interval=120&sound={%SOUND%}&format={%alert format%}&alias=frontdoor
錯誤信息
| 錯誤碼/信息 | 說明 |
|---|---|
| 200 Success. | 執(zhí)行成功 |
| 210 Success, But No Data. | 執(zhí)行成功但無返回數(shù)據(jù) |
| 211 Waiting. | 請求處于等待處理狀態(tài) |
| 401 Unauthorized. | 未授權(quán)訪問（權(quán)限驗證失?。?/td> |
| 406 Parameter Error. | 參數(shù)錯誤（參數(shù)缺失/格式錯誤） |
三、手機解綁設(shè)備
解除設(shè)備與客戶端的綁定，解除后設(shè)備發(fā)送的所有消息將不再推送至該客戶端，此操作與白名單無關(guān)，即使設(shè)備已移除白名單仍可執(zhí)行。
參數(shù)說明
| 參數(shù)名稱 | 是否可選 | 說明 |
|---|---|---|
cmd | 必須 | 解除綁定的指令，固定使用 rm_mapping |
os | 必須 | 需與 Client 注冊時的 os 一致，否則無法順利解除 |
appid | 必須 | 需與 Client 注冊時的 appid 一致，否則無法順利解除 |
udid | 必須 | 需與 Client 注冊時的 udid 一致，否則無法順利解除 |
uid | 必須 | 需要解除綁定的 UID 編號 |
指令示例
/tpns?cmd=rm_mapping&os={%os%}&appid={%APPID%}&uid={%UID%}&udid={%UDID%}
錯誤信息
| 錯誤碼/信息 | 說明 |
|---|---|
| 210 Success, But No Data. | 執(zhí)行成功但無返回數(shù)據(jù) |
| 211 Waiting. | 請求處于等待處理狀態(tài) |
| 401 Unauthorized. | 未授權(quán)訪問（權(quán)限驗證失敗） |
| 406 Parameter Error. | 參數(shù)錯誤（參數(shù)缺失/格式錯誤） |
| 411 Mapping Error. | 綁定關(guān)系錯誤（無對應(yīng)綁定記錄） |
| 412 APPID Error. | APPID 配置錯誤/不存在 |
| 422 White Block. | 白名單限制（僅解除綁定場景無實際影響） |
| 520 Message Did Not Be Send. | 第三方推送服務(wù)器回復 Fail（消息發(fā)送失?。?/td> |
四、同步
用于解決因網(wǎng)絡(luò)問題導致的注冊或解除注冊指令未送達的問題，通過上傳用戶的 UID 列表更新綁定狀態(tài)，不比對 UID 是否在白名單內(nèi)（當前版本為提升存取效率，暫不包含白名單比對），可一次處理多個UID的綁定和解綁。
參數(shù)說明
| 參數(shù)名稱 | 是否可選 | 說明 |
|---|---|---|
cmd | 必須 | 綁定同步的指令，固定使用 mapsync |
appid | 必須 | 需與 Client 注冊時的 appid 一致，否則無法完成同步，需預(yù)先在 KPNS 配置 |
os | 必須 | 需與 Client 注冊時的 os 一致，否則無法完成同步 |
udid | 必須 | 需與 Client 注冊時的 udid 一致，否則無法完成同步，舊版無此參數(shù)時以 Token 代替 |
map | 必須 | base64 編碼后的 json 格式數(shù)據(jù)，核心同步內(nèi)容為綁定的 UID 列表（格式：[{"uid":"aaa"},{"uid":"bbb"},...]），也可包含 interval、sound 等 mapping 相關(guān)的其他參數(shù) |
指令示例
/tpns?cmd=mapsync&os={%os%}&appid={%APPID%}&udid={%UDID%}&map=base64(mapping list)
錯誤信息
| 錯誤碼/信息 | 說明 |
|---|---|
| 200 Success. | 執(zhí)行成功 |
| 210 Success, But No Data. | 執(zhí)行成功但無返回數(shù)據(jù) |
| 211 Waiting. | 請求處于等待處理狀態(tài) |
| 401 Unauthorized. | 未授權(quán)訪問（權(quán)限驗證失?。?/td> |
| 406 Parameter Error. | 參數(shù)錯誤（參數(shù)缺失/格式錯誤，如 map 解析失?。?/td> |
| 411 Mapping Error. | 綁定關(guān)系錯誤（同步的 UID 無有效記錄） |
| 412 APPID Error. | APPID 配置錯誤/不存在 |
| 422 White Block. | 白名單限制（當前版本已跳過白名單比對） |
| 520 Message Did Not Be Send. | 第三方推送服務(wù)器回復 Fail（同步指令發(fā)送失?。?/td> |
