回到顶部
TOP

Cocos2d-x游戏客户端接入文档



    此文档为Cocos2d-x原生游戏接入文档,使用其他第三方引擎或者语言开发的游戏开发者请参考相应接入文档。接入中涉及的产品代码及测试渠道代码等接入信息需通过开发者后台获取,详见 参数获取。
    对于Cocos2d-x原生接入,IOS和Android共用一套接口,对于同时接入IOS和Android的游戏,游戏只需对不同平台进行简单配置即可导出相应平台的游戏包。如果用户只需接入IOS或者Android其中一个平台,则只需根据本文档关于相应平台接入即可,另外的平台则忽略。

注意:Android接入代码中,请勿使用LJMainActivity字眼命名,详情请咨询运营。

 



该文档面向具有Android或者IOS基础以及开发能力的工程师

关于接口接入须知:

对于原生接口IOS与Android共用,每个平台的接入基本步骤如下,如果游戏已正确接入其中一个平台,则无需再对原生代码进行重新接入,只需根据不同平台进行相应配置即可。

Android接入步骤简介:

1.将Cocos2d-x Android工程导入Eclipse或者Android Studio。

2.导入平台接入jar包到Android工程的lib目录下,以及拷贝平台配置文件到Android工程的assets目录下。

3.修改Android部分代码,并完成闪屏接口接入。

4.修改AndroidManifest文件配置基本权限,注册平台母包所需组件,配置平台信息。

5.完成平台Cocos2d-x原生接入,编译打包测试通过后即可上传母包。

IOS接入步骤简介:

1.将Cocos2d-x IOS工程导入XCode。

2.导入平台Cocos2d-x交互插件,配置平台所需framework及静态库文件,资源bundle等。

3.修改IOS工程的plist文件配置平台所需信息。

4.完成平台Cocos2d-x原生接入,编译打包测试通过。



Android接入:

修改Android工程的配置信息

修改前:

棱镜示例

修改后:

棱镜示例

1.配置平台所需基本权限:

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.GET_TASKS" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <uses-permission
         android:name="android.permission.PACKAGE_USAGE_STATS"
         tools:ignore="ProtectedPermissions" />

2.配置平台参数信息:

修改AndroidManifest.xml, 标签中加入meta-data

    <meta-data android:name="XMGAME_CHANNEL_CODE" android:value="在产品后台产品页面获取" />
    <meta-data android:name="XMGAME_PRODUCT_CODE" android:value="在产品后台产品页面获取" />

3.修改配置Application类:

修改AndroidManifest.xml文件中的application节点

(1)如果游戏有自己的Application类,请确保该Application继承于XMApplication,否则会影响部分渠道登录与支付操作;

(2)如果游戏没有自己的Application类,请直接在AndroidManifest清单的application节点下配置XMApplication;

棱镜示例

4.配置平台所需基本组件:

在Application节点下增加登录Activity声明,否则会影响本地登录调试

    <activity
       android:name="com.xinmei365.game.proxy.XMSDKLoginActivity" />

5.设置游戏包名:

SDK接入完成后,上传的游戏母包需要使用特定的包名,包名规范为:com.ljapps.+产品code,如游戏产品code为p646,则包名可设置为com.ljapps.p646(该报名仅用于我方接口检测,并不是最终渠道包名,各渠道包名可在后台自定义配置),设置方法为修改AndroidManifest.xml文件中manifest标签下的package属性的值,如下图所示:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.ljapps.p646"
    android:versionCode="1"
    android:versionName="1.0" >

6.Android闪屏配置以及代码集成:

1)接入该接口后,开发者可以在游戏后台灵活配置闪屏内容、数量、次序等,该接口不会影响程序原有闪屏(母包中闪屏示意图无需处理,会被平台自行处理,该接口不会影响程序原有闪屏)

2)接入方法,继承 com.xinmei365.game.proxy.XMSplashActivity, 并将该Activity设置为程序启动时的Activity

3)继承说明

参考代码

    public class MySplashActivity extends XMSplashActivity {

            public int getBackgroundColor() {
               // 返回闪屏的背景颜色
               // 当游戏设置的闪屏图片没有办法全屏的时候,请设置与闪屏图片相适应的的背景色
       return Color.WHITE;

    }

    @Override
    public void onSplashStop() {

        // 闪屏结束 进入游戏
        Intent intent = new Intent(this, MainActivity.class);
        startActivity(intent);
        this.finish();

    }

}

