GHOME 国际版SDK (PC版) 开发手册 for Unity C#

版本更新说明

前言

本文用于指导游戏开发商接入GHome-International_Unity PC 版本SDK，文中包含客户端的接入说明；

SDK接入流程概述

• 初始化SDK

• 初始化成功，调用账号功能相关接口

• 用户在进行购买时，调用支付功能相关接口

• 接入注销接口

• 其他功能接口，可根据业务需要适时调用

集成SDK文件到游戏工程

请按照以下步骤集成：

• 下载json解析插件Newtonsoft Json（package manager可直接下载该插件，git url：com.unity.nuget.newtonsoft-json）

• 下载并导入插件Embedded_Browser_3.1.0.unitypackage (opens new window) (下载地址：https://gskd.sdoprofile.com/ghome/ztc/sdk/Embedded_Browser_3.1.0.unitypackage.unitypackage)

  【注意】若游戏项目中已有该库的话，请修改源码UserAgent类中的GetUserAgent()方法。老的userAgent会导致谷歌登录验证不通过。

  修改后的userAgent对象：

  var userAgent =
                "Mozilla/5.0 " +
                "(" + osStr + "; Unity 3D; ZFBrowser 3.1.0; " + Application.productName + " " + Application.version + ") " +
                "Chrome/" + chromeVersion + " Safari/537.36";
  

• 导入GHomeInternationalSDK_vXXX.unitypackage 包（demo 代码所在路径：GHomeInternationalDemo，可按需勾选导入进行参考）

数据结构说明

一、GHomeTBaseRet详解

GHomeSDK 回调的基础结构体，所有的回调结果类都继承自它。该类包含一些基础的信息。

成员变量名称	类型	说明
MethodNameId	int	调用接口的方法标记，对应 GHomeTMethodNameID 枚举
RetCode	int	SDK 的返回码，详情参考 GHomeTError 类
RetMsg	string	SDK 描述信息
ThirdCode	int	第三方渠道返回码
ThirdMsg	string	第三方渠道描述信息
ExtraJson	string	扩展字段

二、各方法名枚举说明

public enum GHomeTMethodNameID : int
{
     // 未定义方法名
     METHODNAMEID_UNDEFINE = 000, 

     // 初始化
     BASE_INIT = 111, 

     // 登录
     LOGIN_LOGIN = 211,
     //获取登录小票
     LOGIN_GET_TICKET = 212, 

     // pay
     PAY_WEB_PAY = 311, 

     //get agreement url
     GET_AGREEMENT_URL = 411, 

     //get area config list
     GET_AREA_CONFIG_LIST = 511, 

     //get product config list
     GET_PRODUCT_CONFIG_LIST = 611,

     // bind acct
     BIND_ACCT = 811
}

基础模块（必接）

自定义域名（如果不需要自定义域名，可以忽略这一条）

根据发布国家和地区配置不同的域名（默认新加坡）。

以下方式二选一，方式一优先级大于方式二，即：如果两种方式同时设置，优先使用方式一的配置

方式一、通过SetDomain接口配置

1）功能描述

如果您需要自定义接口请求的域名，可以调用此接口进行设置

2）接口声明

public static void SetDomain(string baseUrl = "", string payUrl = "", string logUrl = "", string webUrl = "")

3）参数说明

参数名称	参数类型	说明（默认是在新加坡）
baseUrl	string	通用域名（例如初始化、登录等），默认值："https://abroad-sin.shengqugames-corp.com"
payUrl	string	支付域名，默认值："https://abroad-sin-pay.shengqugames-corp.com"
logUrl	string	日志域名，默认值："https://reportsk-gg.web.sdo.com"
webUrl	string	web登录服务域名（例如注册、重置密码、三方登录等），默认值："https://abroad-sin-wlogin.shengqugames-corp.com"

4）示例代码

GHomeT.SetDomain("https://xxx", "https://xxx", "https://xxx", "https://xxx");

5）注意事项

如果要自定义配置域名，请务必在初始化接口之前设置，传null或者空字符串将使用默认的域名

方式二、通过配置文件配置

1）功能描述

在 Unity Editor 环境中，点击菜单 GHomeSDK -> SDKConfigSettings，可以生成配置信息编辑面板。

生成的配置面板路径：/Assets/GHomeInternationalConfig

在配置面板修改填写域名，点击保存，生成最终配置文件txt。

最终的配置文件路径：/Assets/Resources/GHomeInternationalConfigData/Data/

2）注意事项

• 请勿修改配置文件路径，您可以查看文件内容，确认域名是否正确

• 每次SDK初始化，会读取配置文件中的相应内容

• 如果不设置，将使用默认值。【注意】如果通过GHomeTApi中的SetDomain()方法来设置，此配置失效，将以SetDomain接口配置为准

注册GHomeSDK 初始化回调

1）功能描述

接受GHomeSDK初始化完成的回调，游戏需要注册回调函数进行处理。游戏需要等待该回调完成后，才能开始调用GHomeSDK其他模块功能接口。

2）接口声明

/// GHomeSDK初始化回调
public static event GHomeTEventHandler.OnGHomeTRetEventHandler<GHomeTBaseRet> InitRetEvent;

3）示例代码

/// 注册监听
GHomeT.InitRetEvent += OnInitRetEvent;

/// 回调
private void OnInitRetEvent(GHomeTBaseRet baseRet)
{
   if (baseRet.RetCode == GHomeTError.CODE_SUCCESS)
   {
       // 此时可以调用GhomeSDK的其他接口了
   }
   else
   {
    }
}

/// 销毁监听
private void OnDestroy()
{
    GHomeT.InitRetEvent -= OnInitRetEvent;
}

初始化 SDK

1）功能描述

需要在游戏开始时，执行 GHomeT.Init 方法来初始化 GHomeSDK 模块。

2）接口声明

/// 初始化
public static void Init(string appId)

3）参数说明

参数名称	参数类型	说明
appId	string	必传，GHome后台登记游戏获得的 appId

4）示例代码

GHomeT.Init("791000008");

账号模块（必接）

一、概述

GHomeSDK登录功能为游戏提供便捷的登录功能，支持的登录渠道有：

• 邮箱登录

• 苹果登录

• Facebook登录

• Google登录

• Twitter登录

• Line登录

• 二维码登录

推荐登录流程

1. 初始化 SDK
2. 注册登录回调
3. 调用登录

注册&登录原理

1. 在游戏登录界面打开SDK注册&登录界面；

2. 用户完成注册&登录之后，SDK会把用户id和ticket票据返回游戏；

3. 游戏如果有服务器，需要把客户端获取到ticket票据发送到“登录票据验证接口”进行验证，然后把返回的用户信息（用户id和账号）保存到游戏服务器；

二、API 调用

注册回调

1）功能描述

接受 GHome 登录模块的回调，游戏需要注册回调函数进行处理；强烈建议游戏在应用启动函数中进行注册。

2）接口声明

/// 登录回调、获取新的票据回调
public static event GHomeTEventHandler.OnGHomeTRetEventHandler<GHomeTLoginRet> LoginRetEvent;

3）示例代码

/// 注册监听
GHomeTLogin.LoginRetEvent += OnLoginRetEvent;

/// 回调
private void OnLoginRetEvent(GHomeTLoginRet loginRet)
{
    if (loginRet.RetCode == GHomeTError.CODE_SUCCESS)
    {
        if (loginRet.MethodNameId == GHomeTMethodNameID.LOGIN_LOGIN)
        {
        }
        else if (loginRet.MethodNameId == GHomeTMethodNameID.LOGIN_GET_TICKET)
        {
        }
    }
    else if (loginRet.RetCode == GHomeTError.CODE_CANCEL)
    {
        GHomeUtils.ShowToastUI(TAG + loginRet.RetMsg);
    }
    else
    {
        GHomeUtils.ShowToastUI(TAG + loginRet.RetMsg);
    }
}


/// 销毁监听
private void OnDestroy()
{
    GHomeTLogin.LoginRetEvent -= OnLoginRetEvent;
}

4）数据结构

GHomeTLoginRet详解

继承自GHomeTBaseRet，包含基础的信息

成员变量名称	类型	说明
userid	string	用户ID
loginType	int	登录类型  0:游客 588:邮箱 502:Google 503:Facebook 504:AppleId 505:Twitter 506:Line
ticket	string	登录票据
autokey	string	自动登录key
isBind	bool	是否绑定，只有游客登录此字段才会有意义
isGuest	bool	是否是游客登录。目前是在移动客户端使用了游客登录，然后扫码登录PC才会触发true
confirmChannel	string	移动端扫码渠道号: ios google onestore mycard

登录

1）功能描述

获取登录态并到 GHomeSDK 服务器鉴权，返回 GHomeSDK 统一账号。

2）接口声明

public static void Login()

3）示例代码

GHomeTLogin.Login();

获取新的ticket

1）功能描述

获取最新的ticket

2）接口声明

/// 获取新的ticket
public static void GetNewLoginTicket()

3）示例代码

GHomeTLogin.GetNewLoginTicket();

获取登录态

1）功能描述

在游戏中，获取游戏的登录态信息，注意，该接口不会检验登录态是否过期

2）接口声明

public static GHomeTLoginRet GetLoginRet()

3）示例代码

GHomeTLoginRet ret = GHomeTLogin.GetLoginRet();

退出登录

1）功能描述

游戏客户端可以在游戏内需要退出登录账号的地方调用该接口，执行成功将删除自动登录的记录信息，玩家下次登录后将不再自动登录，而是显示出登录界面。

2）接口声明

public static void Logout()

3）示例代码

GHomeTLogin.Logout();

绑定账号

1）功能描述

游戏客户端可以调用游客绑定接口为玩家提供游客绑定功能。

2）接口声明

public static void BindAcct()

3）示例代码

/// 注册监听
GHomeTLogin.BindRetEvent += OnBindAcctEvent;

/// 调用绑定
GHomeTLogin.BindAcct();

/// 绑定回调
void OnBindAcctEvent(GHomeTLoginRet bindRet)
    {
        if (bindRet.RetCode == GHomeTError.CODE_SUCCESS)
        {

            GHomeUtils.ShowToastUI(TAG + "绑定成功：" + GHomeUtils.DicToString(JsonConvert.DeserializeObject<Dictionary<string, string>>(JsonConvert.SerializeObject(bindRet))));
        }
        else
        {
            GHomeUtils.ShowToastUI(TAG + bindRet.RetMsg);
        }
    }


/// 销毁监听
private void OnDestroy()
{
    GHomeTLogin.BindRetEvent -= OnBindAcctEvent;
}

支付模块（必接）

一、概述

游戏客户端可以在购买道具的地方调用该接口。这将打开支付界面，引导玩家支付该订单。用户结束支付操作后，SDK会回调游戏客户端，告知支付结果是否已经成功。

二、API调用

注册回调

1）功能描述

接受 GHome 支付模块的回调，游戏需要注册回调函数进行处理

2）接口声明

/// GHomeSDK支付回调
public static event GHomeTEventHandler.OnGHomeTRetEventHandler<GHomeTBaseRet> PayRetEvent;

3）示例代码

/// 注册监听
GHomeT.PayRetEvent += OnPayRetEvent;

/// 回调
private void OnPayRetEvent(GHomeTBaseRet retD)
{
        if (retD.RetCode == GHomeTError.CODE_SUCCESS)
        {
            //支付成功逻辑
            GHomeUtils.ShowToastUI(TAG + retD.RetCode + "支付成功, msg: " + retD.RetMsg);
        }
        else
        {
            //支付失败逻辑
            GHomeUtils.ShowToastUI(TAG + retD.RetCode + ", msg: " + retD.RetMsg);
        }
}


/// 销毁监听
private void OnDestroy()
{
    GHomeT.PayRetEvent -= OnPayRetEvent;
}

调用支付

1）功能描述

调用接口，开始支付

2）接口声明

 public static void Pay(string orderId, string groupId, string areaId, string productId, string extend);

3）参数说明

参数名称	参数类型	说明
orderId	string	必传，游戏订单号。如果游戏需要记录订单号，可以传入唯一的字符串来标识此订单
groupId	string	必传，组ID。没有则传空串
areaId	string	必传，在GPOP发行运营平台(gpop.sdo.com)上设置的区服的ID ，区服ID不可为0
productId	string	必传，在GPOP发行运营平台(gpop.sdo.com)上设置的商品的ID
extend	string	可选，扩展参数，游戏可用于自行扩展，平台发货通知时将原样返回给游戏服务器

4）示例代码

long timeNow = (long)(DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc)).TotalMilliseconds;
string orderId = timeNow + "";
GHomeT.Pay("order" + orderId, GHConfig.GROUP_ID, GHConfig.AREA_ID, selectedProductId, "internationalPCdemoExtendInfo");

