西瓜SDK(Cocos2d-X Android版)接入文档

1. 文档概述

此文档为Cocos2d-X引擎Android游戏客户端接入文档。
本文介绍如何在Cocos2d-X引擎平台下,Android游戏客户端快速接入西瓜SDK。 文档分成三大部分:接入环境下载/搭建,西瓜SDK接口说明以及参考代码。逐步细述了整个接入过程;同时罗列出了4种类型的接口, 分别为:用户接口、充值接口、统计接口、扩展接口,便于游戏方的接入人员可以按照需求更加快速便捷的进行接入。

1.1 文档结构

  1. 文档概述
  2. 配置环境与快速接入简介
  3. 修改相应平台工程的配置信息
  4. 接入前的初始化工作
  5. 用户接口
  6. 充值接口
  7. 统计接口
  8. 扩展接口
  9. 运营活动接口
  10. 渠道接入要点须知

1.2 SDK下载包

渠道版SDK下载包包含:

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

Cocos2dx SDK下载

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

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等

3. 修改相应平台工程的配置信息

3.1 复制SDK的Jar包

将西瓜SDK的xgsdk-api.jar和libcocos2dx.jar拷贝到Android工程的libs目录下:

3.2 复制接口文件

复制接口文件ProtocolXGSDK.h,ProtocolXGSDK.cpp到工程的Classes目录。

复制接口文件ProtocolXGSDKAndroid.h,ProtocolXGSDKAndroid.cpp和ProtocolXGSDK_android_CallBack.h到Android工程中的jni/hellocpp目录下,如图:

3.3 修改游戏的主Activity

拷贝xgsdk-cocos-2.0.X.jar文件到安卓工程目录下,如图:

找到游戏的主Activity(继承于Cocos2dxActivity的游戏主Activity),修改该Activity,让其继承XGCocos2dxActivity,并且使用import语句导入XGCocos2dxActivity类:
在这个类中,位于public class 和package之间的位置添加如下语句:

    import com.xgsdk.client.XGCocos2dxActivity;
注意,XGCocos2dxActivity中已经重写过了 public Cocos2dxGLSurfaceView onCreateView()
这个方法。如果游戏需要自定义改方法,在重写改方法后,务必要调用
XGSDKCocos2dxWrapper.getInstance().setGlSurfaceView(glSurfaceView)
将当前的glSurfaceView对给XGSDK持有,否则在回调的时候,将无法在GL线程中完成。

父类修改前:

父类修改后:

修改后的代码如下:

    import com.xgsdk.client.XGCocos2dxActivity;   
    public class CoCosDemo extends XGCocos2dxActivity

3.4 修改Android项目的Android.mk文件

在Android.mk文件中添加的代码如下:

    LOCAL_LDLIBS :=-llog
    LOCAL_SRC_FILES := hellocpp/main.cpp \
                   ../../Classes/AppDelegate.cpp \
                   ../../Classes/XGCocosDemo.cpp \
                   ../../Classes/ProtocolXGSDK.cpp \
                   hellocpp/ProtocolXGSDKAndroid.cpp

3.5 在AndroidManifest.xml添加权限

在AndroidManifest.xml文件中添加权限:
添加的代码如下:

    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.GET_TASKS" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

3.6 在AndroidManifest.xml修改Application

在AndroidManifest.xml文件中修改Application,修改如下图:

修改的代码如下:

    <application
        android:name="com.xgsdk.client.api.XGApplication"
        android:label="@string/app_name"
        android:icon="@drawable/icon">

3.7 在AndroidManifest.xml修改Activity:

    <activity android:name="com.xgsdk.client.CoCosDemo"
              android:label="@string/app_name"
              android:screenOrientation="landscape"
              android:theme="@android:style/Theme.NoTitleBar.Fullscreen"
              android:configChanges="fontScale|orientation|keyboardHidden|locale|navigation|screenSize|uiMode"
              android:configChanges="orientation">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>

