西瓜SDK(Cocos2d-x引擎)模拟接入文档

1. 文档概述

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

1.1 文档结构

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

1.2 SDK下载包

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

  1. 西瓜SDK的Jar包:xgsdk-api.jar;
  2. 接口文件:ProtocolXGSDK.h和ProtocolXGSDK.cpp;
  3. Cocos2d-X的Android接入Demo;
  4. 西山居移动游戏-渠道SDK(Cocos2d-X Android)接入文档。
  5. 模拟接入工具包

Cocos2dx SDK下载

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

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

Cocos2d-X开发环境:

  • Cocos2d-X版本:Cocos2d-X 2.2.6
  • Cocos2d-X开发工具:VS2012,Xcode等
  • Python版本:Python 2.7.10

Java开发环境:

  • Java版本:JAVA JDK 8

Android开发环境:

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

2.2 安装模拟接入工具

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

2.把压缩包内的cocos_2.0.2.zip解压出来,把test/proj.win32下的classes文件夹复制到游戏的cocos2dx工程的proj.win32下(有重名的classes文件夹,合并即可)

3.同理,把压缩包的test/Resources下的XGWin32文件夹放到游戏的cocos2dx工程的Resources目录

4.用VS2012打开游戏工程,右键点击工程,选择添加->新建筛选器,名字建议取debugWin32

5.然后在debugWin32(前文新建的筛选器)点击右键,选择添加->现有项,把解压在proj.win32下的classes目录的文件全部添加进去

6.然后在主工程(字体加粗的工程目录,比如图例的XGDemo)右键,选择属性->配置属性->C/C++ 在弹出框的右边选择 附加包含目录,复制里面的信息,在最后添加pthread和rapidjson的引用路径,需要根据游戏工程实际路径进行添加,以下的例子是基于cocos2dx-2.2.6标准工程的引用路径(工程目录cocos2d-x-2.2.6\projects\XGDemo)

    ;$(ProjectDir)..\..\..\cocos2dx\platform\third_party\win32\pthread;$(ProjectDir)..\..\..\extensions\CocoStudio\Json\rapidjson;

如果工程已经引入这2个路径,则忽略。

7.检查西瓜API文件ProtocolXGSDK.cpp,看是否有win32平台的宏控制代码,如果没有,需要加入

XGWin32SDKProtocol.h的路径,需要和上文2中解压缩到proj.win32的路径保持一致!


    #include <stdio.h>
    #include "ProtocolXGSDK.h"
    #include "cocos2d.h"
    #if (CC_TARGET_PLATFORM == CC_PLATFORM_ANDROID)
    #include "../proj.android/jni/hellocpp/ProtocolXGSDKAndroid.h"
    #endif
    #if (CC_TARGET_PLATFORM == CC_PLATFORM_WIN32)
    #include "../proj.win32/classes/XGWin32SDKProtocol.h"
    #endif

    static ProtocolXGSDK *sInstance = NULL;
    ProtocolXGSDK *ProtocolXGSDK::getInstance()
    {
        if(!sInstance)
        {
    #if (CC_TARGET_PLATFORM == CC_PLATFORM_ANDROID)
            sInstance = new ProtocolXGSDKAndroid();
    #endif
    #if (CC_TARGET_PLATFORM == CC_PLATFORM_WIN32)
            sInstance = new XGWin32SDKProtocol();
    #endif
        }
        return sInstance;
    }

对游戏工程进行编译一下,正常情况下,是编译通过的。 这样cocos2dx的window下的模拟接入工具已经安装好了

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

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

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

Resources\Win32\sdk_config.properties

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

首先,游戏要已经接入了西瓜API,编译通过后,可以直接在window下启动调试,在登录页面,勾选“接口检查及调测”,才具备调测校验和记录功能,没有勾选,则不进行检查及记录调测信息。

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

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

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

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

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

3. 用户接口

3.1 登录接口(必接)

接口定义: void login(const char * customParams = "");

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

代码示例:

    mXgSdk->login();

关于参数的说明:

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

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

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

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

3.2 登出接口(必接)

接口定义: void logout(const char * customParams = "");

接口说明: 在相应的位置调用登出接口,调用位置可参考Demo中的XGCocosDemo.cpp,此接口将调用渠道的登出方法,并将登出的结果回调通知游戏。

