高效率完成一次接入80個手遊渠道SDK——遊戲接入SDK服務端篇
.1 概要
通常,遊戲開發商並不會只在一個渠道上線他們的遊戲,接入越多的渠道,代表著可能獲取越多的使用者,但同時也代表著越多的接入SDK工作量、工期和費用。一款遊戲要有足夠的使用者,甚至需要接入30家以上的各種渠道,以保障自己的市場覆蓋率。
單個SDK接入流程在一位有經驗的全職客戶端程式、一位全職服務端程式設計師、一位全職QA處理的情況下,需要3天時間才能完成。因此當一款產品面對30個甚至更多不同需求的渠道SDK時,人員成本和時間成本就會急劇增加。所以我們需要一個通用介面,來處理各種渠道的需求,這就是統一渠道SDK接入框架。 本部分主要提供平臺SDK伺服器與CP方遊戲伺服器互動的介面規範
1.2 支付基本流程
1.2.1 渠道支付流程
遊戲客戶端在每次使用者點選購買時向服務端請求生成內部訂單。並需要採用特定機制(例如一定時間內禁止連續點選購買)防止使用者頻繁操作對伺服器造成過高負載。
遊戲服務端生成的所有內部訂單需要儲存待查。並在得到渠道返回的外部訂單後非同步處理髮貨操作並以特定機制通知客戶端更新資料顯示。
渠道支付介面負責完成貨幣交易操作,生成並存儲外部訂單,供對賬查詢使用。
SDK服務端轉發請求時額外儲存一份訂單日誌資料,儲存內部訂單號,外部訂單號及訂單狀態,供對賬及查詢BUG時作為參考。
1.2.2 一般渠道支付流程圖
1.3 協議說明
1.3.1 通訊協議
SDK伺服器採用HTTP協議作為通訊協議,遊戲伺服器通過構造HTTP請求(POST方式)向SDK伺服器發起介面請求。
1.3.2 資料協議
1.資料格式
請求訊息和響應訊息的內容都使用JSON表示資料。
2.字元編碼
請求與相應內容均採用UTF-8字元編碼
3.簽名規則
請求和響應中的簽名均使用md5雜湊進行,演算法如下:
MD5(簽名內容 + ”|” + apiKey)
說明:
·MD5使用RFC1321標準,編碼後需轉換成全小寫。
·描述簽名的表示式中,”+”表示做字串連線,實際產生的待簽名字串中並不存在。
·簽名內容指各介面請求資料中若干欄位的拼接。基本格式為各欄位值以 ”|” 符號分隔後直接連線。注意,由於”|”符號用作分隔欄位,簽名內容中需避免出現該符號,換行符(回車或換行)等特殊符號也需要預先剔除。如果對應欄位為空,仍然需要保留“|”符號佔位。
·計算MD5簽名時,應以UTF8編碼取字串的位元組值。
·appid及apiKey由打包工具分配,打包工具使用方法請參考使用文件。
4.簽名示例
假設請求資料為:
“data:{
“id” : 123,
“name” : “test”
“value” : “something”
“other” : “blarblar”
}
要求的簽名內容為:
id + name + value
則拼接後得出要簽名的內容串為
123|test|something
假定apiKey=aabbcc,則需要進行MD5雜湊的字串為:
123|test|something|aabbcc
1.4 介面說明
1.4.1 使用者會話驗證
說明:URL中的{appid}代表遊戲程式碼,由打包工具生成,{channelid}代表渠道程式碼,渠道程式碼列表可以參考打包工具說明,可以從客戶端提交的引數中獲取當前渠道程式碼。
2.呼叫方式:HTTP POST
3.介面描述:
驗證使用者登入結果。
A) 遊戲客戶端通過SDK客戶端的登入動作獲取使用者登入資訊。
B) 遊戲客戶端將獲取的使用者登入資訊傳送至遊戲服務端。
C) 遊戲服務端通過本請求將使用者登入資訊傳送到SDK服務端,驗證該登入資訊是否有效。
D) SDK服務端返回驗證結果及其他資訊,供遊戲伺服器使用。
4.請求方:遊戲服務端
5.響應方:SDK服務端
6.請求內容(JSON格式):
欄位名稱 |
欄位說明 |
型別 |
備註 |
id |
使用者唯一標識 |
string |
對應渠道的使用者ID。並非必傳,未作說明的情況下傳空字串。 |
token |
使用者登入會話標識 |
string |
本次登入標識。並非必傳,未作說明的情況下傳空字串。 |
data |
附加資訊 |
JSON |
附加資訊。並非必傳,根據渠道不同,該欄位含義不同,未作說明的情況下傳空字串。 |
sign |
簽名引數 |
string |
MD5(簽名內容 + ”|” + apiKey) 簽名內容: Id + ”|” + token + ”|” + data |
7.返回內容(JSON格式):
欄位名稱 |
欄位說明 |
型別 |
備註 |
code |
響應碼 |
int |
本次請求結果標誌 |
id |
使用者唯一標識 |
string |
對應渠道的使用者ID |
nick |
使用者在渠道的暱稱 |
string |
對應渠道的使用者暱稱 |
token |
使用者登入會話標識 |
string |
本次登入標識 |
msg |
響應資訊 |
string |
如果請求出錯,描述錯誤資訊。 |
value |
渠道返回資訊 |
JSON |
渠道返回的原始結果資訊。 |
響應碼說明:
0:渠道正常返回,結果成功
1:渠道正常返回,結果失敗
2:渠道服務端請求錯誤
-1:提交的請求引數錯誤
-2:提交的請求轉換成渠道引數錯誤
-3:提交的請求引數簽名錯誤
-99:未知錯誤
id,nick,token說明:
根據不同渠道定義的返回欄位不同,此三個欄位不一定有值。渠道未返回對應欄位時,該欄位值為空字串。
1.4.2 充值結果回撥
1.請求地址:
該地址為充值結果通知地址,由遊戲服務端在下文的SaveOrder介面中通過notifyurl欄位提交至SDK服務端。
2.呼叫方式:HTTP POST
3.介面描述:
通知使用者充值結果。
A) 使用者在遊戲中向SDK客戶端提交充值請求。
B) SDK客戶端將充值請求轉發渠道方
C) 渠道方非同步執行充值。
D) 渠道方將充值結果傳送給SDK服務端
E) SDK服務端通過該介面將充值結果傳送給遊戲服務端。
F) 遊戲服務端處理充值邏輯。
G) 遊戲服務端向SDK服務端返回處理結果。
H) SDK服務端向渠道方返回處理結果。
4.請求方:SDK服務端
5.響應方:遊戲服務端
6.請求內容(JSON格式):
欄位名稱 |
欄位說明 |
型別 |
備註 |
code |
響應碼 |
int |
渠道返回的充值結果。 |
id |
使用者唯一標識 |
string |
對應渠道的使用者ID。 |
order |
渠道訂單號 |
string |
渠道返回的訂單號。 |
cporder |
CP訂單號 |
string |
遊戲客戶端在提交訂單時傳送的內部訂單號。如果該渠道未接收該引數,則該欄位為空字串。 |
info |
訂單附加資訊 |
string |
遊戲客戶端在提交訂單時傳送的附加資訊。如果該渠道未接收該引數,則該欄位為空字串。 |
sign |
簽名引數 |
string |
MD5(簽名內容 + ”|” + apiKey) 簽名內容: code + ”|” + id + ”|” + order+ ”|” + cporder + ”|” + info |
amount |
訂單金額 |
string |
該筆訂單價值折算為人民幣的金額(以分為單位)供服務端校驗使用,不參與簽名。 |
7.返回內容(JSON格式):
欄位名稱 |
欄位說明 |
型別 |
備註 |
code |
響應碼 |
int |
本次請求結果標誌 |
msg |
響應資訊 |
string |
如果請求出錯,描述錯誤資訊。 |
響應碼說明:
0:正常返回,結果成功
1:正常返回,結果失敗
-99:未知錯誤
8.推薦處理方式
遊戲服務端收到該請求後可儲存該次請求引數,隨即返回code=0,表明成功收到訊息。之後非同步處理充值或發放道具邏輯。
1.4.3 充值資訊提交
說明:URL中的{appid}代表遊戲程式碼,由打包工具生成,{channelid}代表渠道程式碼,渠道程式碼列表可以參考打包工具文件,可以從客戶端提交的引數中獲取當前渠道程式碼。
2.呼叫方式:HTTP POST
3.介面描述:
充值資訊存檔待查。
A) 使用者在遊戲中向遊戲服務端提交充值請求。
B) 遊戲服務端生成內部充值訂單號及相關充值資訊
C) 遊戲服務端將內部充值訂單號及相關充值資訊返回遊戲客戶端,供其提交給渠道方。
D) 遊戲服務端非同步將內部充值訂單號,該筆訂單回撥url及相關充值資訊傳送給SDK服務端。
E) SDK服務端將充值資訊存檔待查並返回處理結果。
4.請求方:遊戲服務端
5.響應方:SDK服務端
6.請求內容(JSON格式):
欄位名稱 |
欄位說明 |
型別 |
備註 |
cporder |
CP訂單號 |
string |
遊戲客戶端在提交訂單時傳送的內部訂單號。 |
data |
訂單資訊 |
string |
由CP生成訂單時自定義的附加資訊,不能為空及空字串。 |
sign |
簽名引數 |
string |
MD5(簽名內容 + ”|” + apiKey) 簽名內容: cporder + ”|” + data |
notifyurl |
訂單回撥url |
string |
該筆訂單回撥通知遊戲服務端的url,不參與簽名。 |
verifyurl |
訂單查詢url |
string |
該筆訂單向遊戲服務端查詢詳情的url,不參與簽名。 |
7.返回內容(JSON格式):
欄位名稱 |
欄位說明 |
型別 |
備註 |
code |
響應碼 |
int |
本次請求結果標誌 |
msg |
響應資訊 |
string |
如果請求出錯,描述錯誤資訊。 |
響應碼說明:
0:正常返回,存檔成功
1:正常返回,存檔失敗
-1:系統錯誤
-2:引數錯誤
-3:簽名校驗錯誤
-99:未知錯誤
注意:SaveOrder介面在服務端生成內部訂單號時請求。只有獲取到該請求成功返回,才能允許客戶端作後續充值動作。
1.4.4 充值資訊確認
說明:URL中的{appid}代表遊戲程式碼,由打包工具生成,{channelid}代表渠道程式碼,渠道程式碼列表可以參考打包工具文件,可以從客戶端提交的引數中獲取當前渠道程式碼。
2.呼叫方式:HTTP POST
3.介面描述:
充值資訊查詢。
A) SDK服務端向遊戲服務端轉發充值結果回撥。
B) 遊戲服務端向SDK傳送充值資訊查詢請求,目的是確認該充值結果有效性。
C) SDK服務端根據提交的內部充值訂單號查詢充值資訊並返回遊戲服務端。
D) 遊戲服務端根據查詢結果進行邏輯處理。
說明:部分渠道提供資訊查詢介面,本介面將優先使用渠道的資訊查詢介面處理請求。如果該渠道沒有提供資訊查詢介面,則查詢 3.3.3 充值資訊提交 介面中儲存的充值資訊,如果建立充值資訊時沒有呼叫該介面,或者沒有查詢到目標訂單對應的充值資訊,則會返回未查詢到相應充值資訊。
4.請求方:遊戲服務端
5.響應方:SDK服務端
6.請求內容(JSON格式):
欄位名稱 |
欄位說明 |
型別 |
備註 |
cporder |
CP訂單號 |
string |
遊戲客戶端在提交訂單時傳送的內部訂單號。 |
sign |
簽名引數 |
string |
MD5(簽名內容 + ”|” + apiKey) 簽名內容: cporder |
7.返回內容(JSON格式):
欄位名稱 |
欄位說明 |
型別 |
備註 |
code |
響應碼 |
int |
本次請求結果標誌 |
msg |
響應資訊 |
string |
如果請求出錯,描述錯誤資訊。 |
value |
訂單詳細資訊 |
JSON |
根據渠道不同,返回相應訂單資訊。 |
響應碼說明:
0:正常返回,獲取訂單資訊成功
1:正常返回,沒有獲取到訂單資訊
2:正常返回,獲取訂單資訊錯誤
-1:系統錯誤
-2:引數錯誤
-3:簽名校驗錯誤
-99:未知錯誤
1.4.5 遊戲訂單查詢
1.請求地址:
該地址為訂單查詢地址,在SaveOrder介面中通過verifyurl欄位提交至SDK服務端。
2.呼叫方式:HTTP POST
3.介面描述:
SDK服務端向遊戲服務端查詢收到的訂單資訊。
A) 使用者在遊戲中向SDK客戶端提交充值請求。
B) SDK客戶端將充值請求轉發渠道方
C) 渠道方非同步執行充值。
D) 渠道方將充值結果傳送給SDK服務端
E) SDK服務端通過該介面向遊戲服務端查詢該充值請求是否合法。
F) 遊戲服務端處理查詢邏輯。
G) 遊戲服務端向SDK服務端返回查詢結果。
H) SDK服務端比對訂單資訊並依此確定下一步處理流程。
4.請求方:SDK服務端
5.響應方:遊戲服務端
6.請求內容(JSON格式):
欄位名稱 |
欄位說明 |
型別 |
備註 |
code |
操作型別 |
string |
預留欄位,區分本次查詢操作型別。目前統一傳0 |
id |
使用者唯一標識 |
string |
對應渠道的使用者ID。 |
order |
渠道訂單號 |
string |
渠道返回的訂單號。 |
cporder |
CP訂單號 |
string |
遊戲客戶端在提交訂單時傳送的內部訂單號。如果該渠道未接收該引數,則該欄位為空字串。 |
info |
訂單附加資訊 |
string |
遊戲客戶端在提交訂單時傳送的附加資訊。如果該渠道未接收該引數,則該欄位為空字串。 |
sign |
簽名引數 |
string |
MD5(簽名內容 + ”|” + apiKey) 簽名內容: code + ”|” + id + ”|” + order+ ”|” + cporder + ”|” + info |
7.返回內容(JSON格式):
欄位名稱 |
欄位說明 |
型別 |
備註 |
code |
響應碼 |
int |
本次請求結果標誌 |
msg |
響應資訊 |
string |
如果請求出錯,描述錯誤資訊。 |
id |
使用者唯一標識 |
string |
對應渠道的使用者ID。 |
order |
渠道訂單號 |
string |
渠道返回的訂單號。 |
cporder |
CP訂單號 |
string |
遊戲客戶端在提交訂單時傳送的內部訂單號。如果該渠道未接收該引數,則該欄位為空字串。 |
amount |
訂單金額 |
string |
該筆訂單價值折算為人民幣的金額(以分為單位)。 |
createtime |
訂單建立時間 |
string |
該筆訂單建立時間。 |
Itemid |
道具id |
string |
該筆訂單的道具id,如果沒有傳空字串。 (該欄位標識訂單中的商品ID,需要與客戶端下訂單時對應的欄位匹配,驗證對比不符時不發貨) |
Itemquantity |
道具數量 |
Int |
該筆訂單道具數量,沒有傳0。 (該欄位標識客戶端提交的訂單中的道具數量,渠道不接受該欄位時,客戶端提交的訂單沒有該欄位,此時直接傳0或1均可) |
status |
訂單狀態 |
int |
訂單狀態碼。 |
info |
其他資訊 |
string |
備用欄位,傳送其他可供比對的資訊。 |
響應碼說明:
0:正常返回,結果成功
1:正常返回,結果失敗
-99:未知錯誤
8.推薦處理方式
遊戲服務端收到該請求後優先以CP訂單號為條件查詢,查詢不到或請求中沒有CP訂單號時以渠道訂單號為條件查詢,找到匹配的訂單資訊並同步返回SDK服務端。
1.5 約定
l 支付相關介面內部訂單號欄位長度不能超過10位,格式使用英文字母和數字的組合,需要能夠區分割槽服。不可重複。
l 渠道返回的使用者id用於使用者唯一標識。單區服內不可重複。