高效率完成一次接入80個(gè)手游渠道SDK——游戲接入SDK客戶端篇

一、引言

通常，游戲開發(fā)商并不會(huì)只在一個(gè)渠道上線他們的游戲，接入越多的渠道，代表著可能獲取越多的用戶，但同時(shí)也代表著越多的接入SDK工作量、工期和費(fèi)用。一款游戲要有足夠的用戶，甚至需要接入30家以上的各種渠道，以保障自己的市場(chǎng)覆蓋率。
單個(gè)SDK接入流程在一位有經(jīng)驗(yàn)的全職客戶端程序、一位全職服務(wù)端程序員、一位全職QA處理的情況下，需要3天時(shí)間才能完成。因此當(dāng)一款產(chǎn)品面對(duì)30個(gè)甚至更多不同需求的渠道SDK時(shí)，人員成本和時(shí)間成本就會(huì)急劇增加。

所以我們需要一個(gè)通用接口，來處理各種渠道的需求，這就是統(tǒng)一渠道SDK接入框架。

二、資源導(dǎo)入

下載地址：https://github.com/typesdk/TypeSdkClient

將TypeSDKLibrary文件夾整個(gè)添加到Unity工程中，注意結(jié)構(gòu)需要與截圖統(tǒng)一。建議游戲中與當(dāng)前導(dǎo)入的腳本命名沖突的文件，需要由開發(fā)者自行修改沖突的類名

添加后的目錄結(jié)構(gòu)如下所示

三、代碼接入

１、接入流程簡(jiǎn)要描述

SDK普通接入邏輯示意圖

1.1在調(diào)用其它API前需先調(diào)用初始化接口對(duì)SDK進(jìn)行初始化。

1.2在完成初始化接口調(diào)用后方可調(diào)用登錄接口，登錄成功選擇角色進(jìn)入游戲后需要調(diào)用提交用戶信息接口。

1.3登錄成功后如果需要切換賬號(hào)，需調(diào)用登出接口。

1.4對(duì)于有依賴于登錄用戶的接口，如支付，提交用戶信息接口，需要調(diào)用獲取用戶信息接口拿到相關(guān)數(shù)據(jù)，如user_id….

1.5在游戲退出時(shí)需要調(diào)用退出接口。

SDK的接入需要接入程序員實(shí)現(xiàn)接口的調(diào)用和回調(diào)函數(shù)的響應(yīng)兩個(gè)部分邏輯

a. 回調(diào)函數(shù)的響應(yīng)主要通過設(shè)置監(jiān)聽來實(shí)現(xiàn)，具體請(qǐng)看第二節(jié)（回調(diào)函數(shù)的處理）

b. 接口的調(diào)用主要為以下的接口調(diào)用，將會(huì)下后面詳細(xì)講解每個(gè)接口的調(diào)用

接口列表

2、回調(diào)函數(shù)的處理

typesdkbaselib中已經(jīng)提供了預(yù)先注冊(cè)完畢所有回調(diào)偵聽的cs文件：U3DTypeEventListener.cs接入方需要在U3DTypeEventListener監(jiān)聽類中，根據(jù)不同回調(diào)事件實(shí)現(xiàn)相應(yīng)的游戲邏輯。

也可以根據(jù)自己需要，在游戲內(nèi)合適的地方，參考demo自行注冊(cè)相關(guān)的函數(shù)偵聽。

注：接入方只能修改以下方法實(shí)現(xiàn)相應(yīng)的邏輯，U3DTypeEventListener類中其它代碼段建議不要更改，以免影響功能。

部分需要界面響應(yīng)的監(jiān)聽，請(qǐng)判斷當(dāng)時(shí)場(chǎng)景，避免造成游戲邏輯混亂。如，在PVP時(shí)檢測(cè)到用戶切換賬號(hào)。