5）注意事项

由于可能发生网络延迟等等原因，有时候客户端返回的支付结果可能与实际情况有出入，所以最终订单是否支付成功，建议以平台服务器端的通知为准，客户端的通知结果仅作为参考。

扩展模块

获取游戏区服列表

一、概述

游戏客户端可以调用该接口获取游戏在GPOP发行运营平台(gpop.sdo.com)登记的区服配置信息。

二、API调用

注册回调

1）接口声明

public static event GHomeTEventHandler.OnGHomeTRetEventHandler<GHomeTGetAreaConfigRet> AreaListRetEvent;

2）示例代码

/// 注册监听
GHomeT.AreaListRetEvent += OnAreaListRetEvent;

/// 回调
private void OnAreaListRetEvent(GHomeTGetAreaConfigRet retD)
{
    if (retD != null)
    {
        foreach (GHAreaInfoDetail areaInfo in retD.areaList)
        {
        }
    }
}

/// 销毁监听
private void OnDestroy()
{
    GHomeT.AreaListRetEvent -= OnAreaListRetEvent;
}

3）数据结构

GHomeTGetAreaConfigRet详解

继承自GHomeTBaseRet，包含基础的信息

成员变量名称	类型	说明
areaList	List<GHAreaInfoDetail>	区服列表

