高效率完成一次接入80個手游渠道SDK——游戲接入SDK服務(wù)端篇

.1 概要
    通常，游戲開發(fā)商并不會只在一個渠道上線他們的游戲，接入越多的渠道，代表著可能獲取越多的用戶，但同時也代表著越多的接入SDK工作量、工期和費用。一款游戲要有足夠的用戶，甚至需要接入30家以上的各種渠道，以保障自己的市場覆蓋率。

單個SDK接入流程在一位有經(jīng)驗的全職客戶端程序、一位全職服務(wù)端程序員、一位全職QA處理的情況下，需要3天時間才能完成。因此當(dāng)一款產(chǎn)品面對30個甚至更多不同需求的渠道SDK時，人員成本和時間成本就會急劇增加。所以我們需要一個通用接口，來處理各種渠道的需求，這就是統(tǒng)一渠道SDK接入框架。 本部分主要提供平臺SDK服務(wù)器與CP方游戲服務(wù)器交互的接口規(guī)范

1.2   支付基本流程

1.2.1 渠道支付流程

游戲客戶端在每次用戶點擊購買時向服務(wù)端請求生成內(nèi)部訂單。并需要采用特定機制（例如一定時間內(nèi)禁止連續(xù)點擊購買）防止用戶頻繁操作對服務(wù)器造成過高負載。

游戲服務(wù)端生成的所有內(nèi)部訂單需要存儲待查。并在得到渠道返回的外部訂單后異步處理發(fā)貨操作并以特定機制通知客戶端更新數(shù)據(jù)顯示。

渠道支付接口負責(zé)完成貨幣交易操作，生成并存儲外部訂單，供對賬查詢使用。

       SDK服務(wù)端轉(zhuǎn)發(fā)請求時額外存儲一份訂單日志數(shù)據(jù)，存儲內(nèi)部訂單號，外部訂單號及訂單狀態(tài)，供對賬及查找BUG時作為參考。

1.2.2 一般渠道支付流程圖

1.3 協(xié)議說明

1.3.1 通信協(xié)議

       SDK服務(wù)器采用HTTP協(xié)議作為通信協(xié)議，游戲服務(wù)器通過構(gòu)造HTTP請求（POST方式）向SDK服務(wù)器發(fā)起接口請求。

1.3.2 數(shù)據(jù)協(xié)議

1.數(shù)據(jù)格式

       請求消息和響應(yīng)消息的內(nèi)容都使用JSON表示數(shù)據(jù)。

2.字符編碼

       請求與相應(yīng)內(nèi)容均采用UTF-8字符編碼

3.簽名規(guī)則

       請求和響應(yīng)中的簽名均使用md5哈希進行，算法如下：

       MD5(簽名內(nèi)容 + ”|” + apiKey)

       說明：

       ·MD5使用RFC1321標(biāo)準(zhǔn)，編碼后需轉(zhuǎn)換成全小寫。

       ·描述簽名的表達式中，”+”表示做字符串連接，實際產(chǎn)生的待簽名字符串中并不存在。

       ·簽名內(nèi)容指各接口請求數(shù)據(jù)中若干字段的拼接?；靖袷綖楦髯侄沃狄?”|” 符號分隔后直接連接。注意，由于”|”符號用作分隔字段，簽名內(nèi)容中需避免出現(xiàn)該符號，換行符(回車或換行)等特殊符號也需要預(yù)先剔除。如果對應(yīng)字段為空，仍然需要保留“|”符號占位。

       ·計算MD5簽名時，應(yīng)以UTF8編碼取字符串的字節(jié)值。

       ·appid及apiKey由打包工具分配，打包工具使用方法請參考使用文檔。

4.簽名示例

       假設(shè)請求數(shù)據(jù)為：

       “data:{

              “id” : 123,

              “name” : “test”

              “value” : “something”

              “other” : “blarblar”

       }

       要求的簽名內(nèi)容為:

id + name + value

則拼接后得出要簽名的內(nèi)容串為

123|test|something

假定apiKey=aabbcc，則需要進行MD5哈希的字符串為：

123|test|something|aabbcc 

1.4 接口說明

1.4.1 用戶會話驗證

1.請求地址：http://TypeSDK:PORT/{appid}/{channelid}/Login/

       說明：URL中的{appid}代表游戲代碼，由打包工具生成，{channelid}代表渠道代碼，渠道代碼列表可以參考打包工具說明，可以從客戶端提交的參數(shù)中獲取當(dāng)前渠道代碼。

       例： http://192.168.0.1:40000/1000/1/Login/

