西瓜SDK(Android原生引擎)模拟接入文档

1. 文档概述

此文档为使用Android原生引擎游戏客户端的模拟接入文档。
本文介绍在Android原生引擎平台下,游戏开发人员如何进行模拟接入西瓜SDK。 文档分成三大部分:西瓜 SDK 模拟接入工具 下载,集成模拟接入环境,各个接口的接入说明和样例代码,如何查看调测记录。逐步细述了整个接入过程;
同时罗列出了4种类型的接口:分别为:用户与角色接口、充值接口、统计接口、扩展接口 ,便于游戏方的接入人员可以按照需求更加快速便捷的进行模拟接入。

1.1 文档结构

  1. 文档概述
  2. 配置环境与快速接入简介
  3. 用户接口
  4. 充值接口
  5. 统计接口
  6. 扩展接口
  7. 文档版本

1.2 SDK下载包

渠道版 SDK 下载包包含: 渠道版SDK下载包包含:

  1. 西瓜SDK的Jar包:xgsdk-api.jar;
  2. Android原生接入Demo;
  3. 西山居移动游戏-渠道SDK(Android 原生)接入文档。
  4. 模拟接入工具包

java 原生SDK下载

2. 配置环境与快速接入简介

2.1 开发和接入所需基本环境

Java开发环境:

  • Java版本:JAVA JDK 8

Android开发环境:

  • Android版本:Android2.2 以上
  • Android NDK版本:Android NDK r10
  • Android开发工具:Android SDK和Android Eclipse等

2.2 模拟渠道接入模拟游戏

1.下载好Android的API压缩包后,打开压缩包,使用MD5校验工具确认一下MD5值是否一致:

2.把压缩包内的android_2.2.0.zip解压出来,会出现模拟游戏包与调测渠道包

3.按如图所示步骤将调测渠道工程导入eclipse中,调测渠道需要依赖xgsdk-channel-core,然后在eclipse中Clean整个工程

4.按如图所示方式将模拟游戏包导入eclispe中,需要依赖调测渠道工程

5.在eclipse中运行模拟游戏工程,这样原生模拟接入就安装好了

2.3 完善模拟接入的配置信息

登录西瓜web控制台,选择待模拟接入的产品,选择“调测信息”, 填上游戏方供测试充值回调的地址(如果不配置,或者配置错误,支付的服务端验证可能会出现错误),并且点击测试参数的“复制”按钮

把上文复制的测试参数,全部粘贴到游戏工程目录下的配置文件里:

\assets\sdk_config.properties

2.4 基于游戏开发环境上的调试方法

首先,游戏要已经接入西瓜API,可以直接在eclipse中进行调试,将渠道工程xgsdk-channel-test的layout文件夹中的xg-testchannel-item-order.xml与xg-testchannel-item-title.xml文件拷贝到游戏工程的layout文件夹中,然后运行游戏工程,出现登录页面。

注意:使用调测功能需要保证客户端能连上西瓜web控制台。

该功能主要对游戏调用西瓜API的接口进行参数校验,如果有错,则给出错误信息,如果校验正确,则记录调用记录,调用日志可以在西瓜web控制台的调测信息的日志找到,使用如下图:

模拟接入必须接入的接口展示在西瓜web控制台的调测信息的未调用接口列表

如果有接口的参数校验失败了,客户端会弹出报错窗口,告诉哪一个参数错误,参数的校验规则是什么,这样便于游戏开发人员及时发现参数错误的原因。 (弹出框参数列表是可以滚动的)

建议:至少需要把所有接口都成功接入才可以进行下一步实际接入测试。

3. 用户接口

3.1 登录接口(必接)

接口定义: public void login(Activity activity,String customParams)

接口说明: 在相应的位置调用登录接口,此接口将调出渠道的登录界面,并将登录的结果回调通知游戏。

参数说明:

  • activity:该参数是传入当前activity。
  • customParams:该参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可。

代码示例:

XGSDK.getInstance().login(activity,customParams);

模拟接入时,调用该接口,会弹出一个登录框,下方的三个按钮,模拟了三种登录回调:登录成功,登录取消,登录失败,只有点击“登录成功”才会真正去请求uid和authinfo信息回调给游戏。

登录成功,游戏服务端和西瓜服务端会进行验证,需要查看登录流程的调测记录,请登录西瓜web控制台查看。登录回调信息因为是在客户端固定给的信息,展示没有意义,故没有进行记录展示。