GHAreaInfoDetail详解

成员变量名称	类型	说明
area_code	string	区服ID
name	string	区服名称
group_id	string	组ID
group_name	string	组名称

获取区服列表信息

1）接口声明

public static void GetAreaConfig();

2）示例代码

GHomeT.GetAreaConfig();

上报区服信息

1）接口声明

public static void SetLoginArea(string areaId, string groupId)

2）参数说明

参数名称	参数类型	说明
areaId	string	区服ID
groupId	string	组ID

3）示例代码

/// 上报选择的区服信息
GHomeT.SetLoginArea(selectedAreaId, selectedGroupId);

4）注意事项

游戏客户端需要在选择了区服之后调用该接口上报所选的区服信息

获取游戏商品列表

一、概述

游戏客户端可以调用该接口获取游戏在G家平台登记的支付商品配置。

二、API调用

注册回调

1）接口声明

public static event GHomeTEventHandler.OnGHomeTRetEventHandler<GHomeTGetProductConfigRet> ProductListRetEvent;

2）示例代码

/// 获取商品列表监听
GHomeT.ProductListRetEvent += OnGetProductListsEvent;

/// 回调
private void OnGetProductListsEvent(GHomeTGetProductConfigRet retD)
{
        if (retD != null)
        {
            foreach (GHProductInfoDetail productInfo in retD.productList)
            {
                Debug.Log("productName: " + productInfo.item_name);
            }
        }
}