//初始化完成后回調(diào)函數(shù)
void NotifyInitFinish(U3DTypeEvent evt)
{
//游戲需要等待此回調(diào)才允許調(diào)用登錄接口。
}

    //登錄操作完成后的回調(diào)函數(shù)
    void NotifyLogin(U3DTypeEvent evt){
        //解析渠道登錄成功返回的信息，一般有user_token,user_id...
              //此時(shí)返回的結(jié)果不能作為登錄依據(jù)，需要進(jìn)過服務(wù)端驗(yàn)證，取的服務(wù)器返回的最終數(shù)據(jù)。
        //CP方需要將信息解析為CP服務(wù)器約定的數(shù)據(jù)格式轉(zhuǎn)發(fā)給游戲服務(wù)器，并由游戲服務(wù)器轉(zhuǎn)發(fā)至TypeSDK Server以完成游戲的登錄驗(yàn)證
         string userId = evt.evtData.GetData(U3DTypeAttName.USER_ID);
}

    //更新渠道更新檢測(cè)完成后回調(diào)
void NotifyUpdateFinish(U3DTypeEvent evt){
       //建議等待此更新完成后，再進(jìn)行游戲的更新邏輯，否則會(huì)造成渠道更新和游戲自身更新沖突。
}

    //支付結(jié)果通知回調(diào)，CP需根據(jù)支付返回結(jié)果完成相應(yīng)邏輯，此處為客戶端返回結(jié)果，不可作為支付到賬依據(jù)，游戲需等待TypeSDK Server的支付成功回調(diào)。
    void NotifyPayResult(U3DTypeEvent evt){
        if (evt.evtData.GetData(U3DTypeAttName.PAY_RESULT).Equals("1"))
{ //支付完成，可嘗試延遲刷新賬戶余額信息。
            Debug.Log("pay finished:" + evt.evtData.GetData(U3DTypeAttName.PAY_RESULT_DATA));
        }
        else
        {//支付失敗，或取消。
            Debug.Log("pay failed:" + evt.evtData.GetData(U3DTypeAttName.PAY_RESULT_REASON));
        }
}

    //登出結(jié)果通知回調(diào)，說明用戶已經(jīng)做了退出賬戶操作，需要返回登錄界面，并重新調(diào)用登錄
    void NotifyLogout(U3DTypeEvent evt){
}

    //重登錄結(jié)果通知回調(diào)，用戶在渠道SDK進(jìn)行用戶切換操作，需要切換到新賬號(hào)界面。
    void NotifyRelogin(U3DTypeEvent evt){
}

    //取消退出游戲通知回調(diào)，把退出游戲邏輯說明一下。
    void NotifyCancelExit(U3DTypeEvent evt){
}

3、SDK傳遞的基本數(shù)據(jù)類型

sdk用到的數(shù)據(jù)類型 都繼承于U3DTypeBaseData，相關(guān)使用示例如下：

3.1創(chuàng)建U3DTypeBaseData對(duì)象

U3DTypeBaseData baseData = new U3DTypeBaseData();

3.2設(shè)置一條屬性

示例：

//（鍵名使用U3DTypeAttName定義的字段）
baseData.SetData(“鍵名”,”值”);

3.3獲得一個(gè)string類型的屬性 attname為標(biāo)識(shí)

3.4獲得一個(gè)int類型的屬性 attname為標(biāo)識(shí)

3.5獲得一個(gè)bool類型的屬性 attname為標(biāo)識(shí)

函數(shù)名

使用例子：

//新建一個(gè)對(duì)象
       U3DTypeBaseData egData = new U3DTypeBaseData ();
//給該對(duì)象賦值
egData.SetData (U3DTypeAttName.APP_KEY, "123456789");
//讀取一個(gè)string類型數(shù)據(jù)readStr = "123456789
        string readStr = egData.GetData (U3DTypeAttName.APP_KEY);
//讀取一個(gè)int類型數(shù)據(jù)readInt
        int readInt = egData.GetInt(U3DTypeAttName.APP_KEY); = 123456789

響應(yīng)消息傳遞的消息類型

public class U3DTypeEvent

事件對(duì)象例子

void LoginResult(U3DTypeEvent evt)
    {
        U3DTypeBaseData data = evt.evtData;
        string userID = data.GetData(U3DTypeAttName.USER_ID);
        string userToken = data.GetData(U3DTypeAttName.USER_TOKEN);
  }

4、接口接入與描述

(1)初始化

調(diào)用例子

U3DTypeSDK.Instance.InitSDK();

(2)登錄

調(diào)用例子

U3DTypeSDK.Instance.Login();

(3)提交用戶信息

調(diào)用例子