2.調(diào)用方式：HTTP POST

3.接口描述：

       驗證用戶登錄結(jié)果。

A)   游戲客戶端通過SDK客戶端的登錄動作獲取用戶登錄信息。

B)   游戲客戶端將獲取的用戶登錄信息傳送至游戲服務(wù)端。

C)   游戲服務(wù)端通過本請求將用戶登錄信息傳送到SDK服務(wù)端，驗證該登錄信息是否有效。

D)   SDK服務(wù)端返回驗證結(jié)果及其他信息，供游戲服務(wù)器使用。

4.請求方：游戲服務(wù)端

5.響應(yīng)方：SDK服務(wù)端

6.請求內(nèi)容（JSON格式）：

7.返回內(nèi)容（JSON格式）：

響應(yīng)碼說明：

       0：渠道正常返回，結(jié)果成功

       1：渠道正常返回，結(jié)果失敗

       2：渠道服務(wù)端請求錯誤

       -1：提交的請求參數(shù)錯誤

       -2：提交的請求轉(zhuǎn)換成渠道參數(shù)錯誤

       -3：提交的請求參數(shù)簽名錯誤

       -99：未知錯誤

id,nick,token說明：

       根據(jù)不同渠道定義的返回字段不同，此三個字段不一定有值。渠道未返回對應(yīng)字段時，該字段值為空字符串。

1.4.2 充值結(jié)果回調(diào)

1.請求地址：

       該地址為充值結(jié)果通知地址，由游戲服務(wù)端在下文的SaveOrder接口中通過notifyurl字段提交至SDK服務(wù)端。

2.調(diào)用方式：HTTP POST

3.接口描述：

       通知用戶充值結(jié)果。

A)   用戶在游戲中向SDK客戶端提交充值請求。

B)   SDK客戶端將充值請求轉(zhuǎn)發(fā)渠道方

C)   渠道方異步執(zhí)行充值。

D)   渠道方將充值結(jié)果發(fā)送給SDK服務(wù)端

E)   SDK服務(wù)端通過該接口將充值結(jié)果發(fā)送給游戲服務(wù)端。

F)    游戲服務(wù)端處理充值邏輯。

G)   游戲服務(wù)端向SDK服務(wù)端返回處理結(jié)果。

H)   SDK服務(wù)端向渠道方返回處理結(jié)果。

4.請求方：SDK服務(wù)端

5.響應(yīng)方：游戲服務(wù)端

6.請求內(nèi)容（JSON格式）：

7.返回內(nèi)容（JSON格式）：

響應(yīng)碼說明：

       0：正常返回，結(jié)果成功

       1：正常返回，結(jié)果失敗

-99：未知錯誤

8.推薦處理方式

游戲服務(wù)端收到該請求后可保存該次請求參數(shù)，隨即返回code=0，表明成功收到消息。之后異步處理充值或發(fā)放道具邏輯。

1.4.3 充值信息提交

1.請求地址：http://TypeSDK:PORT/{appid}/{channelid}/SaveOrder/

      說明：URL中的{appid}代表游戲代碼，由打包工具生成，{channelid}代表渠道代碼，渠道代碼列表可以參考打包工具文檔，可以從客戶端提交的參數(shù)中獲取當(dāng)前渠道代碼。

       例： http://192.168.0.1:40000/1000/1/SaveOrder/

2.調(diào)用方式：HTTP POST

3.接口描述：

      充值信息存檔待查。

A)   用戶在游戲中向游戲服務(wù)端提交充值請求。

B)    游戲服務(wù)端生成內(nèi)部充值訂單號及相關(guān)充值信息

C)   游戲服務(wù)端將內(nèi)部充值訂單號及相關(guān)充值信息返回游戲客戶端，供其提交給渠道方。

D)   游戲服務(wù)端異步將內(nèi)部充值訂單號，該筆訂單回調(diào)url及相關(guān)充值信息發(fā)送給SDK服務(wù)端。

E)    SDK服務(wù)端將充值信息存檔待查并返回處理結(jié)果。

4.請求方：游戲服務(wù)端

5.響應(yīng)方：SDK服務(wù)端

6.請求內(nèi)容（JSON格式）：

7.返回內(nèi)容（JSON格式）：

響應(yīng)碼說明：

0：正常返回，存檔成功

1：正常返回，存檔失敗

-1：系統(tǒng)錯誤