AndroidManifest.xml中关于该SplashActivity的声明,要声明为启动Activity

<activity
     android:name="com.channel.channeldemo.MySplashActivity"
     android:configChanges="orientation|keyboardHidden|screenSize"
     android:screenOrientation="portrait" >
     <intent-filter>
         <action android:name="android.intent.action.MAIN" />

         <category android:name="android.intent.category.LAUNCHER" />
     </intent-filter>
 </activity>

IOS接入:

修改IOS工程plist文件配置渠道号和产品编码

plist文件的2种方式,根据情况选择其一。


棱镜示例

用文本编辑工具打开Info.plist文件,在文本后面增加3个string节点,如下图:

棱镜示例

<key>CHANNEL_LABEL</key>
<string>lj_test</string>
<key>XMGAME_CHANNEL_CODE</key>
<string>平台分配的测试渠道号</string>
<key>XMGAME_PRODUCT_CODE</key>
<string>平台分配的产品编码</string>

棱镜示例

点击Info.plist,点击如下图的+号,并手动添加,如下图:

棱镜示例


首先将文档中CPP文件夹下的GameProxy.h头文件与GameProxy.cpp源文件拷贝到游戏的源码目录

接入注意事项:

原生接口Android与IOS完全一致,共同使用,请根据以下文档进行正确接入

在使用到GameProxy的地方首先导入头文件”GameProxy.h”

调用位置:Cocos2dx 主工程的Classes目录下的AppDelegate.cpp中

AppDelegate::applicationDidFinishLaunching方法的最后调用

参考代码:

     #import"GameProxy.h"
     ...
     class InitCallBackImpl:public InitCallBack{
     public:
     virtual void onInitSuccess(const char *msg){
          //初始化成功,请在该回调后再调用登陆,支付等接口
     }
      virtual void onInitSuccess(const char *msg){
          //初始化失败
     }
     }
     ...
     bool AppDelegate::applicationDidFinishLaunching(){
       ...
       GameProxy::Init(new InitCallBackImpl());
       return true;
     }
     ...

