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