4.接入前的初始化工作

1.首先先确认ProtocolXGSDK.h头文件和ProtocolXGSDK.cpp源文件已经按照3.2拷贝到相应目录下。
2.然后在使用到ProtocolXGSDK的地方首先导入头文件"ProtocolXGSDK.h",例如在我们的Demo中添加如图中所示代码:

添加的代码是:

    #include "ProtocolXGSDK.h"

3.用户要继承并且实现回调类,如图:

4.然后在游戏的类中声明一个指向ProtocolXGSDK的指针mXgSdk和指向XGSDKTestCallback的指针,如图:

添加的代码是:

    ProtocolXGSDK *mXgSdk;
    XGSDKTestCallback *mTestListener;

5.需要在层的init()函数中初始化ProtocolXGSDK和XGSDKTestCallback,如图加入代码:

添加的代码是:

    mXgSdk = ProtocolXGSDK::getInstance();

    if(mXgSdk)
    {
      mTestListener = new XGDemoCallback(mXgSdk);
      mXgSdk->setListener(mTestListener);
    }else
    {
        mTestListener = NULL;
    }

按文档完成第4和5节的所有配置和初始化步骤后即可开始接入西瓜的接口。

所有必接接口必须进行接入!

5. 用户接口

5.1 初始化回调接口

初始化失败后回调此回调方法,参考代码:


    void XGSDKTestCallback::onInitSuccess(int code, const char * msg, const char* channelCode){
        //初始化成功,游戏此回调中实现初始化失败后的逻辑
    }
    void XGSDKTestCallback::onInitFail(int code, const char * msg, const char* channelCode){
        //初始化失败,游戏此回调中实现初始化失败后的逻辑
    }

关于参数的说明:

  • code:返回的错误码,详情请见
  • 错误码表
  • msg:返回的信息
  • channelCode:渠道的错误码

5.2 登录接口(必接)

接口定义:void login(const char *customParams = "");
接口说明:在相应的位置调用登录接口,此接口将调出渠道的登录界面,并将登录的结果回调通知游戏。
代码示例:

    mXgSdk->login();

关于参数的说明:

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

请勿在游戏启动后直接调用此接口,部分渠道初始化时间较长,初始化不成功调用登录接口会出现游戏崩溃等问题,建议添加用户登录界面,由用户点击触发登录操作

5.3 登录回调

回调说明:游戏客户端调用西瓜SDK登录接口后,西瓜SDK处理完所有流程后回调。 代码示例:

    void XGSDKTestCallback::onLoginSuccess(int code, const char * authInfo){
        //登录成功,游戏在此回调中实现登录成功后的逻辑
    }
    void XGSDKTestCallback::onLoginFail(int code, const char * msg, const char* channelCode){
        //登录失败,游戏在此回调中实现登录失败后的逻辑
    }
    void XGSDKTestCallback::onLoginCancel(int code, const char * msg){
        //登录取消,游戏在此回调中实现登录取消后的逻辑
    }