U3DTypeSDK.Instance.UpdatePlayerInfo()

當(dāng)用戶成功完全登錄進(jìn)入游戲后，需要設(shè)置用戶相關(guān)信息并且提交

該函數(shù)的所有內(nèi)容，不能使用SDK客戶端本地緩存的數(shù)據(jù)，建議從服務(wù)端獲得

需要設(shè)置的屬性如下，當(dāng)沒有該屬性時(shí)，請(qǐng)傳空字符串

string ROLE_TYPE = “create_role”;//角色統(tǒng)計(jì)信息類型即調(diào)用時(shí)機(jī)，（createRole:創(chuàng)建角色，levelUp:角色升級(jí)，enterGame:選定角色進(jìn)入游戲）（不能為空）
string SAVED_BALANCE = “0”;//當(dāng)前角色余額（RMB購買的游戲幣），默認(rèn)為0
string USER_NAME = "user_name"; //用戶名
string USER_TOKEN = "user_token"; //用戶渠道驗(yàn)證用token
string USER_ID = "user_id"; //用戶id
string USER_HEAD_ID = "user_head_id"; //用戶頭像id
string USER_HEAD_URL = "user_head_url"; //用戶頭像url
string VIP_LEVEL = “vip_level”;//VIP等級(jí)，沒有傳0
string PARTY_NAME = “party_name”;//工會(huì)名稱,如：天下第一
string ROLE_ID = "role_id"; //角色id
string ROLE_NAME = "role_name"; //角色名字
string ROLE_LEVEL = "role_level"; //角色等級(jí)
string ROLE_CREATE_TIME = “role_create_time”;//角色創(chuàng)建時(shí)間，一定要服務(wù)器時(shí)間（單位/秒）
string ROLE_LEVELUP_TIME = “role_levelup_time”;//角色升級(jí)時(shí)間（單位/秒）
string ZONE_ID = "zone_id"; //所在大區(qū)id
string ZONE_NAME= "zone_name"; //所在大區(qū)名稱
string SEVER_ID = "server_id"; //所在服務(wù)器id
string SERVER_NAME = “server_name”;//所在服務(wù)器名稱
string EXTRA ="extra";

設(shè)置方法示例：

U3DTypeSDK.Instance.GetUserData().SetData(U3DTypeAttName.USER_ID, "123");
U3DTypeSDK.Instance.GetUserData().SetData(U3DTypeAttName.EXTRA, "1");
U3DTypeSDK.Instance.UpdatePlayerInfo();

(4)支付

調(diào)用例子

U3DTypeSDK.Instance.PayItem (U3DTypeBaseData _in_pay);

其中U3DTypeBaseData中

U3DTypeBaseData userData = U3DTypeSDK.Instance.GetUserData();

必填參數(shù)為：

