海外游戏对接文档--PC
版本
当前版本及SDK下载
客户端 Unity
最新版本 1.0.01 下载地址
一. 集成SDK
1.1 手动集成
- 下载 Unity SDK 资源文件
- 双击 .unitypackage 文件 或者通过Assets > Import Package > Custom Package,导入.unitypackage
- 安装 Newtonsoft.Json,菜单栏:Window > Package Manager > 点击左上角的 + 按钮,选择 Add package from git URL... > 输入:com.unity.nuget.newtonsoft-json > 点击 Add
- 工程下面需要新建个Canvas,这个Canvas的大小会影响我们登录等UI显示,如果没有这个Canvas将无法显示登录等界面。
1.2 必需信息
客户端参数:
找运营获取当前项目配置文件 NeoriginSDKConfig.txt,并进行替换,替换位置: Assets/SDKScripts/Resources/NeoriginSDKConfig.txt
Xsolla参数:
如果接的是官网包,则需要用到xsolla参数,位置:Window > Xsolla > Edit Settings。勾选 Pack In-App Broswer。注意:正式包不要勾选Test Payments Mode是沙盒环境
参数 类型 参数描述 Project ID string Xsolla发布商帐户中项目名称旁边找到的项目ID,如254833 Login ID string Xsolla登录管理器项目的ID,如54d1568b-4dde-11ec-bc85-42010aa80004 OAuth Client ID string Xsolla发布商帐户的玩家 > 登录管理器 > 您的登录管理器项目 > 安全性 > OAuth 2.0中找到的OAuth 2.0客户端ID,如13605 Callback URL string neorigin主体为:https://pc-api.neorigin.com metajoy主体为:https://pc-api.metajoygames.com 服务端参数:
参数 类型 参数描述 AppSecret string 支付回调时用来验证签名
1.3 整体功能介绍
功能 | 是否必接 | 前提 | 作用 |
---|---|---|---|
2.2 初始化Init | 必接 | 无 | SDK初始化 |
2.3 登录LoginAccount | 必接 | 2.2 | 登录账号,初始化后,创建角色前 |
2.4 登录态登录Login | 2.2 | 游客登录,初始化后,创建角色前;无游客则接2.3 | |
2.5 拉起用户中心OpenUserCenter | 必接 | 2.3 或 2.4 | 打开用户中心 |
2.6 获取商品列表GetPayItems | 2.2 | 用于做支付商品本地化展示 | |
2.7 支付Pay | 必接 | 2.7中的登录角色后 | 应用内支付 |
2.8 上报发行指定行为数据SubmitExtraData | 必接 | 一般在2.3 或 2.4,特殊事件咨询sdk技术 | 上报游戏必要信息:创建角色、登录角色、切换角色 |
2.9 游戏上报数数方法SubmitTAUserInfo | 2.2 | 按业务要求上报数数 | |
2.10 获取用户信息GetUserInfo | 2.3 或 2.4 | 获取登录后的用户信息 | |
2.11 打开隐私协议OpenPolicy | 2.2 | 打开隐私协议 | |
2.12 打开客服界面OpenCustomerService | 2.2 | 打开客服界面 | |
2.13 退出登录状态Logout | 2.2 | 退出登录状态 |
二、功能对接
2.1 公共部分
- 回调返回值
参数 | 类型 | 参数描述 |
---|---|---|
code | NeoriginSDKStatusCode | 状态码 NeoriginSDKStatusCode.Success 为成功 |
msg | string | 文本信息 |
data | 接口定义 | 接口定义 |
2.2 初始化Init
说明 必接,SDK初始化方法,这是调所有SDK方法的前置方法,所有SDK必需在初始化成功回调后调用
方法Init定义
public void Init(NeoriginSDKParamsInit initData, InitCallBack callBack = null)
- 参数NeoriginSDKParamsInit定义
public class NeoriginSDKParamsInit
{
public string gameVersion; // 游戏版本号
}
- 回调函数InitCallBack定义
InitCallBack(NeoriginSDKStatusCode code = NeoriginSDKStatusCode.Success, string msg = "", NeoriginSDKCallbackDataInit data = null);
public class NeoriginSDKCallbackDataInit
{
}
- 示例代码
using NeoriginPCSDK;
var initParam = new NeoriginSDKParamsInit()
{
gameVersion = "1.0.666", // 游戏版本号
isDebug = false //调试状态,正式包传false
};
NeoriginSDK.Instance.Init(initParam, (code, msg, result) =>
{
Debug.Log($"Init result: {code}, Message: {msg}");
});
2.3 登录LoginAccount
- 说明
必接,SDK登录方法,检测本地是否有登录态,有则直接用登录态登录,没有则拉起平台登录
- 方法Login定义
public void LoginAccount(NeoriginSDKParamsLogin loginParams,LoginAccountCallBack callBack = null)
- 参数NeoriginSDKParamsLogin定义
public class NeoriginSDKParamsLogin
{
public string account; // 用户标识,如果游戏想使用自己的用户标识,且touristFlag为1时传值,否则传空字符串
public int touristFlag; // 是否允许游客登录,"1"允许,"0"不允许,默认"0"
public int loginType; // 登录类型,"1"仅拉起登录框,"0"先检测本地登录态,再拉起登录框,,默认"0"
}
- 回调函数LoginCallBack定义
LoginAccountCallBack(NeoriginSDKStatusCode code = NeoriginSDKStatusCode.Success, string msg = "", NeoriginSDKCallbackDataLoginAccount data = null);
public class NeoriginSDKCallbackDataLoginAccount
{
public long userID;//U8用户id,如果不需要打通可以用这个作为用户标识
public string username;//U8用户名
public string sdkUserID;//平台用户id,如果需要打通可以用这个作为用户标识,推荐用这个
public string sdkUserName;//平台用户名
public string sdkLogUserId;//记录日志时使用的sdkUserID,游戏不需要用
public string sdkLogThirdUserName;//记录日志时使用的三方登录用户名,大部分没有,邮箱的时候有
public string token;//登录状态,用于服务端验证
public int isNew;//是否新用户,1为新用户
public int thirdLoginType;//最近三方账号登录类型,1google,6邮箱
public int callbackFrom; // 信息返回来源类型,0自动登录,1登录界面登录,2切换界面登录,3用户中心,4获取用户信息
}
```+
- 示例代码
```C#
using NeoriginPCSDK;
NeoriginSDKParamsLogin loginParam = new NeoriginSDKParamsLogin
{
account = "",
touristFlag = 0, //不允许游客登录
loginType = 0
};
NeoriginSDK.Instance.LoginAccount(loginParam, (code, msg, result) =>
{
Debug.Log($"Login result: {code}, Message: {msg}");
});
2.4 登录态登录Login
- 说明
SDK登录态登录方法,之前登录过的用户会在本地缓存登录态,调这个方法可以直接完成登录,也可以使用游客登录,如果游戏必须要平台账号登录,建议使用2.3 登录LoginAccount
- 方法Login定义
public void Login(NeoriginSDKParamsLogin loginData, LoginCallBack callBack = null)
- 参数NeoriginSDKParamsLogin定义
如果游客用户标识需要游戏传,则需要传,否则传空字符串
public class NeoriginSDKParamsLogin
{
public string account; // 用户标识,如果游戏想使用自己的用户标识,且touristFlag为1时传值,否则传空字符串
public int touristFlag; // 是否允许游客登录,"1"允许,"0"不允许,默认"0"
public int loginType; // 登录类型,"1"仅拉起登录框,"0"先检测本地登录态,再拉起登录框,,默认"0"
}
- 回调函数LoginCallBack定义
LoginCallBack(NeoriginSDKStatusCode code = NeoriginSDKStatusCode.Success, string msg = "", NeoriginSDKCallbackDataLogin data = null);
public class NeoriginSDKCallbackDataLogin
{
public long userID;//U8用户id,如果不需要打通可以用这个作为用户标识
public string username;//U8用户名
public string sdkUserID;//平台用户id,如果需要打通可以用这个作为用户标识,推荐用这个
public string sdkUserName;//平台用户名
public string sdkLogUserId;//记录日志时使用的sdkUserID,游戏不需要用
public string sdkLogThirdUserName;//记录日志时使用的三方登录用户名,大部分没有,邮箱的时候有
public string token;//登录状态,用于服务端验证
public int isNew;//是否新用户,1为新用户
public int thirdLoginType;//最近三方账号登录类型,1google,6邮箱
public int callbackFrom; // 信息返回来源类型,0自动登录,1登录界面登录,2切换界面登录,3用户中心,4获取用户信息
}
- 示例代码
using NeoriginPCSDK;
NeoriginSDKParamsLogin loginParam = new NeoriginSDKParamsLogin
{
account = "",
touristFlag = 0, //不允许游客登录
loginType = 0
};
NeoriginSDK.Instance.Login(loginParam, (code, msg, result) =>
{
Debug.Log($"Login result: {code}, Message: {msg}");
});
2.5 拉起用户中心OpenUserCenter
- 说明
SDK拉起用户中心,必须在2.2或2.3登录成功后调用才有效
- 方法Login定义
public void OpenUserCenter(OpenUserCenterCallBack callBack = null)
- 回调函数OpenUserCenterCallBack定义
OpenUserCenterCallBack(NeoriginSDKStatusCode code = NeoriginSDKStatusCode.Success, string msg = "", NeoriginSDKCallbackDataLoginAccount data = null);
public class NeoriginSDKCallbackDataLoginAccount
{
public long userID;//U8用户id,如果不需要打通可以用这个作为用户标识
public string username;//U8用户名
public string sdkUserID;//平台用户id,如果需要打通可以用这个作为用户标识,推荐用这个
public string sdkUserName;//平台用户名
public string sdkLogUserId;//记录日志时使用的sdkUserID,游戏不需要用
public string sdkLogThirdUserName;//记录日志时使用的三方登录用户名,大部分没有,邮箱的时候有
public int isNew;//是否新用户,1为新用户
public int thirdLoginType;//最近三方账号登录类型,1google,6邮箱
public int callbackFrom; // 信息返回来源类型,0自动登录,1登录界面登录,2切换界面登录,3用户中心,4获取用户信息
}
- 示例代码
using NeoriginPCSDK;
NeoriginSDK.Instance.OpenUserCenter( (code, msg, result) =>
{
Debug.Log($"OpenUserCenter result: {code}, Message: {msg}");
});
2.6 获取三方商店商品信息列表GetPayItems
- 说明
SDK获取商品列表方法,用于展示商品的当前货币和本地化信息等
- 方法GetPayItems定义
public void GetPayItems(GetPayItemsCallBack callBack = null)
- 回调函数GetPayItemsCallBack定义
GetPayItemsCallBack(NeoriginSDKStatusCode code = NeoriginSDKStatusCode.Success, string msg = "", NeoriginSDKCallbackDataPayItem[] data = null);
public class NeoriginSDKCallbackDataPayItem
{
public string product_id; // 商品标识,同商店、发行后台
public float price; // 价格
public string symbol; // 货币符号,在xsolla中同货币代码
public string title; // 商品名称
public string localizedDescription; // 商品本地化描述
public string countryCode; // 国家代码
public string priceCurrencyCode; // 货币代码
}
- 示例代码
using NeoriginPCSDK;
NeoriginSDK.Instance.GetPayItems( (code, msg, result) =>
{
Debug.Log($"GetPayItems result: {code}, Message: {msg}");
if (code == NeoriginSDKStatusCode.Success && result != null)
{
foreach (var item in result)
{
Debug.Log($"SDK GetPayItems: product_id={item.product_id}, price={item.price}, symbol={item.symbol}, title={item.title}, localizedDescription={item.localizedDescription}, countryCode={item.countryCode}, priceCurrencyCode={item.priceCurrencyCode}");
}
}
else
{
Debug.Log($"GetPayItems result: {code}, Message: {msg}");
}
});
2.7 支付Pay
- 说明
SDK支付方法,拉起平台支付
- 时序图
- 方法Pay定义
public void Pay(NeoriginSDKU8PayData payParams, PayCallBack callBack = null)
- 参数NeoriginSDKU8PayData定义
public class NeoriginSDKU8PayData
{
public string productId; // 商品ID,同google等后台配置的商品标识
public string productName; // 商品名称,比如100元宝,500钻石...
public string productDesc; // 商品描述
public double price; // 充值金额,单位:美分
public int buyNum; // 购买数量,一般都是1
public int coinNum; // 玩家当前身上剩余的游戏币
public string serverId; // 玩家所在服务器的ID
public string serverName; // 玩家所在服务器的名称
public string roleID; // 玩家角色ID
public string roleName; // 玩家角色名称
public string roleLevel; // 玩家角色等级
public string vip; // 玩家vip等级
public string payNotifyUrl; // 游戏服务器支付回调地址,渠道SDK支付成功,异步通知U8Server,U8Server根据该地址,通知游戏服务器发货,如果传了用这个地址回调,不传则用后台配置的回调
public string paySubNotifyUrl; // 游戏服务器订阅支付回调地址,渠道SDK支付成功,异步通知U8Server,U8Server根据该地址,通知游戏服务器发货,如果传了用这个地址回调,不传则用后台配置的回调
public string extension; // 自定义字段,支付成功之后,回调通知游戏服务器时,原样返回给游戏服务器,长度不超过255
public string skuType; // 商品类型,订阅商品"subs";普通商品"inapp",google支付用到,其余支付不会用到,默认"inapp"
}
- 回调函数PayCallBack定义
PayCallBack(NeoriginSDKStatusCode code = NeoriginSDKStatusCode.Success, string msg = "", NeoriginSDKCallbackDataPay data = null);
public class NeoriginSDKCallbackDataPay
{
public int state; // 支付成功0
public string extension;//回传参数
public string order_id;//订单id
}
- 示例代码
using NeoriginPCSDK;
NeoriginSDKU8PayData payParams = new NeoriginSDKU8PayData
{
productId = "demopaid_1",
productName = "1元宝",
productDesc = "1元宝哦",
price = 299,
buyNum = 1,
coinNum = 299,
serverId = "1",
serverName = "server001",
roleID = "10000001",
roleName = "role001",
roleLevel = "10",
vip = "2",
payNotifyUrl = "",
paySubNotifyUrl = "",
extension = "orderId:111111",
skuType = "inapp"
};
NeoriginSDK.Instance.Pay(payParams, (code, msg, result) =>
{
Debug.Log($"Pay result: {code}, Message: {msg}");
});
2.8 上报发行指定行为数据SubmitExtraData
- 说明
上报创建角色、登录角色等指定行为数据,创建角色TYPE_CREATE_ROLE和登录角色TYPE_LOGIN_ROLE上报必接,其他行为视游戏要求
- 方法SubmitExtraData定义
public void SubmitExtraData(NeoriginSDKU8UserExtraData extraData, SubmitExtraDataCallBack callBack = null)
- 参数NeoriginSDKU8UserExtraData定义
public class NeoriginSDKU8UserExtraData
{
public NeoriginSDKU8UserExtraDataType dataType; // 调用时机,数据类型
public string serverID; // 玩家所在服务器的ID
public string serverName; // 玩家所在服务器的名称
public string roleID; // 玩家角色ID
public string roleName; // 玩家角色名称
public string roleLevel; // 玩家角色等级
public string moneyNum; // 当前角色身上拥有的游戏币数量
public long roleCreateTime; // 角色创建时间戳,单位秒
public long roleLevelUpTime; // 角色等级变化时间戳,单位秒
public string vip; // 玩家vip等级
public string loadingEvent; //可不传
public string eventName; // 可不传,事件名,当dataType值为TYPE_OTHER_EVENT时必填
public string param; // 可不传
public Dictionary<string, string> customData; // 可不传,自定义数据,格式:{'key':'value', 'key':'value'}
public List<string> userTags; // 可不传,用户标签
}
public enum NeoriginSDKU8UserExtraDataType
{
None = 0, //异常值
TYPE_SELECT_SERVER = 1, //选择服务器
TYPE_CREATE_ROLE = 2,//创建角色,必接
TYPE_ENTER_GAME = 3,//进入游戏
TYPE_LEVEL_UP = 4, //角色升级
TYPE_EXIT_GAME = 5, //退出游戏
TYPE_SHOW_RV = 6, //展示激励视频
TYPE_DEVICE_START = 7, //设备启动
TYPE_LOGIN_PID = 8, //登录平台成功
TYPE_BIND_ACCOUNT = 9, //绑定账号成功
TYPE_DEVICE_ENTER_GAME = 10, //设备进入游戏
TYPE_DEVCIE_ENTER_SERVER = 11, //设备进入服务器
TYPE_OTHER_EVENT = 12, //其他事件上报
TYPE_TUTORIAL_COMPLETION = 13, //新手引导完成
TYPE_LOGIN_ROLE = 14, //角色登录,必接
TYPE_DEVICE_LOAD = 15, //设备加载过程,可能会分几步,所以此上报需要填写lodingEvent字段录角色
TYPE_RETENTION_2 = 16, //留存2天
TYPE_RETENTION_3 = 17, //留存3天
TYPE_CHANGE_ROLE = 18 //角色切换
}
- 回调函数SubmitExtraDataCallBack定义
SubmitExtraDataCallBack(NeoriginSDKStatusCode code = NeoriginSDKStatusCode.Success, string msg = "", string data = "");;
- 示例代码
using NeoriginPCSDK;
NeoriginSDKU8UserExtraData data = new NeoriginSDKU8UserExtraData
{
dataType = NeoriginSDKU8UserExtraDataType.TYPE_CREATE_ROLE,
roleID = "1",
roleName = "role1",
roleLevel = "1",
serverID = "10001",
serverName = "server001",
moneyNum = "0",
roleCreateTime = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
roleLevelUpTime = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
vip = "1"
};
NeoriginSDK.Instance.SubmitExtraData(data,(code, msg, result) =>
{
Debug.Log($"CreateRoleButton result: {code}, Message: {msg}");
});
NeoriginSDKU8UserExtraData data = new NeoriginSDKU8UserExtraData
{
dataType = NeoriginSDKU8UserExtraDataType.TYPE_LOGIN_ROLE,
roleID = "1",
roleName = "role1",
roleLevel = "1",
serverID = "10001",
serverName = "server001",
moneyNum = "10",
roleCreateTime = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
roleLevelUpTime = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
vip = "2"
};
NeoriginSDK.Instance.SubmitExtraData(data,(code, msg, result) =>
{
Debug.Log($"LoginRoleButton result: {code}, Message: {msg}");
});
2.9 游戏上报数数方法SubmitTAUserInfo
- 说明
上报数数,根据业务要求游戏埋点上报数数调用此方法,2.5中创建角色、登录角色、切换角色三个事件不用单独上报,2.5中已上报。
- 方法SubmitTAUserInfo定义
public void SubmitTAUserInfo(int eventType, string eventId, Dictionary<string, object> properties, SubmitTAUserInfoCallBack callBack = null)
- 参数定义
int eventType;//0表示事件上报;1表示用户属性set,可以覆盖;2表示用户属性setOnce,不可以覆盖,以第一次设置为准;3表示要上传数值型的属性时,您可以调用 UserAdd 来对该属性进行累加操作,可传负数,表示相减;6表示一次性事件上报,针对用户只会记录一次的事件。
string eventId;//事件Id,eventType=0或6时有用
Dictionary<string, object> properties;//属性,每个类型都有用到,属性名对应属性值
- 回调函数SubmitTAUserInfoCallBack定义
SubmitTAUserInfoCallBack(NeoriginSDKStatusCode code = NeoriginSDKStatusCode.Success, string msg = "", string data = "");
- 示例代码
using NeoriginPCSDK;
//上报事件
Dictionary<string, object> dic = new Dictionary<string, object>();
dic.Add("role_id", extraData.roleID);
dic.Add("role_name", extraData.roleName);
dic.Add("server_name", extraData.serverName);
dic.Add("server_id", extraData.serverID);
dic.Add("mj_channel", sdkConfig.sdk.u8ChannelId);
dic.Add("SDKID", platformUserInfo.displayName);
SubmitTAUserInfo(0, "mj_pc_create_role", dic, (code, msg, data) =>
{
Debug.Log("SubmitTAUserInfo TYPE_CREATE_ROLE code: " + code + ", msg: " + msg);
});
//设置用户属性
Dictionary<string, object> roleOnceDic = new Dictionary<string, object>();
roleOnceDic.Add("mj_role_id", extraData.roleID);
roleOnceDic.Add("mj_rolename", extraData.roleName);
roleOnceDic.Add("mj_server_id", extraData.serverID);
roleOnceDic.Add("mj_register_platform", "PC");
NeoriginSDKDevice device = NeoriginSDKStorage.LoadDevice();
roleOnceDic.Add("mj_device_number", device.deviceID);
string roleCreateTime = System.DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss.fff");
roleOnceDic.Add("mj_role_create_time", roleCreateTime);
roleOnceDic.Add("mj_version_sdk", pcSdkVersion);
roleOnceDic.Add("mj_channel_id", sdkConfig.sdk.u8ChannelId);
roleOnceDic.Add("mj_version_game", gameVersion);
SubmitTAUserInfo(2, "", roleOnceDic, (code, msg, data) =>
{
Debug.Log("SubmitTAUserInfo TYPE_CREATE_ROLE UserSetOnce code: " + code + ", msg: " + msg);
});
2.10 获取用户信息GetUserInfo
- 说明
获取用户信息,此方法必须在已经LoginAccount或者Login回调成功后使用
- 方法GetUserInfo定义
public void GetUserInfo(GetUserInfoCallBack callBack = null)
- 回调函数GetUserInfoCallBack定义
GetUserInfoCallBack(NeoriginSDKStatusCode code = NeoriginSDKStatusCode.Success, string msg = "", NeoriginSDKCallbackDataUserCenter data = null);
public class NeoriginSDKCallbackDataUserCenter
{
public long userID;//U8用户id,如果不需要打通可以用这个作为用户标识
public string username;//U8用户名
public string sdkUserID;//平台用户id,如果需要打通可以用这个作为用户标识,推荐用这个
public string sdkUserName;//平台用户名
public string sdkLogUserId;//记录日志时使用的sdkUserID,游戏不需要用
public string sdkLogThirdUserName;//记录日志时使用的三方登录用户名,大部分没有,邮箱的时候有
public int isNew;//是否新用户,1为新用户
public int thirdLoginType;//最近三方账号登录类型,1google,6邮箱
public int callbackFrom; // 信息返回来源类型,0自动登录,1登录界面登录,2切换界面登录,3用户中心,4获取用户信息
}
- 示例代码
using NeoriginPCSDK;
NeoriginSDK.Instance.GetUserInfo( (code, msg, result) =>
{
string resultMsg = JsonUtility.ToJson(result);
Debug.Log($"GetUserInfo result: {code}, Message: {msg},Data: {resultMsg?.ToString()}");
});
2.11 打开隐私协议OpenPolicy
- 说明
打开隐私协议页面
- 方法OpenPolicy定义
public void OpenPolicy(OpenPolicyCallBack callBack = null)
- 回调函数OpenPolicyCallBack定义
OpenPolicyCallBack(NeoriginSDKStatusCode code = NeoriginSDKStatusCode.Success, string msg = "", string data = null);
- 示例代码
using NeoriginPCSDK;
NeoriginSDK.Instance.OpenPolicy((code, msg, result) =>
{
Debug.Log($"OpenPolicy result: {code}, Message: {msg}");
});
2.12 打开客服界面OpenCustomerService
- 说明
打开客服页面
- 方法OpenCustomerService定义
public void OpenCustomerService(OpenCustomerServiceCallBack callBack = null)
- 回调函数OpenCustomerServiceCallBack定义
OpenCustomerServiceCallBack(NeoriginSDKStatusCode code = NeoriginSDKStatusCode.Success, string msg = "", string data = null);
- 示例代码
using NeoriginPCSDK;
NeoriginSDK.Instance.OpenCustomerService((code, msg, result) =>
{
Debug.Log($"OpenCustomerService result: {code}, Message: {msg}");
});
2.13 退出登录状态Logout
- 说明
退出登录状态,会把SDK本地的登录缓存清除
- 方法Logout定义
public void Logout(LogoutCallBack callBack = null)
- 回调函数LogoutCallBack定义
LogoutCallBack(NeoriginSDKStatusCode code = NeoriginSDKStatusCode.Success, string msg = "", string data = null);
- 示例代码
using NeoriginPCSDK;
NeoriginSDK.Instance.Logout((code, msg, result) =>
{
Debug.Log($"Logout result: {code}, Message: {msg}");
});