关于参数的说明:

  • code:返回的错误码,详情请见
  • 错误码表
  • msg:返回的信息,登录成功返回的信息是Json格式的Base64编码的字符串,需要解码后使用,游戏需要从此处获得uid
  • channelCode:渠道错误码
  • authInfo:验证信息( 因为部分渠道的authInfo比较长,建议游戏留1024长度

5.4 登出接口

接口定义:void logout(const char *customParams = "");
接口说明:在相应的位置调用登出接口,此接口将调用渠道的登出方法,并将登出的结果回调通知游戏。 代码示例:

    mXgSdk->logout();

关于参数的说明:

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

5.5 登出回调

回调说明:游戏客户端调用西瓜退出帐号接口后,西瓜SDK处理完登出帐号流程后回调。
代码示例:


    void XGSDKTestCallback::onLogoutFinish(int code, const char * msg){
        //登出完成,游戏在此回调中根据code来实现登出完成后的逻辑
    }

关于参数的说明:

  • code:返回的完成码,详情请见 错误码表
  • msg:返回的信息

5.6 退出接口(必接)

接口定义:void exit(const char *customParams = "");
接口说明:在相应的位置调用退出接口,此接口将调用渠道的退出方法,会尝试退出游戏,并将结果通过退出回调通知游戏。
代码示例:


    mXgSdk->exit();

5.7 退出回调

回调说明:游戏客户端调用退出游戏接口,西瓜SDK处理完退出帐号流程后回调。
代码示例:

    void XGSDKTestCallback::doExit(){
        //退出游戏成功,游戏在此回调中实现退出游戏后的逻辑
    }
    void XGSDKTestCallback::onNoChannelExiter(){
        //如果渠道没有退出方法,则使用游戏的退出,游戏需要在此回调实现退出游戏逻辑
    }

5.8 释放资源接口(必接)

接口定义:void releaseResource();
接口说明:用户退出游戏时释放资源接口。
代码示例:


    mXgSdk->releaseResource();

6.充值接口

6.1 支付接口(必接)

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

    PayInfo payInfo;
    payInfo.uid = "123456";
    payInfo.productId = "payment017";
    payInfo.productName = "大宝剑";
    payInfo.productDesc = "倚天不出谁与争锋";
    payInfo.productUnit = "个";
    payInfo.productUnitPrice = 1;
    payInfo.productQuantity = 1;
    payInfo.totalAmount = 1;
    payInfo.payAmount = 1;
    payInfo.currencyName = "CNY";
    payInfo.roleId = "1234";
    payInfo.roleName = "yeye";
    payInfo.roleLevel = "65";
    payInfo.roleVipLevel = "8";
    payInfo.serverId = "11";
    payInfo.zoneId = "33";
    payInfo.partyName = "丐帮";
    payInfo.customInfo = "customInfo";
    payInfo.virtualCurrencyBalance = "0";
    payInfo.gameTradeNo = "12480";
    payInfo.gameCallbackUrl = "/sdkserver/receivePayResult";
    payInfo.additionalParams = "";
    mXgSdk->pay(payInfo);

关于PayInfo的成员说明:

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

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

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

支付场景

场景一: 某个玩家,购买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 商品单价(单位分) 无需传

6.2 支付回调

游戏客户端调用西瓜支付接口后,西瓜SDK处理完所有支付流程后回调。

    void XGSDKTestCallback::onPaySuccess(int code, const char* msg, const char* gameTradeNo, const char* xgTradeNo){
        //支付成功,游戏在此回调中实现支付成功后的逻辑
    }
    void XGSDKTestCallback::onPayFail(int code, const char* msg, const char* gameTradeNo, const char* channelCode, const char* channelMsg){
        //支付失败,游戏在此回调中实现支付失败后的逻辑
    }
    void XGSDKTestCallback::onPayProgress(int code, const char* msg, const char* gameTradeNo, const char* channelCode, const char* channelMsg){
        //支付正在处理,游戏在此回调中实现支付正在处理的逻辑
    }

关于参数的说明:

  • code:返回的错误码,详情请见错误码表
  • msg:返回的信息
  • gameTradeNo:游戏的订单ID
  • xgTradeNo:西瓜的订单ID
  • channelCode:渠道错误码
  • channelMsg:渠道错误信息

7.统计接口

7.1 创建角色(必接)

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

    RoleInfo roleInfo;
    roleInfo.roleId = "1000";
    roleInfo.roleType = "弓箭手";
    roleInfo.roleCreateTime = "1461722392";
    roleInfo.roleName = "东方不败";
    roleInfo.roleLevel = "1";
    roleInfo.roleVipLevel = "0";
    roleInfo.serverId = "0";
    roleInfo.zoneId = "1";
    mXgSdk->onCreateRole(roleInfo);

类型RoleInfo结构体定义在ProtocolXGSDK.h头文件中:

    struct RoleInfo {
        const char *uid;
        const char *roleId;
        const char *roleName;
        const char *roleType;
        const char *roleCreateTime;
        const char *roleLevel;
        const char *roleVipLevel;
        const char *serverId;
        const char *zoneId;
        const char *serverName;
        const char *zoneName;
        const char *partyName;
        const char *gender;
        const char *balance;
        const char *ageInGame;
        const char *ext;
    };

关于RoleInfo的成员说明:

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

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

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

7.2 角色升级(必接)

必接接口
接口定义:void onRoleLevelup(RoleInfo &);
接口说明:统计接口在角色升级时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo的参数。
代码示例:

    RoleInfo roleInfo;
    roleInfo.roleId = "1000";
    roleInfo.roleType = "弓箭手";
    roleInfo.roleCreateTime = "1461733392";
    roleInfo.roleName = "东方不败";
    roleInfo.roleLevel = "2";
    roleInfo.roleVipLevel = "0";
    roleInfo.serverId = "0";
    roleInfo.zoneId = "1";
    mXgSdk->onRoleLevelUp(roleInfo);

类型RoleInfo结构体定义在ProtocolXGSDK.h头文件中:

具体限制参考7.1的RoleInfo数据说明

7.3 进入游戏(必接)

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

    RoleInfo roleInfo;
    roleInfo.roleId = "1000";
    roleInfo.roleType = "弓箭手";
    roleInfo.roleName = "东方不败";
    roleInfo.roleLevel = "1";
    roleInfo.roleVipLevel = "0";
    roleInfo.serverId = "0";
    roleInfo.zoneId = "1";
    mXgSdk->onEnterGame(roleInfo);

类型RoleInfo结构体定义在ProtocolXGSDK.h头文件中:

具体限制参考7.1的RoleInfo数据说明

8.扩展接口

8.1 切换账号

接口定义:void switchAccount(const char *customParams = "");
接口说明:在相应的位置调用切换账号接口,此接口将调用渠道的切换账号方法,并会产生登出回调来通知游戏。
代码示例:

    mXgSdk->switchAccount();

关于参数的说明:

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

8.2 获取渠道ID

接口定义:char *getChannelId();
接口说明:获取channelId。channelId为渠道ID。
代码示例:

    char *channelId = mXgSdk->getChannelId();

8.3 是否已打渠道包接口

接口定义:void hasPackedChannel();

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

mXgSdk->hasPackedChannel();

8.4 游戏加载资源接口

接口定义:void onGameLoadResource();

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

代码示例:

mXgSdk->onGameLoadResource();

8.5 游戏加载配置接口

接口定义:void onGameLoadConfig();

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

代码示例:

mXgSdk->onGameLoadConfig()

8.6 打开公告接口

接口定义:void onOpenAnnouncement();

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

代码示例:

mXgSdk->onOpenAnnouncement();

8.7 关闭公告接口

接口定义:void onCloseAnnouncement();

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

代码示例:

mXgSdk->onCloseAnnouncement();

8.8 新手任务完成接口

接口定义:void onNewUserMission(RoleInfo& roleInfo);

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

代码示例:

RoleInfo roleInfo;
roleInfo.roleId = "1000";
roleInfo.roleType = "弓箭手";
roleInfo.roleName = "onEvent";
roleInfo.roleLevel = "1";
roleInfo.roleVipLevel = "13";
roleInfo.serverId = "0";
roleInfo.zoneId = "1";
mXgSdk->onNewUserMission(roleInfo);

类型RoleInfo结构体定义在ProtocolXGSDK.h头文件中:

具体限制参考7.1的RoleInfo数据说明

8.9 自定义事件

接口定义:void onEvent(RoleInfo &, const char eventId, const char eventDesc,int eventValue, const char* eventBody="");

接口说明:统计接口在游戏自定义事件时调用该接口上传角色数据,角色升级需要传入类型为RoleInfo等参数。

代码示例:

RoleInfo roleInfo;
roleInfo.roleId = "1000";
roleInfo.roleType = "弓箭手";
roleInfo.roleName = "onEvent";
roleInfo.roleLevel = "1";
roleInfo.roleVipLevel = "13";
roleInfo.serverId = "0";
roleInfo.zoneId = "1";
mXgSdk->onEvent(roleInfo,"test.event","test/event/desc",1,"{\"prop1\":\"value1\"}");

类型RoleInfo结构体定义在ProtocolXGSDK.h头文件中:

具体限制参考7.1的RoleInfo数据说明

8.10 任务开始

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

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

代码示例:

RoleInfo roleInfo;
roleInfo.roleId = "1000";
roleInfo.roleLevel = "1";
roleInfo.roleVipLevel = "13";
roleInfo.serverId = "0";
roleInfo.zoneId = "1";
roleInfo.roleName = "onMissionBegin";
mXgSdk->onMissionBegin(roleInfo,"10001","第二章节-第四关",1,150);

类型RoleInfo结构体定义在ProtocolXGSDK.h头文件中:

具体限制参考7.1的RoleInfo数据说明

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

序号 参数 参数类型 最大长度 说明 必须
1 missionId 字符串 100 任务/关卡ID Y
2 missionName 字符串 100 任务/关卡名称 Y
3 doMissionTimes 整数 执行关卡/任务的次数 Y
4 roleCurrentPower 整数 角色当前的体力值 Y

8.11 任务成功

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

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

代码示例:

RoleInfo roleInfo;
roleInfo.roleId = "1000";
roleInfo.roleLevel = "1";
roleInfo.roleVipLevel = "13";
roleInfo.serverId = "0";
roleInfo.zoneId = "1";
roleInfo.roleName = "onMissionSuccess";
mXgSdk->onMissionSuccess(roleInfo,"10001","第二章节-第四关",1,150);

类型RoleInfo结构体定义在ProtocolXGSDK.h头文件中:

具体限制参考7.1的RoleInfo数据说明

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

序号 参数 参数类型 最大长度 说明 必须
1 missionId 字符串 100 任务/关卡ID Y
2 missionName 字符串 100 任务/关卡名称 Y
3 doMissionTimes 整数 执行关卡/任务的次数 Y
4 roleCurrentPower 整数 角色当前的体力值 Y

8.12 任务失败

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

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

代码示例:

RoleInfo roleInfo;
roleInfo.roleId = "1000";
roleInfo.roleLevel = "1";
roleInfo.roleVipLevel = "13";
roleInfo.serverId = "0";
roleInfo.zoneId = "1";
roleInfo.roleName = "onMissionFail";
mXgSdk->onMissionFail(roleInfo,"10001","第二章节-第四关",1,150);

类型RoleInfo结构体定义在ProtocolXGSDK.h头文件中:

具体限制参考7.1的RoleInfo数据说明

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

序号 参数 参数类型 最大长度 说明 必须
1 missionId 字符串 100 任务/关卡ID Y
2 missionName 字符串 100 任务/关卡名称 Y
3 doMissionTimes 整数 执行关卡/任务的次数 Y
4 roleCurrentPower 整数 角色当前的体力值 Y

8.13 获得虚拟货币

接口定义:void onVirtualCurrencyPurchase(RoleInfo& roleInfo, int amount, const char virtualCurrencyType, int virtualCurrencyTotal, const char gameTradeNo);

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

注意该接口需要在游戏服务器通知游戏客户端的时候才进行数据上报,在其他地方上报数据,会造成数据错误 代码示例:

RoleInfo roleInfo;
roleInfo.roleId = "1000";    
roleInfo.roleLevel = "1";
roleInfo.roleVipLevel = "13";
roleInfo.serverId = "0";
roleInfo.zoneId = "1";
roleInfo.roleName = "onVirtualCurrencyPurchase";
mXgSdk->onVirtualCurrencyPurchase(roleInfo, 100, "元宝", 10100, "12345678");

类型RoleInfo结构体定义在ProtocolXGSDK.h头文件中:

具体限制参考7.1的RoleInfo数据说明

8.14 赠送虚拟货币

接口定义:void onVirtualCurrencyReward(RoleInfo& roleInfo, int amount, const char virtualCurrencyType, int virtualCurrencyTotal, const char gainChannel, const char gainChannelType, const char gameTradeNo);

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

代码示例:

RoleInfo roleInfo;
roleInfo.roleId = "1000";    
roleInfo.roleLevel = "1";
roleInfo.roleVipLevel = "13";
roleInfo.serverId = "0";
roleInfo.zoneId = "1";
roleInfo.roleName = "onVirtualCurrencyReward";
mXgSdk->onVirtualCurrencyReward(roleInfo, 15, "元宝", 10115, "每日登录奖励", "日常任务", "12345678");

类型RoleInfo结构体定义在ProtocolXGSDK.h头文件中:

具体限制参考7.1的RoleInfo数据说明

8.15 消费虚拟货币

接口定义:void onVirtualCurrencyConsume(RoleInfo& roleInfo, int amount, const char virtualCurrencyType, int virtualCurrencyTotal, const char itemName, int itemNum, const char *itemType);

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

代码示例:

RoleInfo roleInfo;
roleInfo.roleId = "1000";    
roleInfo.roleLevel = "1";
roleInfo.roleVipLevel = "13";
roleInfo.serverId = "0";
roleInfo.zoneId = "1";
roleInfo.roleName = "onVirtualCurrencyConsume";
mXgSdk->onVirtualCurrencyConsume(roleInfo, 8, "元宝", 10107, "十连抽", 10, "幸运大转盘");

类型RoleInfo结构体定义在ProtocolXGSDK.h头文件中:

具体限制参考7.1的RoleInfo数据说明

8.16 提供给游戏的动态接口

接口定义:char callXGMethod(const char methodName, const char paramsJsonString, const char customInfo);

接口说明:部分特殊渠道需要用到的动态接口(如华为)。

代码示例:

char * ret;
ret = mXgSdk->callXGMethod("initSDK","","");

8.17 西瓜SDK通用的回调

回调说明:游戏客户端调用动态接口,西瓜SDK处理完提供给游戏的动态事件后回调。

代码示例:

void onXGGenericCallBack(int code, const char* customInfo, const char* resultJsonString)
{
 //退出游戏成功,游戏在此回调中实现退出游戏后的逻辑
}

关于参数的说明:

code:返回的错误码,详情请见错误码表

customInfo:透传字段

resultJsonString:根据特定的逻辑需要,返回特定的结果

9.运营活动接口

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

接口定义:

void openWebActivity(const char* uid, const char* activityType, const char* roleId, const char* zoneId, const char* serverId)

接口说明:打开活动页面

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

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

接口定义:

void exchangeGiftCode(const char* uid, const char* roleId, const char* zoneId, const char* serverId, const char* giftCode)

接口说明:礼包码兑换

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

回调:

void onExchangeGiftCodeFinish(const char* code, const char* msg)
参数 说明 必须
code 结果代码,0为成功,其它为失败 Y
msg 成功或者错误信息 N

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

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

接口定义:

// 发送验证码  
void sendCaptcha(const char* mobileNumber, const char* uid, const char* serverId, const char* zoneId, const char* roleId, const char* roleName)

// 绑定手机号  
void bindMobile(const char* mobileNumber, const char* uid, const char* serverId, const char* zoneId, const char* roleId, const char* roleName, const char* captcha)

接口说明:发送验证码

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

回调:

void onSendCaptchaFinish(const char* code, const char* msg)
参数 说明 必须
code 结果代码,0为成功,其它为失败 Y
msg 成功或者错误信息 N

接口说明:绑定手机号

参数 参数类型 最大长度 说明 必须
mobileNumber const char* 11 手机号 Y
uid const char* 128 用户ID,游戏必须使用登录时西瓜服务器返回的uid Y
serverId const char* 32 游戏服ID Y
zoneId const char* 32 区ID Y
roleId const char* 32 角色ID Y
roleName const char* 64 角色名 Y
captcha const char* - 接收到的手机验证码 Y

回调:

void onBindMobileFinish(const char* code, const char* msg)
参数 说明 必须
code 结果代码,0为成功,其它为失败 Y
msg 成功或者错误信息 N

9.3.2 根据游戏ID和UID查看是否绑定了手机号

接口定义:void getBindInfoByUid(const char* uid);

接口说明:根据游戏ID和UID查看是否绑定了手机号。

代码示例:

mXgSdk->getBindInfoByUid(uid);

9.3.3 根据游戏ID和UID查看是否绑定了手机号回调

游戏客户端调用根据游戏ID和UID查看是否绑定了手机号接口后,西瓜SDK处理完手机绑定账号状态后回调

void XGSDKTestCallback::onGetBindInfoByUid(const char* code, const char* msg){
    // 根据code和msg 游戏处理相应逻辑
}

关于参数的说明:

code:返回的错误码,详情请见错误码表

msg:返回的信息

9.3.4 根据游戏ID和手机号查看是否绑定了手机号

接口定义:void getBindInfoByMobile(const char* mobile);

接口说明:根据游戏ID和手机号查看是否绑定了手机号。

代码示例:

mXgSdk->getBindInfoByMobile(mobile);

9.3.5 根据游戏ID和手机号查看是否绑定了手机号回调

游戏客户端调用根据游戏ID和手机号查看是否绑定了手机号接口后,西瓜SDK处理完手机绑定账号状态后回调

void XGSDKTestCallback::onGetBindInfoByMobile(const char* code, const char* msg){
    // 根据code和msg 游戏处理相应逻辑
}

关于参数的说明:

code:返回的错误码,详情请见错误码表

msg:返回的信息

9.4 问卷调查

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

9.4.1 初始化问卷

通知Android初始化回调,请参考初始化回调接口,设置callback后就初始化问卷,无需游戏再另行调用。

9.4.2 刷新问卷

接口定义:void refreshQuestionnaire(RoleInfo& roleInfo, const char missionId, const char missionName, const char* customInfo);

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

参数说明:

RoleInfo roleInfo;
roleInfo.roleId = "1000";    
roleInfo.roleLevel = "1";
roleInfo.roleVipLevel = "13";
roleInfo.serverId = "0";
roleInfo.zoneId = "1";
roleInfo.roleName = "refreshQuestionnaire";

类型RoleInfo结构体定义在ProtocolXGSDK.h头文件中:

具体限制参考7.1的RoleInfo数据说明

其它参数说明:

输入参数 数据类型 说明 可空
missionId string 任务ID 可为空
missionName string 任务名称 可为空
customParams string json串格式自定义参数 可为空

代码样例:

mXgSdk->refreshQuestionnaire(roleInfo, missionId, missionName, customInfo);

9.4.3 打开问卷

接口定义:void openXgQuestionnaire(int widthPercent, int heightPercent, const char* customInfo);

接口说明:当游戏有通过游戏用户在线分发问卷的需求时,可以通过本SDK的接入简化开发提高效率节省成本。

参数说明:widthPercent:打开问卷窗口的宽度占屏幕的百分比,100表示全屏。 heightPercent:打开问卷窗口的高度占屏幕的百分比,100表示全屏。 customParams:json串格式自定义参数。

代码样例:

mXgSdk->openXgQuestionnaire(widthPercent, heightPercent, customInfo);

9.5 更新服务回调接口

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

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

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

10 渠道接入要点须知

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