-2：參數(shù)錯誤

-3：簽名校驗錯誤

-99：未知錯誤

注意：SaveOrder接口在服務(wù)端生成內(nèi)部訂單號時請求。只有獲取到該請求成功返回，才能允許客戶端作后續(xù)充值動作。

1.4.4 充值信息確認

1.請求地址：http://TypeSDK:PORT/{appid}/{channelid}/CheckOrder/

      說明：URL中的{appid}代表游戲代碼，由打包工具生成，{channelid}代表渠道代碼，渠道代碼列表可以參考打包工具文檔，可以從客戶端提交的參數(shù)中獲取當(dāng)前渠道代碼。

       例： http://192.168.0.1:40000/1000/1/CheckOrder/

2.調(diào)用方式：HTTP POST

3.接口描述：

      充值信息查詢。

A)   SDK服務(wù)端向游戲服務(wù)端轉(zhuǎn)發(fā)充值結(jié)果回調(diào)。

B)    游戲服務(wù)端向SDK發(fā)送充值信息查詢請求，目的是確認該充值結(jié)果有效性。

C)   SDK服務(wù)端根據(jù)提交的內(nèi)部充值訂單號查詢充值信息并返回游戲服務(wù)端。

D)   游戲服務(wù)端根據(jù)查詢結(jié)果進行邏輯處理。

說明：部分渠道提供信息查詢接口，本接口將優(yōu)先使用渠道的信息查詢接口處理請求。如果該渠道沒有提供信息查詢接口，則查詢 3.3.3 充值信息提交 接口中保存的充值信息，如果創(chuàng)建充值信息時沒有調(diào)用該接口，或者沒有查詢到目標(biāo)訂單對應(yīng)的充值信息，則會返回未查詢到相應(yīng)充值信息。

4.請求方：游戲服務(wù)端

5.響應(yīng)方：SDK服務(wù)端

6.請求內(nèi)容（JSON格式）：

7.返回內(nèi)容（JSON格式）：

響應(yīng)碼說明：

       0：正常返回，獲取訂單信息成功

       1：正常返回，沒有獲取到訂單信息

       2：正常返回，獲取訂單信息錯誤

-1：系統(tǒng)錯誤

-2：參數(shù)錯誤

-3：簽名校驗錯誤

-99：未知錯誤

1.4.5 游戲訂單查詢

1.請求地址：

       該地址為訂單查詢地址，在SaveOrder接口中通過verifyurl字段提交至SDK服務(wù)端。

2.調(diào)用方式：HTTP POST

3.接口描述：

       SDK服務(wù)端向游戲服務(wù)端查詢收到的訂單信息。

A)   用戶在游戲中向SDK客戶端提交充值請求。

B)   SDK客戶端將充值請求轉(zhuǎn)發(fā)渠道方

C)   渠道方異步執(zhí)行充值。

D)   渠道方將充值結(jié)果發(fā)送給SDK服務(wù)端

E)   SDK服務(wù)端通過該接口向游戲服務(wù)端查詢該充值請求是否合法。

F)    游戲服務(wù)端處理查詢邏輯。

G)   游戲服務(wù)端向SDK服務(wù)端返回查詢結(jié)果。

H)   SDK服務(wù)端比對訂單信息并依此確定下一步處理流程。

4.請求方：SDK服務(wù)端

5.響應(yīng)方：游戲服務(wù)端

6.請求內(nèi)容（JSON格式）：

7.返回內(nèi)容（JSON格式）：

響應(yīng)碼說明：

       0：正常返回，結(jié)果成功

       1：正常返回，結(jié)果失敗

-99：未知錯誤

8.推薦處理方式

游戲服務(wù)端收到該請求后優(yōu)先以CP訂單號為條件查詢，查詢不到或請求中沒有CP訂單號時以渠道訂單號為條件查詢，找到匹配的訂單信息并同步返回SDK服務(wù)端。

1.5 約定

l  支付相關(guān)接口內(nèi)部訂單號字段長度不能超過10位，格式使用英文字母和數(shù)字的組合，需要能夠區(qū)分區(qū)服。不可重復(fù)。

l  渠道返回的用戶id用于用戶唯一標(biāo)識。單區(qū)服內(nèi)不可重復(fù)。

l  支付接口返回的amount是當(dāng)次支付產(chǎn)生的實際金額。

該項目已開源，大家有興趣可以自己研究或使用接入
項目地址：https://code.csdn.net/typesdk_code
項目地址：https://github.com/typesdk