代码示例:

    mXgSdk->logout();

关于参数的说明:

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

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

3.3 退出接口(必接)

接口定义: void exit(const char * customParams = "");

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

代码示例:


    mXgSdk->exit();

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

4.充值接口

4.1 支付接口(必接)

接口定义: void pay(PayInfo &);

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

具体的代码示例和参数要求请参考接入文档。

调用西瓜的支付API后,模拟接入工具会弹出XG支付测试界面,下方有三个按钮,对应三种支付回调,只有支付成功才会去请求订单。

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

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

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

5.统计接口

5.1 创建角色(必接)

接口定义: void onCreateRole(RoleInfo &);
接口说明: 统计接口在创建角色时调用该接口上传角色数据,创建角色需要传入类型为RoleInfo的参数。 具体的代码示例和参数要求请参考接入文档。

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

5.2 角色升级(必接)

接口定义: void onRoleLevelup(RoleInfo &);
接口说明: 统计接口在角色升级时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo的参数。 具体的代码示例和参数要求请参考接入文档。 该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录。

5.3 进入游戏(必接)

接口定义: void onEnterGame(RoleInfo &);
接口说明: 统计接口在角色升级时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo的参数。 具体的代码示例和参数要求请参考接入文档。 该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录。

6.扩展接口

6.1 切换账号

接口定义: void switchAccount(const char * customParams = "");

接口说明: 在相应的位置调用切换账号接口,调用位置可参考Demo中的XGCocosDemo.cpp,此接口将调用渠道的切换账号方法,并会产生登出回调来通知游戏。

代码示例:

    mXgSdk->switchAccount();

关于参数的说明:

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

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

6.2 自定义事件

接口定义: void onEvent(RoleInfo &, const char* eventId, const char* eventDesc,int eventValue, const char* eventBody="");
接口说明: 统计接口在游戏自定义事件时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo等参数。

具体的代码示例和参数要求请参考接入文档。 该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录。 该接口没有在未调用列表中,但是如果校验成功,会在西瓜web控制台记录日志。

6.3 任务开始

接口定义: void onMissionBegin(RoleInfo& roleInfo, const char* missionId, const char* missionName, const char *customParams="");

接口说明: 统计接口在任务开始时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo等参数。 具体的代码示例和参数要求请参考接入文档。

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

6.4 任务成功

接口定义: void onMissionSuccess(RoleInfo& roleInfo, const char* missionId, const char* missionName, const char *customParams="");

接口说明: 统计接口在任务成功时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo等参数。 具体的代码示例和参数要求请参考接入文档。 该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录。 该接口没有在未调用列表中,但是如果校验成功,会在西瓜web控制台记录日志。

6.5 任务失败

接口定义: void onMissionFail(RoleInfo& roleInfo, const char* missionId, const char* missionName, const char *customParams="");

接口说明: 统计接口在任务成功时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo等参数。
具体的代码示例和参数要求请参考接入文档。 该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录 。 该接口没有在未调用列表中,但是如果校验成功,会在西瓜web控制台记录日志。

6.6 获得虚拟货币

接口定义: void onVirtalCurrencyPurchase(RoleInfo& roleInfo, int amount, const char *customParams="");

接口说明: 统计接口在获得虚拟货币时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo等参数。
注意该接口需要在游戏服务器通知游戏客户端的时候才进行数据上报,在其他地方上报数据,会造成数据错误

具体的代码示例和参数要求请参考接入文档。
该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录 该接口没有在未调用列表中,但是如果校验成功,会在西瓜web控制台记录日志。

6.8 赠送虚拟货币

接口定义: void onVirtualCurrencyReward(RoleInfo& roleInfo, const char *reason, int amount, const char *customParams="");

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

具体的代码示例和参数要求请参考接入文档。
该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录 该接口没有在未调用列表中,但是如果校验成功,会在西瓜web控制台记录日志。

6.9 消费虚拟货币

接口定义: void onVirtualCurrencyConsume(RoleInfo& roleInfo, const char *itemName, int amount, const char *customParams="");

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

具体的代码示例和参数要求请参考接入文档。
该接口触发后,在客户端没有明确提示,只要正确接入该接口,可以在西瓜web控制台查找到记录 该接口没有在未调用列表中,但是如果校验成功,会在西瓜web控制台记录日志。