回到顶部
TOP

Air客户端接入文档-1.5.3

一、概述

此文档为Air游戏接入文档,使用其他引擎的游戏开发者请参考相应接入文档。

注:1.需要接入ios的开发者请将air sdk的版本升级到17以上。2.请勿在代码中使用LJMainActivity字眼,详情可咨询运营人员。

二、环境搭建

2.1 下载SDK

到资源下载页面下载Air引擎SDK。

2.2 导入ANE

解压下载的SDK,找到ljsdk.ane文件,添加到FlashBuilder项目工程中


2.3 添加资源

2.3.1 添加Android资源(只接入IOS的游戏可跳过本节)

在SDK文件夹中找到android需要的资源,添加到项目的src目录下

2.3.2 添加IOS资源(只接入Android的游戏可跳过本节)

在SDK文件夹中找到ios需要的资源,添加到项目的src目录下

2.4 工程文件配置

配置“项目名-app.xml”文件

2.4.1 配置id标签

为了通过接口检测,需要在id标签中配置包名,包名格式为:com.ljapps.产品号

(该包名仅用于我方接口检测,并不是最终渠道包名,各渠道包名可在后台自定义配置)

2.4.2 配置android标签(只接入IOS的游戏可跳过本节)

在android标签中加入如下代码

<manifestAdditions><![CDATA[
    <manifest android:installLocation="auto">
        <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />  <!-- 检测网络状态 -->
        <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />     <!-- 获取mac地址作为用户的备用唯一标识 -->
        <uses-permission android:name="android.permission.READ_PHONE_STATE" />      <!-- 获取用户手机的IMEI,用来唯一的标识用户。 -->
        <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /><!-- 缓存资源优先存入SDcard -->
        <uses-permission android:name="android.permission.INTERNET" />              <!-- 允许应用程序联网,以便向我们的服务器端发送数据。 -->
        <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />  <!-- 用于评论模块分享位置信息 -->
        <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /><!-- 用于评论模块分享位置信息 -->
        <application android:debuggable="true" android:name="com.xinmei365.game.proxy.XMApplication">
            <activity
                android:name="com.ane.sdk.XMAirSplashActivity"
                android:configChanges="orientation|keyboardHidden|screenSize"
                android:screenOrientation="landscape" >
            </activity>
            <activity
                android:name="com.xinmei365.game.proxy.XMSDKLoginActivity"
                android:configChanges="orientation|keyboardHidden|screenSize"
        android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"/>
            <activity
                android:name="com.alipay.sdk.app.H5PayActivity"
                android:configChanges="orientation|keyboardHidden|navigation"
                android:exported="false"
                android:screenOrientation="behind"
                android:windowSoftInputMode="adjustResize|stateHidden" >
             </activity>
             <meta-data android:name="XMGAME_SPLASH_BG_COLOR" android:value="0xffffffff"/>
             <meta-data android:name="XMGAME_GAME_ACTIVITY" android:value="air.com.ljapps.p645.AppEntry"/>
             <meta-data android:name="XMGAME_CHANNEL_CODE" android:value="5afbe59b6ba84330852b71d40f8dac02" />
             <meta-data android:name="XMGAME_PRODUCT_CODE" android:value="p645" />
             <meta-data android:name="CHANNEL_LABEL" android:value="TestLabel" />
        </application>
    </manifest>
]]></manifestAdditions>

根据应用需求,修改闪屏的横竖屏、闪屏的背景色、游戏界面Activity类名:

注:闪屏背景色的值必须为8位(不算0x)带透明度的颜色值

XMGAME_CHANNEL_CODE:测试渠道代码
XMGAME_PRODUCT_CODE:产品代码
以上参数通过开发者后台获取,具体可咨询运营人员

2.4.3 配置iPhone标签(只接入Android的游戏可跳过本节)

在iPhone标签中加入如下代码

<InfoAdditions><![CDATA[
    <key>UIDeviceFamily</key>
    <array>
        <string>1</string>
        <string>2</string>
    </array>
    <key>XMGAME_PRODUCT_CODE</key>
    <string>huoying</string>
    <key>XMGAME_CHANNEL_CODE</key>
    <string>537a369ae5cf451f80beaf9a228ae73c</string>
    <key>CHANNEL_LABEL</key>
    <string>TestLabel</string>
    <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleTypeRole</key>
            <string>Editor</string>
            <key>CFBundleURLName</key>
            <string>AliPay</string>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>com.ljapps.p645</string>
            </array>
        </dict>
    </array>
    <key>flash_air_ios</key>
    <true/>
]]></InfoAdditions>
<requestedDisplayResolution>high</requestedDisplayResolution>

修改上述加入代码的部分内容,如下图

三、接口接入


SDK通用必接接口:初始化接口、登录接口、注销接口、支付接口、用户信息扩展接口;
接入IOS平台必接接口:通用必接接口;
接入Android平台必接接口:通用必接接口、退出接口、释放资源接口;