/// 销毁监听
private void OnDestroy()
{
    GHomeT.ProductListRetEvent -= OnGetProductListsEvent;
}

3）数据结构

GHomeTGetProductConfigRet详解

继承自GHomeTBaseRet，包含基础的信息

成员变量名称	类型	说明
productList	List<GHProductInfoDetail>

GHProductInfoDetail详解

成员变量名称	类型	说明
item_name	string	商品名称
product_code	string	商品ID
money	float	金额（单位：元）

获取商品列表

1）接口声明

public static void GetProductConfig()

2）示例代码

GHomeT.GetProductConfig();

获取服务协议和隐私政策URL

一、概述

游戏客户端可以调用该接口获取到服务协议和隐私政策url

二、API调用

注册回调

1）接口声明

public static event GHomeTEventHandler.OnGHomeTRetEventHandler<GHomeTGetPrivacyRet> UrlRetEvent;

2）示例代码

/// 注册获取隐私政策url监听
GHomeT.UrlRetEvent += OnGetAgreementUrlEvent;

/// 回调
private void OnGetAgreementUrlEvent(GHomeTGetPrivacyRet retD)
{
        if (retD != null)
        {
            Debug.Log("servicerAgreement html Url: " + retD.serviceAgreementUrl);
            Debug.Log("privacyPolicy html url: " + retD.privacyPolicyUrl);

            if (agreementTypeClicked == 0)
            {
                GHFlowManager.Instance.ShowHtmlDlg(serviceUrl, "", false, null, null);
            }
            else
            {
                GHFlowManager.Instance.ShowHtmlDlg(privacyUrl, "", false, null, null);
            }
        }
}