模拟接入的登录回调除了登录成功回调,都是固定的回调内容:
如果需要查看具体的回调参数,可以直接在调测渠道工程中打断点查看。

3.2 登出接口(必接)

接口定义:public void logout(Activity activity, String customParams)

接口说明: 在相应的位置调用登出接口,此接口将调用渠道的登出方法,并将登出的结果回调通知游戏。

代码示例:

XGSDK.getInstance().logout(activity,customParams);

关于参数的说明:

  • activity:该参数是传入当前activity
  • customParams:该参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可。

该接口点击后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录。

3.3 退出接口(必接)

接口定义: public void exit(Activity activity, final ExitCallBack exitCallBack, String customParams)

接口说明: 在相应的位置调用退出接口,此接口将调用渠道的退出方法,会尝试退出游戏,并将结果通过退出回调通知游戏。

代码示例:

findViewById(RUtil.getId(getApplicationContext(), "xg_exit")) .setOnClickListener(new OnClickListener() { @Override public void onClick(View v) { XGSDK.getInstance().exit(MainActivity.this,new ExitCallBack() {},null) } });

关于参数的说明:

  • activity:该参数是传入当前activity
  • exitCallBack:退出回调接口
  • customParams:该参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可。

3.4 退出回调

退出接口存在三个回调方法:

  1. onNoChannelExiter 使用游戏方退出框
  2. onExit 直接退出
  3. onCancel 取消退出

样例代码:

new ExitCallBack() {

        @Override
        public void onNoChannelExiter() {
            Dialog dialog = new AlertDialog.Builder(
                    MainActivity.this) ).create();
                  //调用游戏方退出框
            dialog.show();

        }

        @Override
        public void onExit() {
            finish();

        }

        @Override
        public void onCancel() {
            ToastUtil.showToast(MainActivity.this,
                    "回到游戏");

        }
 }

4.充值接口

4.1 支付接口(必接)

接口定义: public void pay(final Activity activity, PayInfo payInfo,PayCallBack payCallBack)

接口说明: 在相应的位置调用登出接口,此接口将会发起用户充值,系统会调用对应渠道SDK充值界面,并将支付的结果回调通知游戏。
支付接口需要传入类型为PayInfo的参数。

调用西瓜的支付API后,如果参数检验通过,模拟接入工具会弹出XG支付测试界面,下方有三个按钮,对应三种支付回调.

如果参数验证不通过,模拟接入工具会弹出支付不通过的页面,并显示参数不通过的页面详细情况。

调用记录在西瓜web控制台查看,支付成功的记录,有服务端的调用记录,需要游戏在西瓜web控制台配置正确的“测试环境回调地址”才可以看到服务端的验证记录。

支付成功的调用中,也可能请求订单失败,无法获取西瓜订单号

具体的失败记录,也可以在西瓜web控制台中看到记录:

关于 PayInfo 的成员说明

所有必接字段必须进行接入,否则会导致部分渠道无法支付!

请严格按照西瓜规定的字段长度进行设置,否则可能发生游戏服务器端长度不够问题。

参数 参数类型 最大长度 说明 必须
uid String 128 用户ID,游戏必须使用登录时西瓜服务器返回的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(美元) N
roleId String 32 角色ID Y
roleName String 64 角色名称 Y
roleLevel int 32 角色等级 Y
roleVipLevel String 32 角色vip等级 Y
serverId String 32 服ID:必须为纯数字,且不能超过2147483647(应用宝渠道要求) Y
zoneId String 32 区ID Y
partyName String 32 帮会名称 N
virtualCurrencyBalance String 虚拟货币余额,需要此字段的渠道:快发、小米、VIVO Y
customInfo String 2000 扩展字段,订单支付成功后,透传给游戏 N
gameTradeNo String 64 游戏订单ID,支付成功后,透传给游戏 N
gameCallbackUrl String 128 支付回调地址,如果为空,则后台配置的回调地址 N
additionalParams String 扩展参数 N

常用的国际货币

国家 货币中文名 货币英文名 货币代码
中国 人民币元 RenminbiYuan CNY
韩国 韩圆 Korean Won KRW
日本 日元 Japanese Yen JPY
美国 美元 U.S.Dollar USD

支付场景