另外登录成功后还需进行验证登录信息的操作,请按需求正确接入。

3.1 初始化接口

接口原型:
public function init(callback : XMCallback) : void;
调用示例:
GameProxy.getInstance().init(callback);
参数说明:
callback 回调接口,不可以为null,否则收不到任何回调
接口说明:

请在调用其他接口之前调用初始化接口,并保证每一次程序运行期间,只调用一次,多次调用可能造成游戏崩溃。

回调接口原型:
public interface XMCallback
{
    /**
     * 初始化接口回调
     *
     * code:接口调用结果代码,0代表失败(XMConst.CODE_FAILURE),1代表成功
     * (XMConst.CODE_SUCCESS)
     * msg:附加消息
     *
     * */
    function onInit(code : int, msg : String) : void;
    /**
     * 登录接口回调
     *
     * code:接口调用结果代码,0代表失败(XMConst.CODE_FAILURE),1代表成功
     * (XMConst.CODE_SUCCESS)
     * msg:附加消息
     * user:用户信息,登录成功时为XMUser对象,登录失败时为null
     *
     * */
    function onLogin(code : int, msg : String, user : XMUser) : void;
    /**
     * 注销接口回调
     *
     * code:接口调用结果代码,0代表失败(XMConst.CODE_FAILURE),1代表成功
     * (XMConst.CODE_SUCCESS)
     * msg:附加消息
     *
     * */
    function onLogout(code : int, msg : String) : void;
    /**
     * 支付接口回调
     *
     * code:接口调用结果代码,0代表失败(XMConst.CODE_FAILURE),1代表成功
     * (XMConst.CODE_SUCCESS)
     * msg:附加消息
     *
     * */
    function onPay(code : int, msg : String) : void;
    /**
     * 渠道有退出界面的回调
     *
     * msg:附加消息
     *
     * */
    function onChannelExit(msg : String) : void;
    /**
     * 渠道没有退出界面的回调(需要显示游戏的退出界面)
     *
     * msg:附加消息
     *
     * */
    function onGameExit(msg : String) : void;
}

3.2 用户相关接口

3.2.1 用户登录接口


在初始化init没有结束前不要调用login方法,因为部分渠道需要完成初始化后才能进行登录操作。

接口原型:
public function login() : void;
调用示例:
GameProxy.getInstance().login();
接口说明:

1)请勿游戏启动后直接调用此接口,部分渠道初始化时间较长,初始化不成功调用登录接口会出现游戏崩溃等问题,建议添加用户登录界面,由用户点击触发登陆操作。
2)由于某些渠道不会返回登录失败的回调,所以游戏请勿在调用登录接口后进行等待操作,请保证游戏在退出渠道登录界面后可以再次进行登录。

用户信息原型:
public class XMUser
{
    private var userId : String;            //用户id
    private var userName : String;            //用户名
    private var token : String;                //用户token
    private var channelId : String;            //渠道id
    private var channelUserId : String;     //渠道用户id
    private var productCode : String;        //产品号
}

3.2.2 用户注销接口

接口原型:
public function logout() : void;
调用示例:
GameProxy.getInstance().logout();
接口说明:

登出操作用于用户切换帐号等事件处理,有如下不同处理方式:
a)若游戏中存在登出或者切换帐号的按钮,则可在点击按钮时进行登出接口调用,在登出回调中进行重新登录等操作。
b)若游戏中不存在登出或者切换帐号的按钮时,建议修改游戏添加登出或切换帐号按钮,若实在无法添加,可在退出游戏前调用登出接口,这种情况下会存在部分渠道会审核不通过的情况,需游戏方与渠道去进行沟通。

3.3 支付接口


注:1.支付接口只支持定额支付。2.收到支付成功的回调后,请到游戏服务器查询订单状态后再发放道具,请勿直接做支付成功的UI提示;收到支付失败的回调后可以进行明确的充值失败提示。

接口原型:
public function pay(amount : int, itemName : String, count : int, customParams : String, callBackUrl : String) : void;
调用示例:
GameProxy.getInstance().pay(100, "钻石", 1, "customParams", "www.baidu.com");
参数说明:
amount 支付总金额,<span style="color:red">单位人民币分</span>
itemName 游戏币名称,如金币、钻石等
count 购买商品数量,如100钻石,传入100;10魔法石,传入10
customParams 游戏开发者自定义字段,我方不会对其做任何处理,会与支付结果一起通知到游戏服务器,游戏服务器可通过该字段判断交易的详细内容(金额角色等)
callBackUrl 支付结果通知地址,支付完成后我方后台会向该地址发送支付通知,通知交易结果(如金额、customParams等)

3.4 退出接口(仅用于Android平台)

注意:接入退出接口之前,请务必阅读《退出接口说明》,否则容易导致接错,漏接等。

接口原型:
public function exit() : void;
调用示例:
GameProxy.getInstance().exit();
接口说明:

在游戏退出前调用退出接口,会有如下不同处理:
1.渠道存在退出界面,如91、360等,回调方法onChannelExit会被调用,在此方法中直接进行退出游戏操作即可,无需再弹退出界面。
2.渠道不存在退出界面,如百度游戏等,回调方法onGameExit会被调用,在此方中需要弹出游戏自己的游戏退出确认界面,否则会出现渠道审核不通过的情况。

3.5 用户信息扩展接口

接口原型:
public function setExtRoleData(obj : Object) : void;
调用示例:
GameProxy.getInstance().setExtRoleData(obj);
参数说明:
_id 当前情景,目前支持 enterServer,levelUp,createRole
roleId 当前登录的玩家角色ID,必须为数字,若如,传入userid
roleName 当前登录的玩家角色名,不能为空,不能为null,若无,传入"游戏名称+username" 如 "刀塔传奇风吹来的鱼"
roleLevel 当前登录的玩家角色等级,必须为数字,若无,传入1
zoneId 当前登录的游戏区服ID,必须为数字,若无,传入1
zoneName 当前登录的游戏区服名称,不能为空,不能为null,若无,传入"游戏名+1区",如 “刀塔传奇1区”
balance 当前用户游戏币余额,必须为数字,若无,传入0
vip 当前用户VIP等级,必须为数字,若无,传入1
partyName 当前用户所属帮派,不能为空,不能为null,若无,传入"无帮派"
extra :扩展字段,某些渠道会使用的特殊信息,默认随便传值,但不可为空
接口说明:

1.以上参数作为动态属性添加到Object对象中,调用此接口时传入Object对象即可。
2.上传数据接口需在三处调用,分别为进入服务器、玩家升级、玩家创建用户角色,同一方法,通过id来区分,有如下四点需注意:
a.游戏中该接口必须调用三次,传入不同的id(enterServer,createRole,levelUp),以区分不同的上传数据;
b.若游戏中无对应接口功能,如游戏中无需创建角色,则可根据自身情况在合适位置进行调用,如登录成功后;
c.在上传游戏数据时,若存在无对应字段值的情况,可传入默认值,具体参见参数说明;
d.游戏中动态变化的值不能写死,如有多个服务器,则zoneId不能传入固定值,部分渠道会进行数据验证,若写死会导致无法通过上线审核。
e.如果需要接入uc渠道,需要多传入角色创建时间(服务器时间),放入extra,值为Long型的十位长度字符串

3.6 释放资源接口(仅用于Android平台)

接口原型:
public function release() : void;
调用示例:
GameProxy.getInstance().release();
接口说明:

该接口必须在退出游戏时调用。

3.7 获取Android应用中Meta信息接口(仅用于Android平台)

接口原型:
public function getMetaDataConfig(key : String) : String;
调用示例:
GameProxy.getInstance().getMetaDataConfig("key");
参数说明:
key 待获取的meta-data的key值
接口说明:

获取AndroidManifest.xml中的meta-data值

3.8 区分渠道接口

接口原型:
public function getChannelLabel() : String;
调用示例:
GameProxy.getInstance().getChannelLabel();
接口说明:

获取渠道标识,具体参考官网文档《如何区分渠道

四、导出包及必要的修改

注意:本章所有的导出操作都基于Adobe Flash Builder 4.7

4.1 Android导出操作(只接入IOS的游戏可跳过本节)

4.1.1 导出APK包

第一步:游戏工程右键->导出

第二步:导出页面->FlashBuilder文件夹->发行版

第三步:选择目标平台、选择导出目录和编辑导出文件名

第四步:Air运行时配置,推荐使用运行时绑定选项

第五步:选择证书文件并输入密码

第六步:选择要包括的文件(注:导出Android应用时不要勾选bundle文件

第七步:在本机扩展选项卡中勾选ane

4.1.2 下载解包工具

下载我方提供的解包回编签名工具工具的使用说明在README文件中,请认真阅读使用方法。

4.1.3 修改APK

用我方提供的工具解包导出的APK,编辑其中的AndroidManifest.xml文件

修改后的效果如下图:

4.1.4 回编译APK

回编后的apk包没有签名是无法安装在手机上运行的,需要对回编的apk签名后即可安装在手机运行

4.1.5 签名APK

我方提供的签名只是便于使用者方便安装在手机测试通过我方检测接口等,如果需要正式上传我方后台,建议使用自己的签名对apk进行签名

4.2 IOS导出操作(只接入Android的游戏可跳过本节)

4.2.1 导出IPA包

第一步:游戏工程右键->导出

第二步:导出页面->FlashBuilder文件夹->发行版

第三步:选择目标平台、选择导出目录和编辑导出文件名

第四步:Air运行时配置,只能选择运行时绑定

第五步:选择证书文件并输入密码、选择证书的配置文件

第六步:选择要包括的文件(注:导出IOS应用时不要勾选xm_config_json_format文件和xm_splash_images文件夹

第七步:在本机扩展选项卡中勾选ane、选择IOS的SDK

向上
向下