/// 销毁监听
private void OnDestroy()
{
    GHomeT.UrlRetEvent -= OnGetAgreementUrlEvent;
}

获取服务协议和隐私政策

1）接口声明

public static void GetAgreementUrl()

2）示例代码

GHomeT.GetAgreementUrl();

设置语言

一、概述

国际化设置语言

二、API调用

1）接口声明

public static void SetLanguage(string language)

2）参数说明

参数名称	参数类型	说明
language	string	语言类型，GHomeTLanguage

GHomeTLanguage说明

    /// <summary>
    /// 支持的语言
    /// </summary>
    public sealed class GHomeTLanguage
    {
        /// <summary>
        /// 英文
        /// </summary>
        public const string EN = "en";

        /// <summary>
        /// 简体中文
        /// </summary>
        public const string ZH_CN = "zh-CN";

        /// <summary>
        /// 繁体中文
        /// </summary>
        public const string ZH_TW = "zh-TW";

        /// <summary>
        /// 韩文 
        /// </summary>
        public const string KO = "ko";

        /// <summary>
        /// 日文
        /// </summary>
        public const string JA = "ja";

        /// <summary>
        /// 泰文
        /// </summary>
        public const string TH = "th";

        /// <summary>
        /// 葡萄牙文
        /// </summary>
        public const string PT = "pt";
    
        /// <summary>
        /// 印度尼西亚
        /// </summary>
        public const string ID = "id";
    
        /// <summary>
        /// 意大利
        /// </summary>
        public const string IT = "it";

        /// <summary>
        /// 法语
        /// </summary>
        public const string FR = "fr";

        /// <summary>
        /// 德语
        /// </summary>
        public const string DE = "de";
    }

3）示例代码

GHomeT.SetLanguage(GHomeTLanguage.ZH_CN);

4）注意事项

如果您之前获取了用户协议和隐私政策，设置语言后，需要重新请求用户协议和隐私政策，获取对应语言下的用户协议和隐私政策

FAQ

错误码 GHomeTError

    /// <summary>
    /// 错误码
    /// </summary>
    public sealed class GHomeTError
    {
        // 成功
        public const int CODE_SUCCESS = 0;
        // 取消
        public const int CODE_CANCEL = 1;
        // api错误
        public const int CODE_API_ERROR = 2;
        // 初始化失败
        public const int CODE_INIT_FAILED = 3;
        // 用户未登录
        public const int CODE_USER_NOT_LOGIN = 4;
        // 支付失败
        public const int CODE_PAY_FAILED = 5;
        // 网络不稳定
        public const int CODE_NET_ERROR = 6;
        // 无法解码内容数据
        public const int CODE_PARSING_ERROR = 7;
        // 所以渠道均已绑定
        public const int CODE_BIND_ALL = 8;
        // 验证码错误
        public const int CODE_EMAIL_ERROR = -4100605;
        // TOKEN过期，需要重新登录
        public const int CODE_TOKEN_TIME_OUT = -4101010;
    }

错误码	描述	备注
0	成功
1	取消	登录取消、支付取消
2	api错误	预留
3	初始化失败	可根据失败原因RetMsg进行该接口的重新接入，无法确认可联系G家
4	用户未登录	先确认该接口是否在登录成功之后调用，如果是还依然有该问题请联系G家
5	支付失败	如遇到RetMsg无法自行确认并修复的支付错误请联系G家排查
6	网络不稳定	网络不稳定，请检查网络
7	无法解码内容数据	相关接口响应数据格式错误，不符合JSON格式,请联系G家解决
8	所有渠道均已绑定	所有渠道均已绑定
-4100605	验证码错误	预留
-4101010	TOKEN过期，需要重新登录	TOKEN过期，需要重新登录，建议回到登录界面

常见问题

• 由于unity不支持web页面，目前导入的是Embedded_Browser_3.1.0.unitypackage第三方插件包，加载第三方链接的时候，有概率会被第三方拦截。目前发现的拦截情况是在进行Google登录的时候，插件原userAgent会被谷歌拦截，目前修改了源码中的userAgent，但不保证之后谷歌升级安全策略，再次进行登录拦截。
• Facebook三方登录：如果您尝试使用与帐户注册国家不同的IP进行手机号登录Facebook帐户，Facebook可能会发出“密码不正确”之类的错误，但实际上，密码是正确的。建议使用邮箱或者更换和登录IP国家相符的手机号尝试进行登录。