场景一: 某个玩家,购买750钻石(价值80元),创建订单参数是:

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

场景二: 某个玩家,遇到商品打折优惠:购买750钻石(价值80元)可享受8.5折优惠,这样其实玩家是用68元购买了750钻石,创建订单参数是:

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

场景三: 某个玩家,购买月卡(价值30元),创建订单参数是:

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

4.2 支付回调

在调用 pay 接口时,需要实现 pay 支付 callback (支付的四种状态:支付成功,支付失败,支付取消,支付其他状态)。

实现的案例代码:

 XGSDK.getInstance().pay(MainActivity.this, payment, new PayCallBack() {

        @Override
        public void onPaySuccess(PayInfo payInfo,PayResult payResult) {
            ToastUtil.showToastLong(MainActivity.this, "pay success, result is "+payResult.toJson());
            OrderUtils.storeOrder(MainActivity.this, GameInfo.getInstance().getUid(),payResult.getXgTradeNo(),payment);
        }

        @Override
        public void onPayFail(PayInfo payInfo,PayResult payResult) {
            ToastUtil.showToastLong(MainActivity.this, "pay failed, result is "+payResult.toJson());
        }

        @Override
        public void onPayCancel(PayInfo payInfo,PayResult payResult) {
            ToastUtil.showToastLong(MainActivity.this, "pay canceled, result is "+payResult.toJson());
        }

        @Override
        public void onPayOthers(PayInfo payInfo, PayResult payResult) {
            ToastUtil.showToastLong(MainActivity.this, "onPayOthers, result is "+payResult.toJson());
        }

        @Override
        public void onPayProgress(PayInfo payInfo, PayResult payResult) {
            ToastUtil.showToastLong(MainActivity.this, "onPayProgress, result is "+payResult.toJson());
        }
    });

5.统计接口

5.1 创建角色(必接)

接口定义: public void onCreateRole(RoleInfo roleInfo)
接口说明: 统计接口在创建角色时调用该接口上传角色数据,创建角色需要传入类型为RoleInfo的参数。

参数 说明
roleInfo 角色信息

调用案例代码

findViewById(RUtil.getId(getApplicationContext(), "xg_create_role"))
            .setOnClickListener(new OnClickListener() {
                @Override
                public void onClick(View v) {
                    mRoleInfo.setRoleId("1112");
                    mRoleInfo.setRoleName("cuizi");
                    XGSDK.getInstance().onCreateRole(MainActivity.this,
                            mRoleInfo);
                }
            });

关于 RoleInfo 的成员说明:

所有必字段必须进行接入,否则会导致统计不完全,部分渠道审核无法通过!

请严格按照西瓜规定的字段长度进行设置,否则可能发生游戏服务器端长度不够问题。

参数 参数类型 最大长度 说明 必须
uid string 128 用户ID,游戏必须使用登录时西瓜服务器返回的uid Y
serverId string 32 服ID:必须为纯数字,且不能超过2147483647(应用宝渠道要求) Y
serverName string 64 游戏必须传入真实的游戏服名称,建议中文 Y
zoneId string 32 游戏区ID Y
zoneName string 64 游戏大区名称:要与界面显示名称一致,如:界面显示(一区 桃园结义),zoneName也必须传(一区 桃园结义),UC渠道要求 Y
roleId string 32 角色ID Y
roleName string 64 角色名 Y
roleType string 20 角色类型,如法师,道士,战士 N
roleCreateTime string 10 角色创建时间(Unix时间戳,单位秒),如:1461722392,UC 渠道要求 Y
roleLevel int 32 角色等级,游戏必须传入真实的角色等级 Y
roleVipLevel int 32 角色vip等级 N
partyName string 32 公会名 N
gender string 枚举值:m,f;分别代表男女 角色性别 N
balance string 128 角色账户余额 N

该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录。

5.2 角色升级(必接)

接口定义: public void onRoleLevelup(RoleInfo roleInfo) 接口说明: 统计接口在角色升级时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo的参数。 接口说明:角色等级接口,角色等级提升时调用

参数 说明
roleInfo 角色信息

调用案例代码

findViewById(RUtil.getId(getApplicationContext(), "xg_role_levelup"))
            .setOnClickListener(new OnClickListener() {

                @Override
                public void onClick(View v) {
                    mRoleInfo.setRoleId("1112");
                    mRoleInfo.setLevel(2);
                    XGSDK.getInstance().onRoleLevelup(mRoleInfo);
                }
            });