//用戶ID，渠道返回，沒有填空
payData.SetData(U3DTypeAttName.USER_ID,userData.GetData(U3DTypeAttName.USER_ID))；
//用戶token，登錄驗(yàn)簽完成后由游戲服務(wù)端返回，沒有填空
payData.SetData(U3DTypeAttName.USER_TOKEN,userData.GetData(U3DTypeAttName.USER_TOKEN))；
//商品支付價(jià)格（單位：分）
payData.SetData(U3DTypeAttName.REAL_PRICE,”100");
//商品名稱
payData.SetData(U3DTypeAttName.ITEM_NAME,"sk bi”);
//商品數(shù)量
payData.SetData(U3DTypeAttName.ITEM_COUNT,”1");
//所在服務(wù)器id（如果沒有填“0”）
payData.SetData(U3DTypeAttName.SERVER_ID,”1”);
//所在服務(wù)器名字（如果沒有填“server_name”）
payData.SetData(U3DTypeAttName.SERVER_NAME,”安卓一區(qū)”);
//所在大區(qū)id（如果沒有填“0”），注意應(yīng)用寶要求：賬戶分區(qū)ID_角色I(xiàn)D。每個(gè)應(yīng)用都有一個(gè)分區(qū)ID為1的默認(rèn)分區(qū)，分區(qū)可以在cpay.qq.com/mpay上自助配置。如果應(yīng)用選擇支持角色，則角色I(xiàn)D接在分區(qū)ID號(hào)后用"_"連接，角色I(xiàn)D需要進(jìn)行urlencode。payData.SetData(U3DTypeAttName.ZONE_ID,”1”);
//所在大區(qū)名字（如果沒有填“server_name”）
payData.SetData(U3DTypeAttName.ZONE_NAME,”華北一區(qū)”);

//內(nèi)部訂單號(hào)（必須填寫，并保證多區(qū)情況下，訂單號(hào)唯一）
payData.SetData(U3DTypeAttName.BILL_NUMBER,”NO_123456”);
//商品id（需和TypeSDK Server商品列表保持一致）
payData.SetData(U3DTypeAttName.ITEM_SEVER_ID,”id”);
//傳遞的額外參數(shù)（建議傳入需要用來做訂單標(biāo)識(shí)的信息）
payData.SetData(U3DTypeAttName.EXTRA,”extra");
//商品描述
payData.SetData(U3DTypeAttName.ITEM_DESC,”desc”);
//玩家在游戲中的角色I(xiàn)D
payData.SetData(U3DTypeAttName.ROLE_ID,”role_1234”);
//玩家在游戲中的角色名字
payData.SetData(U3DTypeAttName.ROLE_NAME,”玩家編號(hào)001”);

當(dāng)支付行為在客戶端完成后，會(huì)接到回調(diào)消息：EVENT_PAY_RESULT

其中event的使用類似 login

event中data的參數(shù)包括以下內(nèi)容

PAY_RESULT//支付結(jié)果（1/0/2）成功／失敗(除取消)/支付取消
//說明：客戶端收到“失敗或支付取消”狀態(tài)，建議客戶端可以使用戶直接發(fā)起下筆充值。
PAY_RESULT_REASON//支付結(jié)果的原因（失敗原因）
PAY_RESULT_DATA

(5)登出

調(diào)用例子：

U3DTypeSDK.Instance.Logout()

登出成功則會(huì)發(fā)送 TypeEventType.EVENT_LOGOUT消息，發(fā)送的參數(shù)U3DTypeBaseData數(shù)據(jù)

(6)退出

U3DTypeSDK.Instance.ExitGame();

整個(gè)游戲的退出行為 ，建議交給sdk處理，并且添加 退出行為取消響應(yīng)事件偵聽TypeEventType.EVENT_CANCEL_EXIT_GAME 的函數(shù)

當(dāng)退出成功后 由sdk執(zhí)行系統(tǒng)的退出，當(dāng)退出取消后，則會(huì)發(fā)送 取消退出事件，接入方需完成相應(yīng)的邏輯。

(7)獲取當(dāng)前渠道ＳＤＫ配置參數(shù)

U3DTypeSDK.Instance.GetPlatformData()

包括以下內(nèi)容：

CHANNEL_ID//渠道的id（由SDK組定義 和ConfigSever上的channel id統(tǒng)一）
SDK_NAME//渠道標(biāo)記
CP_ID

以上參數(shù) 在CPSeting.txt中填寫（接入方無需關(guān)心）

(8)用戶中心

顯示渠道用戶中心

U3DTypeSDK.Instance.ShowPersonCenter()

隱藏用戶中心

U3DTypeSDK.Instance.HidePersonCenter()

在調(diào)用這2個(gè)函數(shù)之前 需要先執(zhí)行IsHasRequest(U3DTypeAttName.SUPPORT_PERSON_CENTER)函數(shù) 用以判定 是否需要支持該函數(shù)。

當(dāng)支持時(shí) 這2個(gè)函數(shù)才會(huì)起效，并且需要在游戲內(nèi)，需要有相應(yīng)的圖形入口，

當(dāng)不支持時(shí)，這2個(gè)函數(shù)不會(huì)生效，游戲內(nèi)頁不需要相應(yīng)的圖形入口。

使用示例：

if(IsHasRequest(U3DTypeAttName.SUPPORT_PERSON_CENTER)){
       U3DTypeSDK.Instance.ShowPersonCenter();

或

U3DTypeSDK.Instance.HidePersonCenter();
pushData.DataToString(_json_data);
U3DSDK.instance.SendMessage(“receive_local_notify”,pushData);
}

(9)查詢渠道是否彈出退出框

U3DTypeSDK.Instance.IsHasRequest(“support_exit_window”)