西瓜SDK Unity3D 客户端接口说明

1 文档概述

此文档为Unity3D引擎客户端接入XGSDK接口说明文档,共包括3种类型的接口:基础接口、渠道扩展接口、数据统计接口。

1.1 文档结构

  1. 文档概述
  2. 接口说明
  3. 渠道接入要点须知

2 接口说明

注:所有必接接口必须接入,否则会导致客户端功能不能正常使用。

2.1 初始化设置

2.1.1 通知Android / iOS初始化回调方法
    public static void setCallback()

接口说明:

设置UserCallBack,SDK初始化、用户登录、支付结果的回调都会通知到此对象。

注意:必须在第一个场景的Start方法中调用
原因说明:CreateSDKManager和setCallback的调用顺序是不能改变的。在第一个场景的Awake方法中调用CreateSDKManager,在Start方法中调用setCallback方法。之所以这么做,是因为必须要先初始化Unity3D引擎层的接受回调的gameObject对象,而且在setCallback方法执行后,会调用Android / iOS初始化回调方法,所以CreateSDKManager必须在setCallback之前调用。

代码样例:

void Start(){
    XGSDK2.instance.setCallback();
}

2.1.2 Unity3D引擎层创建回调接受对象
    public static void CreateSDKManager()

接口说明:

配置回调方法
注意:必须在第一个场景的Awake方法中调用

代码样例

void Awake()
{
    XGSDKCallbackWrapper.CreateSDKManager();
}

2.1.3 实现回调方法

游戏需要在 <项目目录>\Assets\XGSDK\XGSDKCallbackImpl.cs 类中 完成对所需回调的实现,具体回调说明请参照以下接口

2.1.4 初始化成功回调
    public abstract void onInitSuccess(int code, string msg, string channelCode);

回调说明:

当SDK初始化成功时,游戏会收到此回调,游戏可以在此回调中实现初始化成功后的逻辑。

参数说明:

  1. code(int):返回的错误码,详情请见错误码表
  2. msg(string):返回的信息
  3. channelCode(string):渠道的错误码

2.1.5 初始化失败回调
    public abstract void onInitFail(int code, string msg,string channelCode);

回调说明:

当SDK初始化失败时,游戏会收到此回调,游戏可以在此回调中实现初始化失败后的逻辑。

参数说明:

  1. code(int):返回的错误码,详情请见错误码表
  2. msg(string):返回的信息
  3. channelCode(string):渠道的错误码

2.2 基础接口

2.2.1 登录接口(必接)
    public static void login(string customParams)

接口说明:

登录时调用,此接口将调出渠道的登录界面。

参数说明:

该参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可。

代码样例:

    XGSDK2.instance.login("");

回调方法:

  • 登录成功回调
    public abstract void onLoginSuccess(int code, string authInfo);

回调说明:

登录成功之后,会收到登录成功回调,游戏在此回调中实现登录成功后的逻辑。