该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录。

5.3 进入游戏(必接)

接口定义: public void onEnterGame(RoleInfo roleInfo)
接口说明: 统计接口在角色升级时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo的参数。

参数 说明
RoleInfo 角色信息
注:此接口在调用登录成功 callback 的时候调用 调用案例代码: @Override public void onLoginSuccess(final String authInfo) { Log.w(TAG, "authInfo: \n" + authInfo); XGSDK.getInstance().onEnterGame(mRoleInfo); } 该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录。 ## 6.扩展接口 ### 6.1 切换账号 **接口定义:** public void switchAccount(Activity activity, String customParams); **接口说明:** 此接口将调用渠道的切换账号方法,传入扩展参数 customParams,并会产生登出回调来通知游戏。 **关于参数的说明:**
参数 说明
customParams 该参数用于扩展,传输时使用 json 格式,接入时若不需要直接置空即可

该接口触发后,会调用登出的回调,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录。

6.2 自定义事件

接口定义: public void onEvent(RoleInfo roleInfo, String eventId, String eventDesc, int eventVal, Map eventBody) 接口说明: 自定义事件,传入事件id以及事件内容

参数 说明
roleInfo 角色信息
eventId 事件id
eventDesc 事件描述
eventVal 事件内容
eventBody key-value 事件体
该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录。 该接口没有在未调用列表中,但是如果校验成功,会在西瓜web控制台记录日志。 ### 6.3 任务开始 **接口定义:** public void onMissionBegin(RoleInfo roleInfo, String missionId, String missionName, String customParams) **接口说明:** 统计接口在任务开始时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo等参数。
参数 说明
roleInfo 对象信息
missionId 任务ID
missionName 任务名称
customParams 该参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可

该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录。 该接口没有在未调用列表中,但是如果校验成功,会在西瓜web控制台记录日志。

6.4 任务成功

接口定义: public void onMissionSuccess(RoleInfo roleInfo, String missionId, String missionName, String customParams)

接口说明: 统计接口在任务成功时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo等参数。

参数 说明
roleInfo 对象信息
missionId 任务ID
missionName 任务名称
customParams 该参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可
该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录。 该接口没有在未调用列表中,但是如果校验成功,会在西瓜web控制台记录日志。 ### 6.5 任务失败 **接口定义:** public void onMissionFail(RoleInfo roleInfo, String missionId, String missionName, String customParams) **接口说明:** 统计接口在任务成功时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo等参数。 该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录 。 该接口没有在未调用列表中,但是如果校验成功,会在西瓜web控制台记录日志。
参数 说明
roleInfo 对象信息
missionId 任务ID
missionName 任务名称
customParams 该参数用于扩展,传输时使用json格式,接入时若不需要直接置空即可

6.6 获得虚拟货币

接口定义: public void onVirtalCurrencyPurchase(RoleInfo roleInfo, int amount, String customParams)

接口说明: 充值获得的虚拟货币
注意该接口需要在游戏服务器通知游戏客户端的时候才进行数据上报,在其他地方上报数据,会造成数据错误
该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录 该接口没有在未调用列表中,但是如果校验成功,会在西瓜web控制台记录日志。

参数 说明
roleInfo 对象信息
amount 数量
customParams 扩展参数

6.7 赠送虚拟货币

接口定义: public void onVirtualCurrencyReward(RoleInfo roleInfo, String reason, int amount, String customParams)

接口说明: 统计接口在赠送虚拟货币时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo等参数。

该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录 该接口没有在未调用列表中,但是如果校验成功,会在西瓜web控制台记录日志。

参数

说明 </tr> roleInfo 对象信息 reason 获得虚拟货币的原因(登录奖励、新手礼包等) amount 数量 customParams 扩展参数 </table>

6.8 消费虚拟货币

接口定义: public void onVirtalCurrencyConsume(RoleInfo roleInfo,String itemName, int amount, String customParams)

接口说明: 统计接口在消费虚拟货币时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo等参数。

参数

说明 </tr> roleInfo 对象信息 itemName 消费点(比如十连抽、购买体力等) amount 数量 customParams 扩展参数 </table> 该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录 该接口没有在未调用列表中,但是如果校验成功,会在西瓜web控制台记录日志。