参考代码:

 

    class XMUserListenerImpl: public XMUserListener {
        virtual void onLoginSuccess(XMUser *user, const char *customParams) {
            //登录成功游戏拿到用户信息进行处理
        };
        virtual void onLoginFailed(const char *reason,const char *customParams{
            //登录失败,游戏自行处理(可能部分渠道不会回调该方法,请做好兼容处理)
        };
        virtual void onLogout(const char *customParams) {
           //用户出发游戏内登出
           //游戏有登出逻辑,请在该方法内实现,注销游戏内用户并返回游戏登录初始界面
        };
    };

关于返回的User的说明:

userId:游戏区分用户的唯一标识userId,不为空,请用该字段来标示游戏的人物唯一性

channelUserID: 渠道的userId,原样返回,不为空,勿使用该字段来标示游戏人物唯一,多个渠道可能存在重复可能

channelID: 渠道编码,不重复,创建渠道分配

channelLabel: 渠道标识,如豌豆荚会返回wandoujia,方便CP区分渠道(获取渠道标识请参考文档下的工具类)

userName: 渠道的userName,原样返回,可能为空,请做好兼容处理

token: 渠道的token,原样返回,可能为空,请做好兼容处理,长度不要限制

productCode: 产品code,不为空,用于表示产品的唯一

    GameProxy::Login(const char *customParams);

调出渠道登录界面

参数说明:

customParams,自定义标识,登录后原样返回

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

调用该方法需要游戏有登出逻辑,回调用户监听中的onLogout方法

参数说明:

customParams 同Login中定义

登出操作用于用户切换帐号等事件处理,有如下不同处理方式:

1.若游戏中存在登出或者切换帐号的按钮,则可在点击按钮时进行登出接口调用,在登出回调中进行重新登录等操作

2.若游戏中不存在登出或者切换帐号的按钮时,建议修改游戏添加登出或切换帐号按钮,若实在无法添加,可在退出游戏前调用登出接口,这种情况下会存在部分渠道会审核不通过的情况,需游戏方与渠道去进行沟通。


注:支付接口为必接,请根据游戏逻辑选择不定额支付与定额支付其中一种


定额支付,游戏可调用该函数进行指定金额的购买

参数说明:

amount 需要支付金额,单位为人民币分

itemName 商品名称

count 商品数量

constomParams 由游戏开发者定义传入的字符串,回与支付结果一同发送给游戏服务器,游戏服务器可通过该字段判断交易的详细内容(金额 角色等)

callbackUrl 该比支付结果通知给游戏服务器时的通知地址url,交易结束后,系统会向该url发送http请求,通知交易的结果金额callbackInfo等信息

payCallback 当客户端完成交易后回调用该对象的对应方法通知游戏客户端交易结果

注:payCallback中onSuccess回调只代表客户端支付行为完成,需要向服务器查询支付结果,并不代表实际支付结果,onFail代表客户端支付行为失败,对于onSuccess和onFail的通知会根据渠道通知,有部分渠道可能没有该通知,所以请做好游戏兼容处理,无需等待回调

如:购买100钻石,请传入数量count为100,商品名称unitName为钻石;请不要传入数量1,商品名100钻石

参考代码:

 class PayCallBackImpl:public PayCallBack{
        virtual void onPaySuccess(char *successinfo){
           //客户端支付行为完成后回调,不能以此为最后发放商品的依据,并不是所有渠道都回调该方法,请做好兼容处理
        };
        virtual void onPayFail(char *failinfo){
          //客户端支付行为失败回调,并不是所有渠道都回调该方法,请做好兼容处理
        };
    };
    GameProxy::Pay(amount, unitName, count, callBackInfo, callbackUrl, new PayCallBackImpl());

    GameProxy::Exit(LJExitCallBack *exitcallback)

退出接口,当用户在游戏中需要退出游戏时调用该接口

参考代码:

 class ExitCallBackImpl:public LJExitCallBack{
    public:
        virtual void onGameExit(){

           //弹出游戏原生退出界面

        };
        virtual void onChannelExit(){

          //该方法为渠道提供退出界面时候调用
          //退出游戏代码逻辑(如杀死进程)

        };
    };

为兼容各个渠道,请在进入服务器,玩家升级,玩家创建角色这3处位置均调用该接口,如不正确调用,将出现渠道退包情况。传入用户信息的json串,以下为json传对应的key和value值说明,务必传入正确字符

_id 当前情景,请根据相应场景选择后面的场景类型,目前支持 enterServer (进入服务器),levelUp (玩家升级),createRole (玩家创建角色)

roleId 当前登录的玩家角色ID,必须为数字,若无,传入userid

roleName 当前登录的玩家角色名,不能为空,不能为null,若无,传入”游戏名称+userId”

roleLevel 当前登录的玩家角色等级,必须为数字,若无,传入1

zoneId 当前登录的游戏区服ID,必须为数字,若无,传入1,若游戏分区服,请不要传入固定写死的ID,否则会造成渠道退包

zoneName 当前登录的游戏区服名称,不能为空,不能为null,若无,传入 “游戏名称+1服”,若游戏分区服,请不要传入固定写死的区服名,否则会造成渠道退包

balance 当前用户游戏币余额,必须为数字,若无,传入0

vip 当前用户VIP等级,必须为数字,若无,传入1

partyName 当前用户所属帮派,不能为空,不能为null,若无,传入”无帮派”

extra 额外的扩展字段(透传字段用于添加额外信息),若无可传入无意义的字段,但不可为NULL或空字符串

注意 如果需要接入uc渠道,需要多传入角色创建时间(服务器时间),放入extra,值为Long型的十位长度字符串


    GameProxy::Release();

请在最终游戏退出Kill游戏进程前调用该方法


Android接入:

IOS接入:

Android接入:

棱镜示例

棱镜示例

Cocos2dx 2.0版本系列

方式:采用静态代码块loadLibrary方式,如下图:

棱镜示例

Cocos2dx 3.0版本系列

方式:废弃了2.0的方式,需要在AndroidManifest里申明meta-data方式引用,如下图:

 

向上
向下