参数说明:

  1. code(int):返回的错误码,详情请见错误码表
  2. authInfo(string):用户验证信息(因为部分渠道的authInfo比较长,建议游戏预留2048长度
  • 登录取消回调
    public abstract void onLoginCancel(int code, string msg);

回调说明:

当用户取消登录之后,会受到登录取消的回调,游戏在此回调中实现登录取消后的逻辑。

参数说明:

  1. code(int):返回的错误码,详情请见错误码表
  2. msg(string):返回的信息
  • 登录失败回调
    public abstract void onLoginFail(int code, string msg, string channelCode);

回调说明:

登录失败后,会收到登录失败的回调,游戏在此回调中实现登录失败后的逻辑。

参数说明:

  1. code(int):返回的错误码,详情请见错误码表
  2. msg(string):返回的信息
  3. channelCode(string):渠道错误码

2.2.2 登出接口
    public static void logout(string customParams)

接口说明:

登出时调用,此接口将调用渠道的登出方法。

参数说明:

该参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可。

代码样例:

    XGSDK2.instance.logout("");

回调方法:

  • 登出成功回调
    public abstract void onLogoutFinish(int code, string msg);

回调说明:

登出成功后,会收到登出成功的回调,游戏在此回调中实现登出成功后的逻辑。

参数说明:

  1. code(int):返回的完成码,详情请见登出完成码表
  2. msg(string):返回的信息

2.2.3 支付接口(必接)
    public static void pay(PayInfo payInfo)

接口说明:

支付时调用,此接口将会发起用户充值,系统会调用对应渠道SDK充值界面。

参数说明:
1. 所有必须字段不能为空,否则会导致部分渠道无法支付;
2. 请严格按照西瓜规定的字段长度进行设置,否则可能导致支付异常。

参数 参数类型 最大长度 说明 必须
uid String 128 游戏必须使用登录时西瓜服务器返回的uid Y
productId String 64 产品ID,如果西瓜后台有商品配置则必须保持一致 Y
productName String 64 游戏必须使用真实的产品名称,建议中文 Y
productDesc String 128 商品描述:不能为空、不能包含特殊字符,包括 # " & / ? $ ^ *:) \ < > | , = 回车 换行,否则部分渠道无法拉起支付 Y
productUnit String 64 产品单位,必须使用真实的单位,,建议中文,例如元宝 Y
productUnitPrice int 10 商品单价,单位分(无需传,以后版本会去掉) N
productQuantity int 10 产品数量,例如购买60元宝则传60 Y
totalAmount int 10 产品总额,单位分 Y
payAmount int 10 实际支付总额,单位分 Y
currencyName String 64 海外渠道必传:实际支付的国际标准货币代码,比如CNY(人民币)/USD(美元) Y
roleId String 32 角色ID Y
roleName String 64 角色名称 Y
roleLevel int 32 角色等级 Y
roleVipLevel String 32 角色vip等级 N
serverId String 32 服ID:必须为纯数字,且不能超过2147483647(应用宝渠道要求) Y
zoneId String 32 区ID Y
partyName String 32 帮会名称 N
customInfo String 2000 扩展字段,订单支付成功后,透传给游戏 N
gameTradeNo String 64 游戏订单ID,支付成功后,透传给游戏 N
gameCallbackUrl String 128 支付回调地址,如果为空,则后台配置的回调地址 N
additionalParams String - 透传参数 N
virtualCurrencyBalance String 32 虚拟货币余额,需要此字段的渠道:快发、小米、VIVO Y
支付场景

场景一: 80元购买750钻石,创建订单参数是:

productId com.mygame.xxx
payAmount 实际支付总额(单位分) 8000
totalAmount 商品总金额(单位分) 8000
productName 商品名称 750钻石
productQuantity 商品数量 750
productUnit 商品单位 钻石
productUnitPrice 商品单价(单位分) 无需传

场景二: 促销优惠:68元购买750钻石,创建订单参数是:

productId com.mygame.xxx
payAmount 实际支付总额(单位分) 6800
totalAmount 商品总金额(单位分) 8000(原价)
productName 商品名称 750钻石
productQuantity 商品数量 750
productUnit 商品单位 钻石
productUnitPrice 商品单价(单位分) 无需传

场景三: 30元购买1月卡,创建订单参数是:

productId com.mygame.yyy
payAmount 实际支付总额(单位分) 3000
totalAmount 商品总金额(单位分) 3000
productName 商品名称 月卡
productQuantity 商品数量 1
productUnit 商品单位 月卡
productUnitPrice 商品单价(单位分) 无需传

代码样例:

    XGSDK2.instance.pay(payinfo);

回调方法:

  • 支付成功回调
    public abstract void onPaySuccess(string payResult);

回调说明:

支付成功后,会收到支付成功的回调,游戏在此回调中实现支付成功后的逻辑。

参数说明:

返回的参数payResult是一个json,解析之后有如下参数:

  • code:返回的支付结果,详情请见错误码表
  • msg:错误信息
  • xgTradeNo:西瓜创建的支付订单ID
  • gameTradeNo:游戏传入的订单ID
  • channelCode:渠道支付结果
  • channelMsg:渠道错误信息
  • 支付取消回调
    public abstract void onPayCancel(string payResult);

回调说明:

支付取消后,会收到支付取消回调,游戏在此回调中实现支付取消后的逻辑。

参数说明:

返回的参数payResult是一个json,解析之后有如下参数:

  1. code:返回的支付结果,详情请见错误码表
  2. msg:错误信息
  3. xgTradeNo:西瓜创建的支付订单ID
  4. gameTradeNo:游戏传入的订单ID
  5. channelCode:渠道支付结果
  6. channelMsg:渠道错误信息
  • 支付失败回调
    public abstract void onPayFail(string payResult);

回调说明:

支付失败后,会收到支付失败的回调,游戏在此回调中实现支付失败后的逻辑。

参数说明:

返回的参数payResult是一个json,解析之后有如下参数:

  1. code:返回的支付结果,详情请见错误码表
  2. msg:错误信息
  3. xgTradeNo:西瓜创建的支付订单ID
  4. gameTradeNo:游戏传入的订单ID
  5. channelCode:渠道支付结果
  6. channelMsg:渠道错误信息
  • 支付结果未知回调
    public abstract void onPayOthers(string payResult);

回调说明:

当支付结果未知的时候,会收到支付结果未知的回调,游戏在此实现支付结果未知时的逻辑。

参数说明:

返回的参数payResult是一个json,解析之后有如下参数:

  1. code:返回的支付结果,详情请见错误码表
  2. msg:错误信息
  3. xgTradeNo:西瓜创建的支付订单ID
  4. gameTradeNo:游戏传入的订单ID
  5. channelCode:渠道支付结果
  6. channelMsg:渠道错误信息
  • 支付正在进行回调
    public abstract void onPayProgress(string payResult);

回调说明:

当支付正在进行,尚未完成的时候,可能会收到支付过程中的回调,游戏在此实现支付过程中的逻辑。

参数说明:

返回的参数是一个json,解析之后有如下参数:

  1. code:返回的支付结果,详情请见错误码表
  2. msg:错误信息
  3. xgTradeNo:西瓜创建的支付订单ID
  4. gameTradeNo:游戏传入的订单ID
  5. channelCode:渠道支付结果
  6. channelMsg:渠道错误信息

2.2.3 退出接口(必接)
    public static void exit(string customParams)

接口说明:

退出时调用,此接口将调用西瓜的退出方法:如果渠道有退出弹窗,点击确定会回调doExit给游戏;如果没有渠道弹窗,则会回调onNoChannelExiter给游戏。 一般游戏中监听返回按键或者退出按钮来调用此接口,预期效果:或者出现渠道的退出弹窗,或者出现游戏的退出弹窗。

参数说明:

customParams参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可。

代码样例:

    XGSDK2.instance.exit("");

回调方法:

  • 直接退出回调
    public abstract void doExit(string msg);

回调说明:

渠道退出弹窗点击确认后,游戏会收到此回调,此回调中游戏不需要实现自己的退出弹窗,需要直接销毁资源退出游戏。

参数说明:

参数msg无意义。

  • 使用游戏方退出回调
    public abstract void onNoChannelExiter(string msg);

回调说明:

渠道没有退出弹窗时,游戏会收到此回调,此回调中游戏需要实现自己的退出弹窗,处理用户退出操作。

参数说明:

参数msg无意义。

2.2.4 释放资源接口(必接)
        public static void releaseResource(string customParams)

接口说明:

用户点击退出时释放资源

参数说明:

customParams参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可。

2.2.5 获取渠道ID
    public static string getChannelId()

接口说明:

获取渠道ID时使用。渠道ID列表请点击渠道ID列表

返回值

参数类型说明
channelIdstirng渠道ID

代码样例:

    XGSDK2.instance.getChannelId();

2.2.6 创建角色(必接)
    public static void onCreateRole(XGSDKEntity.RoleInfo roleInfo)

接口说明:

此接口用于游戏信息统计,当创建游戏角色时调用。

参数说明
1. 所有必须字段不能为空,否则会导致统计不完全,部分渠道审核无法通过;
2. 请严格按照西瓜规定的字段长度进行设置,否则可能导致游戏崩溃异常。

RoleInfo说明:

输入参数 数据类型 最大长度 说明 是否必填
uid String 128 用户ID (必须传入登录时XG服务器返回的UID) Y
roleId String 32 角色ID Y
roleName String 64 游戏必须传入真实的角色名,建议中文 Y
roleType String 20 角色类型,必须使用真实的角色类型,如法师,道士,战士,建议中文 N
roleCreateTime String 10 角色创建时间(Unix时间戳,单位秒),如:1461722392 (UC渠道要求必传真实值,否则无法通过审核) Y
roleLevel String 32 角色等级 Y
roleVipLevel String 32 角色VIP等级 N
serverId String 32 服ID:必须为纯数字,且不能超过2147483647(应用宝渠道要求) Y
zoneId String 32 区ID Y
serverName String 64 游戏必须传入真实的游戏服名称,建议中文 Y
zoneName String 32 游戏大区名称:要与界面显示名称一致,如:界面显示(一区 桃园结义),zoneName也必须传(一区 桃园结义)(UC渠道要求必传真实值,否则无法通过审核) Y
partyName String 32 公会名 N
gender String 传入字符:m,f;分别代表男女 性别 Y
balance String 128 角色账户余额 Y
ageInGame String 64 角色游戏年龄(单位:天) N
accountAgeInGame String 64 账号游戏年龄(单位:天) N
roleFigure String 32 体型(比如正太、萝莉、大叔、御姐等) N
ext String 1024 扩展参数 N

代码样例:

    XGSDK2.instance.onCreateRole(roleInfo);

2.2.7 进入游戏(必接)
    public static void onEnterGame(RoleInfo roleInfo)

接口说明

此接口用于游戏信息统计,当进入游戏时调用。

参数说明:

同上

代码样例:

    XGSDK2.instance.onEnterGame(roleInfo);

2.2.8 角色升级(必接)
    public static void onRoleLevelup(RoleInfo roleInfo)

接口说明:

此接口用于游戏信息统计,当角色升级时调用。

参数说明:

同上

代码样例:

    XGSDK2.instance.onRoleLevelup(roleInfo);

2.3 渠道扩展接口

2.3.1 用户中心(支持部分渠道)
    public static void openUserCenter(string customParams)

接口说明:

打开用户中心时调用,此接口将调用渠道的用户中心方法。

参数说明:

customParams参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可。

代码样例:

    XGSDK2.instance.openUserCenter("");

2.3.2 切换账号
    public static void switchAccount(string customParams)

接口说明:

切换账号时调用,此接口将调用渠道的切换账号方法。

参数说明:

customParams参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可。

代码样例:

    XGSDK2.instance.switchAccount("");

2.3.3 callXGMethod:

调用渠道的特殊方法 (xgsdk-api-2.2.7版本及以上)

public static string callXGMethod(string methodName, string args, string customInfo)

接口说明: 个别渠道有特殊要求或实现时,需要调用此方法。

参数说明: methodName是方法名,args是传入的参数(需要找西瓜技术了解调用该渠道方法的指定参数格式),customInfo是扩展字段(一般为方法名)。

代码样例:

    XGSDK2.instance.callXGMethod("methodName", null, "methodName");

回调方法: public abstract void onXGGenericCallBack(string responseInfoStr);

回调参数说明: callXGMethod之后的回调,responseInfoStr是json串,格式举例:{"code": 200, "customInfo": "methodName", "result": ...} code为200时是成功,customInfo是callXGMethod时传入的扩展字段,result需要找西瓜技术了解该渠道方法返回值的定义才能解析。

2.3.4 是否已打渠道包接口:

public static Boolean hasPackedChannel();

接口说明:提供给游戏在开发过程中(未打渠道包之前)做if...else...处理。

代码样例:

XGSDK2.instance.hasPackedChannel();

2.3.5 打开渠道公告(支持部分渠道)

public static void openAnnounce(String extJsonParams);

接口说明:

打开渠道公告openAnnounce接口,建议在登录成功,选择区服之前调用。(注:此接口和西瓜数据统计里的打开公告接口分别是两个接口)

参数说明:

extJsonParams参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可。

代码样例:

XGSDK2.instance.openAnnounce("");

回调方法:

公告回调 public abstract void onAnnounceResult(int code, string msg, string jsonParams);

  • code 渠道回调 code

  • msg 渠道回调 msg

  • jsonParams 扩展字段

2.3.6 渠道邀请(支持部分渠道)

public static void invite(XGSDKEntity.InviteInfo inviteInfo);

接口说明:

此接口用于调用渠道提供的Facebook邀请

参数说明:

InviteInfo说明:

输入参数 数据类型 最大长度 说明 是否必填
applinkUrl String 128 邀请App链接 Y
channelName String 32 例如:Google,Facebook,etc. N
previewImageUrl String 128 预览图链接地址 Y
extJsonParans String 1024 扩展字段json串 N

代码样例:

XGSDK2.instance.invite(inviteInfo);

回调方法:

邀请回调

public abstract void onInviteResult(int code, string msg, string jsonParams);

  • code 渠道回调code

  • msg 渠道回调 msg

  • jsonParams 扩展字段

2.3.7 渠道邀请挑战(支持部分渠道)

public static void requestChallenge(XGSDKEntity.RequestChallengeInfo requestChallengeInfo);

接口说明:

此接口用于调用渠道提供的Facebook邀请挑战

参数说明:

RequestChallengeInfo说明说明:

输入参数 数据类型 最大长度 说明 是否必填
message String 255 挑战描述(最长255个字符) Y
channelName String 32 例如:Google,Facebook,etc. N
extJsonParans String 1024 扩展字段json串 N

代码样例:

XGSDK2.instance.requestChallenge(requestChallengeInfo);

回调方法:

邀请挑战回调

public abstract void onRequestChallengeResult(int code, string msg, string jsonParams);

  • code 渠道回调code

  • msg 渠道回调 msg

  • jsonParams 扩展字段

2.3.8渠道更新成就(支持部分渠道,只限Android)

public static void updateAchivement(XGSDKEntity.AchivementInfo achivementInfo);

接口说明:

此接口用于调用渠道提供的google解锁成就接口

参数说明:

AchivementInfo说明:

输入参数 数据类型 最大长度 说明 是否必填
achievementId String 10 成就id Y
channelName String 32 例如:Google,Facebook,etc. N
extJsonParans String 1024 扩展字段json串 N

代码样例:

XGSDK2.instance.updateAchivement(achivementInfo);

回调方法:

更新成就回调

public abstract void onUpdateAchivementResult(int code, string msg, string jsonParams);

  • code 渠道回调code

  • msg 渠道回调 msg

  • jsonParams 扩展字段

2.3.9 渠道显示成就(支持部分渠道,只限Android)

public static void showAchivement(String extJsonParams)

接口说明:

此接口用于调用渠道提供的google显示成就接口

参数说明:

extJsonParams参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可。

代码样例:

XGSDK2.instance.showAchivement("showAchivement");

回调方法:

显示成就回调

public abstract void onShowAchivementResult(int code, string msg, string jsonParams);

  • code 渠道回调code

  • msg 渠道回调 msg

  • jsonParams 扩展字段

2.3.10 苹果推荐商品支付接口(只支持IOS)

接口说明: 在收到onXGGenericCallBack回调后,解析返回结果。

如果code==200,并且customInfo == "appstorep"时,解析result字段,获取商品ID (productId) 然后游戏可以根据当前商品ID,调用支付接口(参考2.2.3)

调用支付接口时,需要在payInfo中设置扩展属性,增加payType字段appstorep

代码样例:

additionalParams="{"payType":"appstorep"}";  //(JSON类型)

例:

2.4 数据统计口

2.4.1 注册账号(只支持iOS)
    XGSDK2.instance.onAccountCreate(string accountId, string serverId, string serverName, string serverVersion, string zoneId, string zoneName, string customParams)

接口说明:

此接口用于接入监控数据调用。

参数说明:

accountId 账号ID
serverId 服务器ID
serverName 服务器名称
serverVersion 服务器版本号
zoneId 区ID
zoneName 区名称
extendParams 扩展参数

2.4.2 游戏加载资源接口
public static void onGameLoadResource();

接口说明:游戏加载资源完成时调用该接口,发送相关信息。

代码样例:

XGSDK2.instance.onGameLoadResource();

2.4.3 游戏加载配置接口
public static void onGameLoadConfig();

接口说明:游戏加载配置完成时调用该接口,发送相关信息。

代码样例:

XGSDK2.instance.onGameLoadConfig();

2.4.4 打开公告接口
public static void onOpenAnnouncement();

接口说明:打开公告时调用此接口。

代码样例:

XGSDK2.instance.onOpenAnnouncement();

2.4.5 关闭公告接口
public static void onCloseAnnouncement();

接口说明:用户关闭公告时调用该接口,发送相关信息。

代码样例:

XGSDK2.instance.onCloseAnnouncement();

2.4.6 新手任务完成接口
public static void onNewUserMission(RoleInfo roleInfo);

接口说明:用户完成新手任务时调用该接口,发送相关信息。

参数说明:

输入参数 数据类型 最大长度 说明 是否必填
uid String 128 用户ID (必须传入登录时XG服务器返回的UID) Y
roleId String 32 角色ID Y
roleName String 64 游戏必须传入真实的角色名,建议中文 Y
roleType String 20 角色类型,必须使用真实的角色类型,如法师,道士,战士,建议中文 N
roleCreateTime String 10 角色创建时间(Unix时间戳,单位秒),如:1461722392 (UC渠道要求必传真实值,否则无法通过审核) Y
roleLevel String 32 角色等级 Y
roleVipLevel String 32 角色VIP等级 N
serverId String 32 服ID:必须为纯数字,且不能超过2147483647(应用宝渠道要求) Y
zoneId String 32 区ID Y
serverName String 64 游戏必须传入真实的游戏服名称,建议中文 Y
zoneName String 32 游戏大区名称:要与界面显示名称一致,如:界面显示(一区 桃园结义),zoneName也必须传(一区 桃园结义)(UC渠道要求必传真实值,否则无法通过审核) Y
partyName String 32 公会名 N
gender String 传入字符:m,f;分别代表男女 性别 Y
balance String 128 角色账户余额 Y
ageInGame String 64 角色游戏年龄(单位:天) N
accountAgeInGame String 64 账号游戏年龄(单位:天) N
roleFigure String 32 体型(比如正太、萝莉、大叔、御姐等) N
ext String 1024 扩展参数 N

代码样例:

XGSDK2.instance.onNewUserMission(roleInfo);

2.4.7 任务开始
public static void onMissionBegin(RoleInfo roleInfo, string missionId, string missionName, int doMissionTimes, int roleCurrentPower, string customParams)

接口说明:

此接口用于数据统计,任务开始时调用。

参数说明:

输入参数 数据类型 说明 必须
missionId string 任务ID,不可为空 Y
missionName string 任务名称,不可为空 Y
doMissionTimes int 次数,传递数值为第几次执行该任务/关卡 Y
roleCurrentPower int 角色当前体力值 Y
customParams string 扩展参数,不可为空 Y

RoleInfo说明:

输入参数 数据类型 最大长度 说明 是否必填
uid String 128 用户ID (必须传入登录时XG服务器返回的UID) Y
roleId String 32 角色ID Y
roleName String 64 游戏必须传入真实的角色名,建议中文 Y
roleType String 20 角色类型,必须使用真实的角色类型,如法师,道士,战士,建议中文 N
roleCreateTime String 10 角色创建时间(Unix时间戳,单位秒),如:1461722392 (UC渠道要求必传真实值,否则无法通过审核) Y
roleLevel String 32 角色等级 Y
roleVipLevel String 32 角色VIP等级 N
serverId String 32 服ID:必须为纯数字,且不能超过2147483647(应用宝渠道要求) Y
zoneId String 32 区ID Y
serverName String 64 游戏必须传入真实的游戏服名称,建议中文 Y
zoneName String 32 游戏大区名称:要与界面显示名称一致,如:界面显示(一区 桃园结义),zoneName也必须传(一区 桃园结义)(UC渠道要求必传真实值,否则无法通过审核) Y
partyName String 32 公会名 N
gender String 传入字符:m,f;分别代表男女 性别 Y
balance String 128 角色账户余额 Y
ageInGame String 64 角色游戏年龄(单位:天) N
accountAgeInGame String 64 账号游戏年龄(单位:天) N
roleFigure String 32 体型(比如正太、萝莉、大叔、御姐等) N
ext String 1024 扩展参数 N

其它参数说明:

输入参数 数据类型 说明 可空
missionId string 任务ID 不可为空
missionName string 任务名称 不可为空
customParams string 扩展参数 不可为空

代码样例:

    XGSDK2.instance.onMissionBegin(roleInfo, "1", "test", "1");

2.4.8 任务成功

public static void onMissionSuccess(RoleInfo roleInfo, string missionId, string missionName, int doMissionTimes, int roleCurrentPower, string customParams)

接口说明:

此接口用于数据统计,任务成功时调用。

参数说明:

输入参数 数据类型 说明 必须
missionId string 任务ID,不可为空 Y
missionName string 任务名称,不可为空 Y
doMissionTimes int 次数,传递数值为第几次执行该任务/关卡 Y
roleCurrentPower int 角色当前体力值 Y
customParams string 扩展参数,不可为空 Y

代码样例:

    XGSDK2.instance.onMissionSuccess(roleInfo,"TestMissionId", "TestMissionName", 1, 50, "1");

2.4.9 任务失败

public static void onMissionFail (RoleInfo roleInfo, string missionId, string missionName, int doMissionTimes, int roleCurrentPower, string customParams)

接口说明:

此接口用于数据统计,任务失败时调用。

参数说明:

输入参数 数据类型 说明 必须
missionId string 任务ID,不可为空 Y
missionName string 任务名称,不可为空 Y
doMissionTimes int 次数,传递数值为第几次执行该任务/关卡 Y
roleCurrentPower int 角色当前体力值 Y
customParams string 扩展参数,不可为空 Y

代码样例:

XGSDK2.instance.onMissionFail(roleInfo,"TestMissionId", "TestMissionName", 1, 50, "1");

2.4.10 获得虚拟货币
    public static void onVirtualCurrencyPurchase(RoleInfo roleInfo, int amount, string gameTradeNo, string customParams, string currencyName, int currencyTotal)

接口说明

此接口用于游戏信息统计,充值获得虚拟货币时调用。

参数说明:

参数 说明
roleInfo 角色信息
amount 获得数量
gameTradeNo 游戏订单号
customParams 扩展参数
currencyName 虚拟货币名称,如:元宝、金币等
currencyTotal 虚拟货币总量,如:100、1000、10000

代码样例:

    XGSDK2.instance.onVirtualCurrencyPurchase(roleInfo, 100, "123456", "", "元宝", 10);

2.4.11 赠送虚拟货币
    public static void onVirtualCurrencyReward(RoleInfo roleInfo, string reason, int amount, string gameTradeNo, string customParams, string currencyName, int currencyTotal, string gainChannelType)

接口说明:

此接口用于游戏信息统计,玩家可以在任务奖励、登录奖励、成就奖励等环节获得赠送的虚拟货币时调用

参数说明:

参数 说明
roleInfo 对象信息
reason 获得虚拟货币的原因(登录奖励、新手礼包等)
amount 获得虚拟货币数量
gameTradeNo 游戏订单号
customParams 扩展参数
currencyName 虚拟货币名称,如:元宝、金币等
currencyTotal 虚拟货币总量,如:100、1000、10000
gainChannelType 货币来源类型比如日常任务、闯关等

代码样例:

    XGSDK2.instance.onVirtualCurrencyReward(roleInfo, "每日登录奖励", 100, "123456", "", "元宝", 10, "日常任务");

2.4.12 跟踪虚拟货币的消费
    public static void onVirtualCurrencyConsume(RoleInfo roleInfo, string itemName, int amount, string customParams, string currencyName, int currencyTotal, int itemNum, string itemType)

接口说明:

此接口用于游戏信息统计,跟踪虚拟货币的消费(建议只跟踪有价值的虚拟货币,普通游戏币的消耗不建议在此跟踪)。

参数说明:

参数 说明
roleInfo 对象信息
itemName 消费点(比如十连抽、购买体力等)
amount 消费虚拟货币数量,如:10、100、100
customParams 扩展参数
currencyName 虚拟货币名称,如:元宝、金币等
currencyTotal 虚拟货币总量,如:100、1000、10000
itemNum 消费项目的数量,如1
itemType 消费类型 比如道具

代码样例:

    XGSDK2.instance.onVirtualCurrencyConsume(roleInfo, "十连抽", 8, "", "金币", 1000, 10, "幸运大转盘");

2.4.13 自定义事件
    public static void onEvent(RoleInfo roleInfo, string eventId, string eventDesc, int eventVal, string eventBody)

接口说明:

传递事件时使用,此接口用于游戏的自定义事件。

参数说明:

参数 说明
roleInfo 角色信息
eventId 事件id
eventDesc 事件描述
eventVal 事件内容
eventBody key-value 事件体

代码样例:

    XGSDK2.instance.onEvent(roleInfo, "eventid", "eventDesc", 1, "{\"key\":\"value\"}");

2.4.14 跟踪玩家的支付信息
    public static void onPayFinish(PayInfo payInfo)

接口说明:

跟踪玩家的支付信息,支付成功时调用此接口。

参数说明:
1. 所有必须字段不能为空,否则会导致数据统计误差;
2. 请严格按照西瓜规定的字段长度进行设置,否则可能导致游戏运行异常。
payInfo 支付信息

参数 参数类型 最大长度 说明 必须
uid String 128 游戏必须使用登录时西瓜服务器返回的uid Y
productId String 64 产品ID,如果西瓜后台有商品配置则必须保持一致 Y
productName String 64 游戏必须使用真实的产品名称,建议中文 Y
productDesc String 128 商品描述:不能为空、不能包含特殊字符,包括 # " & / ? $ ^ *:) \ < > | , = 回车 换行,否则部分渠道无法拉起支付 Y
productUnit String 64 产品单位,必须使用真实的单位,,建议中文,例如元宝 Y
productUnitPrice int 10 商品单价,单位分(无需传,以后版本会去掉) N
productQuantity int 10 产品数量,例如购买60元宝则传60 Y
totalAmount int 10 产品总额,单位分 Y
payAmount int 10 实际支付总额,单位分 Y
currencyName String 64 海外渠道必传:实际支付的国际标准货币代码,比如CNY(人民币)/USD(美元) Y
roleId String 32 角色ID Y
roleName String 64 角色名称 Y
roleLevel int 32 角色等级 Y
roleVipLevel String 32 角色vip等级 N
serverId String 32 服ID:必须为纯数字,且不能超过2147483647(应用宝渠道要求) Y
zoneId String 32 区ID Y
partyName String 32 帮会名称 N
customInfo String 2000 扩展字段,订单支付成功后,透传给游戏 N
gameTradeNo String 64 游戏订单ID,支付成功后,透传给游戏 N
gameCallbackUrl String 128 支付回调地址,如果为空,则后台配置的回调地址 N
additionalParams String - 透传参数 N
virtualCurrencyBalance String 32 虚拟货币余额,需要此字段的渠道:快发、小米、VIVO Y

代码样例:

    XGSDK2.instance.onPayFinish(payInfo);

2.5 运营活动接口

2.5.1 礼包码兑换、绑定手机号(西瓜提供界面)

接口定义:

public static void openWebActivity(string uid,string activityType,string roleId, string zoneId, string serverId)

接口说明:开启活动页面

参数 说明
uid 玩家uid
activityType 活动类型(XGSDKEntity.Constants中常量ACTIVITY_TYPE_GIFT/ACTIVITY_TYPE_MOBILE_BIND分别为兑换礼包码和绑定手机号)
roleId 玩家角色ID
zoneId 游戏区ID
serverId 游戏服ID

2.5.2 礼包码兑换(游戏提供界面)

接口定义:

public static void exchangeGiftCode(string uid, string roleId, string zoneId, string serverId, string cdkey)

接口说明:礼包码兑换

参数 说明
uid 玩家uid
roleId 玩家角色ID
zoneId 游戏区ID
serverId 游戏服ID
cdkey 礼包码

礼包码兑换回调
接口定义:

public override void onExchangeGiftCodeFinish(string responseInfoStr)

该接口已经在XGSDKCallbackImpl文件中定义,在方法里面实现即可。 参数说明:

参数 说明
responseInfoStr 礼包码兑换完成的回调json字符串,形如:{"code":0,"msg":"success"}
json对象详细介绍
参数 说明 必须
code 结果码,0为成功,其它为失败 Y
msg 成功或者错误信息 N

2.5.3 绑定手机号(游戏提供界面)

2.5.3.1 发送验证码

接口定义:

public static void sendCaptcha(XGSDKEntity.BindMobileInfo bindMobileInfo)

接口说明:绑定之前获取验证码

参数说明:BindMobileInfo

所有必字段必须进行接入

参数 参数类型 最大长度 说明 必须
mobile string 11 手机号 Y
uid string 128 用户ID,游戏必须使用登录时西瓜服务器返回的uid Y
serverId string 32 游戏服ID Y
zoneId string 32 区ID Y
roleId string 32 角色ID Y
roleName string 64 角色名 Y

回调方法:

public abstract void onSendCaptchaFinish(string responseInfoStr)

回调说明:接收发送验证码的结果

参数说明:

参数 说明
responseInfoStr 验证码发送的回调json字符串,形如:{"code":0,"msg":"success"}
json对象详细介绍
参数 说明 必须
code 结果码,0为成功,其它为失败 Y
msg 成功或者错误信息 N
2.5.3.2 绑定手机号

接口定义:

public static void bindMobile(XGSDKEntity.BindMobileInfo bindMobileInfo,string captcha)

接口说明:用拿到的验证码绑定手机号

参数说明:BindMobileInfo

所有必字段必须进行接入

参数 参数类型 最大长度 说明 必须
mobile string 11 手机号 Y
uid string 128 用户ID,游戏必须使用登录时西瓜服务器返回的uid Y
serverId string 32 游戏服ID Y
zoneId string 32 区ID Y
roleId string 32 角色ID Y
roleName string 64 角色名 Y

captcha:通过2.5.3.1获取验证码接口获取的验证码

回调方法:

public abstract void onBindMobileFinish(string responseInfoStr)

回调说明:接收发送验证码的结果

参数说明:

参数 说明
responseInfoStr 绑定手机的回调json字符串,形如:{"code":0,"msg":"success"}
json对象详细介绍
参数 说明 必须
code 结果码,0为成功,其它为失败 Y
msg 成功或者错误信息 N

2.5.4 查询绑定接口

和西瓜的绑定手机接口配合使用

2.5.4.1 检查UID是否绑定

接口定义:

public static void getBindInfoByUid (string uid)

参数说明:

uid:西瓜返回的uid

回调方法:

public abstract void onGetBindInfoByUid (string responseInfo);

回调说明:通过此回调来得到查询UID是否绑定的结果

参数说明:

responseInfo:json串,比如:{"code": "0", "msg": "已绑定"}
2.5.4.2 检查手机号码是否绑定

接口定义:

public static void getBindInfoByMobile(string mobile)

参数说明:

mobile:手机号码

回调方法:

public abstract void onGetBindInfoByMobile(string responseInfo);

回调说明:通过此回调来得到查询手机号码是否绑定的结果

参数说明:

responseInfo:json串,比如:{"code": "0", "msg": "已绑定"}

2.5.5 问卷调查

问卷的内容和完成问卷返回的礼品信息,需要联系西瓜数据和运营人员设定完成。

2.5.5.1 初始化问卷

通知Android / iOS初始化回调,请参考通知Android / iOS初始化回调方法,设置callback后就初始化了问卷。

2.5.5.2 刷新问卷

接口定义:

refreshQuestionnaireByQuestInfo(RoleInfo roleInfo, QuestInfo questInfo);

接口说明:游戏初始化问卷后手动调用刷新问卷,查看问卷是否更新。

参数说明:

RoleInfo说明:

输入参数 数据类型 最大长度 说明 是否必填
uid String 128 用户ID (必须传入登录时XG服务器返回的UID) Y
roleId String 32 角色ID Y
roleName String 64 游戏必须传入真实的角色名,建议中文 Y
roleType String 20 角色类型,必须使用真实的角色类型,如法师,道士,战士,建议中文 N
roleCreateTime String 10 角色创建时间(Unix时间戳,单位秒),如:1461722392 (UC渠道要求必传真实值,否则无法通过审核) Y
roleLevel String 32 角色等级 Y
roleVipLevel String 32 角色VIP等级 N
serverId String 32 服ID:必须为纯数字,且不能超过2147483647(应用宝渠道要求) Y
zoneId String 32 区ID Y
serverName String 64 游戏必须传入真实的游戏服名称,建议中文 Y
zoneName String 32 游戏大区名称:要与界面显示名称一致,如:界面显示(一区 桃园结义),zoneName也必须传(一区 桃园结义)(UC渠道要求必传真实值,否则无法通过审核) Y
partyName String 32 公会名 N
gender String 传入字符:m,f;分别代表男女 性别 Y
balance String 128 角色账户余额 Y
ageInGame String 64 角色游戏年龄(单位:天) N
accountAgeInGame String 64 账号游戏年龄(单位:天) N
roleFigure String 32 体型(比如正太、萝莉、大叔、御姐等) N
ext String 1024 扩展参数(Json串格式) N

QuestInfo说明:

输入参数 数据类型 最大长度 说明 是否必填
questId String 32 任务ID N
questName String 64 任务名称 N
missionId String 32 关卡ID N
missionName String 64 关卡名称 N
customParams String 1024 扩展参数(Json串格式) N

注意:当questInfo和roleInfo都有扩展参数时,而且有相同的key值时,questInfo扩展参数 key对应的数据会覆盖掉roleInfo扩展参数key对应的数据。

代码样例:

XGSDK2.instance.refreshQuestionnaireByQuestInfo(roleInfo, questInfo);

回调方法:

问卷状态更新回调

public abstract void doFreshQuestionnaire(String questionnaireName);

回调说明:

问卷状态更新后,用该方法处理问卷信息的显示与通知。该回调会在调用onEnterGame或refreshQuestionnaire或打开问卷填写并提交问卷后触发。

参数说明:

问卷名称,未设置可能是null或者""

实现代码示例:

    //问卷状态更新后,用该方法处理问卷信息的显示与通知
    public override void doFreshQuestionnaire(string questionnaireName)
    {
        //1. 如果questionnaireName不等于空:显示问卷按钮
        //2. 如果questionnaireName等于空:隐藏问卷按钮
    }
2.5.5.3 打开问卷

接口定义:

  public static void openXgQuestionnaire(int widthPercent,  int heightPercent, string customParams)

接口说明:点击问卷按钮时,调用该方法,显示问卷窗口。

参数说明:

widthPercent:打开问卷窗口的宽度占屏幕的百分比,100表示全屏。

heightPercent:打开问卷窗口的高度占屏幕的百分比,100表示全屏。

customParams:json串格式自定义参数,可为null。

代码样例:

  XGSDK2.instance.openXgQuestionnaire(80, 80, null);

调用实例代码:

回调方法:

完成问卷回调

  public abstract void doFinishQuestionnaire(string giftInfo);

回调说明:

问卷完成后,用该方法处理完成问卷的相关奖励。该回调会在调用打开问卷并填写提交后触发。

参数说明:

游戏自定义的礼品信息,格式也是自己定义。需要联系西瓜数据和运营人员设定完成。

实现代码示例:

    //问卷完成后,用该方法隐藏问卷按钮,发放奖励
    public override void doFinishQuestionnaire(string giftInfo)
    {
        // 1. 隐藏问卷按钮
        // 2. 发放奖品
    }

2.6 更新服务回调接口

游戏需要使用西瓜更新服务时,在西瓜后台配置打开更新

西瓜检测完更新将通过西瓜通用回调(onXGGenericCallBack)回调游戏

参数 说明
code 200:成功,其它失败
customInfo {"updateType":"1"} type = 0 为强制更新 type = 1 为选择更新 type = -1 为不存在更新
result "updateCallBack"

3 渠道接入要点须知

  • 华为:
    1.要求传入的productDesc非空,不能包含特殊字符,包括 # " & / ? $ ^ *:) \ < > | , = 回车 换行,否则会导致无法拉起支付
  • 快发:
    1.要求首次启动游戏onCreateRole的信息和onEnterGame的一致
  • UC:
    1.角色创建时间为必传
    2.zoneName要与角色进入游戏时,玩家看到的信息相同,如:界面显示(一区 桃园结义),zoneName也必须传(一区 桃园结义)
  • 应用宝:
    1.调用西瓜login接口可以传参:{\"platform\":\"qq\"} or {\"platform\":\"weixin\"}"
    2.serverid必须为纯数字,且不能超过2147483647