1、和游戏网游SDK开发文档和游戏网游SDK开发文档（Android版）2014年9月18日文件状态： 草稿 正式发布 正在修改文件标识：当前版本：V2.2.1完成日期：2014-9-18Table of Contents1引言1.1介绍本文档的目的是为中国移动游戏业务合作方开发Android网游提供说明指导，对Android网游SDK的集成方式和步骤进行描述，介绍了游戏业务平台与合作方游戏间的技术开发接口规，以便于游戏开发商开发游戏业务。本文档主要包括以下几方面容：中国移动游戏基地安卓网游业务总体概述、Android网游系统结构及流程说明、Android网游SDK集成步骤、Android网游SD
2、K 接口说明、合作方游戏服务器接口说明、Unity3D引擎游戏适配、常见问题等。本文档适用于中国移动游戏基地安卓网游SDK集成开发者。本文档参考了以下规文档最新版本：序号标准编号标准名称发布单位1QB-D-XXX-XXXX中国移动游戏业务设备规中国移动通信集团公司2QB-D-XXX-XXXX中国移动游戏业务接口规中国移动通信集团公司3QB-D-XXX-XXXX中国移动游戏业务总体技术要求中国移动通信集团公司4QB-D-XXX-XXXX游戏业务平台合作方开发规中国移动通信集团公司5QB-E-XXX-XXXX中国移动游戏大厅客户端规中国移动通信集团公司1.2术语及缩略词词语解释CPContent
3、Provider，容提供商HTTPHyper Text Transfer Protocol，超文本传输协议ICON游戏业务的展示图标LOGO游戏业务容提供商、服务提供商的商标OTAOver The Air，空中无线下载技术SPService Provider，服务提供商SDKSoftware Development Kit 的缩写，中文即“软件开发工具包”。广义上指辅助开发某一类软件的相关文档、例和工具的集合。XMLExtensible Markup Language，可扩展标记语言UAProfile由开放移动联盟提出，描述用户终端的配置信息URLUniversal Resource Loca
4、tor，统一资源定位符点数游戏业务平台中进行各种交易的通用货币计费点游戏在平台申报的激活点信息，包含：计费点名称、价格、及唯一标识代码等信息强制计费点即一次性付费的计费点，通常也是必须要付费的计费点，否则用户无法继续使用游戏或者进入下一关卡。非强制计费点即可重复购买的计费点，通常是游戏中道具或金币，用户可以多次购买的计费点。iGop游戏业务管理平台，完成CP资质评审，游戏业务评审，测试及商用。游戏平台游戏业务通过使用移动游戏SDK与之交互的核心支付平台。游戏服务器合作方按照移动游戏规自行实现的游戏服务器，用于完成同移动游戏平台进行数据交互与通信的服务器。2总体概述2.1总体流程总体流程图总体流
5、程说明合作方开发者需根据此总流程图集成使用移动游戏SDK。必选流程：1、游戏应用配置集成SDK必须先配置游戏运行的必选配置（自定义Application）。此版本SDK需要游戏自定义Application类，加载SDK核心接口容。Application的定义与使用方式详见3.1章节。2、游戏启动画面集成移动SDK启动画面（按照移动游戏规，游戏的首个启动画面必须包含移动游戏LOGO），启动画面展现移动LOGO。启动画面的具体集成方式详见3.2章节。启动画面结束后，需要通过3.2.2接口获得用户是否开启游戏背景音乐的选项。开发者根据此接口返回值设置游戏背景音乐。3、游戏初始化启动画面结束后，进入游
6、戏容，合作方开发者需要对SDK进行初始化，即调用3.3章节，调用此接口的同同时，SDK会进行用户登录。该接口部会进行用户登录，登录流程及接口详见3.4章节。4、游戏付费 用户进入游戏商店就行购买道具时，进入游戏付费流程。付费流程及接口详见3.6章节。5、游戏退出用户游戏结束后，选择退出游戏，合作方开发者需要调用退出接口（3.7章节）完成游戏退出逻辑。可选流程： 按照移动游戏接入规，需要合作方在游戏主菜单添加关于、更多游戏等功能菜单。更多游戏详见3.5章节。2.2集成步骤SDK开发资源包： SDK目录中包含SDK的资源文件，请复制SDK目录中的所有目录与文件，并拷贝至各自的游戏工程中），如下：1
7、）拷贝APIA）拷贝Native API将SDK/libs目录中的文件全部拷贝到游戏libs下。B）拷贝JAVA API将SDK/runtime目录文件， 直接复制到游戏根目录下， 切勿将runtime下面的jar文件放入libs下面编译，否则会报编译错误，例如：bad range(不同编译环境均需要按照此要求引用此jar，如遇编译问题，请参考章节4)。2）拷贝SDK资源A）将SDK/res文件夹中的容拷贝至游戏工程目录中。B）将SDK/assets文件夹中的所有文件拷贝至游戏相同的工程目录中，不能删除其中的任何文件， 否则导致非正常运行。3）添加SDK提供的Activity引用将SDKAnd
8、roidManifest.xml.activity.txt中的文本Copy到游戏的AndroidManifest.xml中。Activity的横竖屏配置（android:screenOrientation），最好设置成游戏主界面的横竖屏设置。4）添加SDK需要的use-permision将SDKAndroidManifest.xml.permision.txt中的文本Copy到游戏的AndroidManifest.xml 注意：不要重复添加use-permision项。5）为游戏主入口添加中国移动游戏基地标识（Intent-Filter） 为游戏主入口Activity添加中国移动游戏基地标识，
9、如下：注意:如果游戏的主入口Activity没有添加移动游戏标识,则测试会不通过。示例工程:（Sample目录中为游戏计费实现的实例，详细的Sample程序源文件在Sample/GameSample/文件夹下），请不要直接拷贝Sample的示例代码，根据游戏时间情况，处理接口调用逻辑。3详细接口3.1应用程序加载接口游戏开发者在集成SDK，务必先自定义全局Application。Application里面代码必须包含，下行代码(注意：该接口必须放在Application中进行加载，不可放在Activity的onCreate中)：System.loadLibrary(megjb);示例代码如下:
10、(注意:该类的package路径应用必须与AndroidManifest.xml中的一致,如下代码示例中,黄色标注,否则游戏无常启动)。package.cmgame.sdk;public class CmgameApplication extends Application public void onCreate() try System.loadLibrary(megjb); catch(Exception e) AndroidManifest.xml中配置： 3.2游戏启动接口3.2.1 游戏启动画面配置按照中国移动合作方游戏接入规，需要在游戏的首个启动页面展现移动游戏相关LOGO，此规
11、要求SDK已经自带完成，游戏开发者只需要按照特定集成方式使用即可。具体使用方法：在AndroidManifest.xml中的主入口Activity配置为GameOpenActivity（即SDK提供的游戏启动画面的Activity）。游戏原来的主入口Activity请添加到res/values/g_strings.xml中的g_class_name字符串中，使得启动画面完成后即启动游戏。例如：your.game.ui.Entry 特殊说明：如果游戏使用的API Level是小于等于3的情况，即：游戏是基于Android 1.5及以下API版本开发的，那么还需要设置一个低版本标识，(API 小于
12、4的情况，Android本身不支持图片自适配，故可能导致SDK中的界面元素被放大，UI效果差)。true，这样SDK会读取该标识，并完成开机界面的自适配。3.2.2 游戏音效接口 游戏启动的第一个界面(3.2.1章节)，即：用户选择是否开启音效界面，用户选择是，则游戏需要实现有背景音乐的逻辑，否则反之，游戏开发者可根据此接口判断用户是否选择了开启音效：接口定义boolean GameInterface.isMusicEnabled()返回值返回false，则游戏中应关闭音效，否则开启。3.3游戏初始化接口游戏的初始化是实现游戏计费的必须操作。在游戏启动之后计费之前，务必调用如下方法，否则无法使
13、用计费功能。该接口提供2个重载方法，如果合作伙伴希望自定义计费界面的游戏名称，游戏提供商及客服信息（SDK默认采用平台上申报业务时填写的客服），可以调用重载接口2实现。接口定义void GameInterface.initializeApp(Activity main);void GameInterface.initializeApp(Activity main, String gameName, String provider, String serviceTel);参数定义参数名称类型意义注释：actActivity游戏项目的上下文环境该Activity需要在游戏运行期间不能被finish
14、掉，否则计费会出现不可预知问题gameNameString移动计费界面展现的游戏名称传null时，SDK使用平台申报的业务名称providerString移动计费界面展现的游戏提供商名称传null时，SDK使用平台中合作伙伴管理栏目中填写的容提供商名称serviceTelString移动计费界面展现的客服大多数情况，不需要指定该值，SDK会从使用平台上业务申报时指定的客服3.4登录流程及接口3.4.1登录流程该登录流程是移动游戏用户登录移动用户中心体系的过程。 业务流程图：流程描述:1）用户下载安装移动游戏：用户从移动线上渠道或其他渠道下载已商用的游戏2）用户登录：用户安装完成后启动游戏，集成
15、此游戏SDK的游戏会向游戏平台发送登录请求，游戏平台验证当前用户的登录请否合法有效，并进行用户登录。具体：登录的请求由SDK自动发起（即在3.3接口中完成），另外，为便于步骤4中的客户端与服务器数据交互，游戏开发者可根据自身需要调用登录透传参数接口（3.4.2章节）用于记录客户端每次登录的流水号。3）登录结果通知：a）游戏平台把登录结果返回给游戏服务器（服务器通过登录同步URL接口获得）。b）游戏平台把登录结果返回给游戏客户端（客户端通过登录结果监听接口获得，详见：3.4.3章节）4）游戏客户端同游戏服务器交互： 此步骤由游戏开发者自选是否需要执行。如果游戏希望从移动游戏平台获得更多的用户数据
16、，则可以通过该步骤从自身游戏服务器提取。客户端与服务器的每次登录凭证或流水号可以通过设置登录透传参数接口（3.4.4章节）完成。3.4.2客户端登录透传参数设置接口 按照3.4.1登录流程：在步骤2，SDK发起登录流程后，如果需要在登录完成后，客户端与游戏服务器进行数据交互，则需要通过该接口设置登录的流水号作为每次登录的唯一凭证。注：该接口需在初始化之前调用接口定义void GameInterface.setExtraArguments(String args);参数定义参数名称类型意义注释：argsString可扩展的自定义业务参数集合，对于网游业务，可以用该接口设置登录透传参数该参数必须1
17、6个字节，请勿包含SDK保留字符，如：“&=”另，其中不能含有空格，同时尽量避免使用特殊字符 调用示例String cpparam = “21270”;GameInterface.setExtraArguments(String cpparam)3.4.3客户端登录结果回调接口按照3.4.1登录流程：在步骤2，SDK发起登录流程后，如果游戏希望通过SDK获得本次登录用户的用户ID，可以通过设置该监听接口完成。此接口仅仅返回移动游戏登录结果中的用户伪码（即移动用户中心用户ID：统称UID）,游戏容可以使用此UID关联玩家身份，也可忽略此UID。接口定义void GameInterface.set
18、LoginListener(Context context, ILoginCallback callback);参数定义参数名称类型意义注释：contextContext触发该接口的应用上下文环境callbackILoginCallback登录结果的回调接口。回调方法：onResult(int resultCode, String userId, Object obj);resultCode：详见下面返回结果定义。userId：即为移动用户UID。obj：扩展额外参数。客户端登录返回码登录结果。在SDK中使用常量类进行定义，即：LoginResultLoginResult.UNKOWN 用户没
19、有发起登录（如网络原因，或者用户取消登录）LoginResult.SUCCESS_IMPLICIT 隐式登录成功。LoginResult.FAILED_IMPLICIT 隐式登录失败。LoginResult.SUCCESS_EXPLICIT 显式登录成功。LoginResult.FAILED_EXPLICIT 显式登录失败。调用示例GameInterface.setLoginListener(this, new ILoginCallback() Override public void onResult(int resultCode, String userId, Object ogj) if
20、 (LoginResult.SUCCESS_EXPLICIT = resultCode) /用户登录成功的游戏业务逻辑代码else if (LoginResult.FAILED_EXPLICIT = resultCode) /用户登录失败的游戏业务逻辑代码 else /用户取消登录的游戏业务逻辑代码 );3.4.4获取登录同步结果按照3.4.1登录流程：合作方可以通过此接口获得游戏平台同步的用户伪码（userId），网游事务ID，合作方ID，计费代码，渠道代码，透传参数，用户归属地，用户终端等额外扩展信息。该接口由游戏平台主动调用游戏服务器提供的URL地址，并通过GET方式透传用户登录结果。故
21、：游戏提供商需要在iGop上申报网游业务时，指定该登录同步URL。接口地址：indexURL?userId=xxx&key=xxx&cpId=xxx&cpServiceId=xxx&channelId=xxx&p=xxx®ion=xxx&Ua=xxx注：indexURL即为是网游合作方在业务申报时在iGop上提交的用户信息同步URL。（IGOP平台游戏信息页中显示截图)提交方式：GET相关参数：参数名称重要性类型长度（字节）描述信息userIdMString10用户伪码keyMString24用户登录网游的事务ID，与返回给客户端的KEY一致。cpIdMString6合作方IDcpSer
22、viceIdMString12计费代码channelIdMString88位渠道代码pOString16透传参数（即2.3.2接口设置的登录透传参数）regionOString30用户归属地信息UaMString用户手机型号（短UA形式），如用户手机型号为MOT-MOTORAZRV8_CMCC/1.0 linuxOS/2.6.10 Release/06.30.2007.Browser/Opera8.50 Profile/MIDP-2.0Configuration/CLDC-1.1software/R601_G_90.44.2BR则平台传递ua为MOT-MOTORAZRV8合作方接口的返回值：合
23、作方游戏服务器，收到游戏平台提供的登录结果同步数据后，应立即给出响应，否则整个登录过程会被阻塞，则游戏平台认为登录失败。返回容为普通文本，容如下：Content-Type: text/plain; charset=UTF8rContent-Length: xxrr03.5更多游戏接口按照中国移动合作方游戏接入规，游戏主菜单需要添加更多游戏入口。点击此按钮，需调用如下接口实现更多游戏逻辑。接口定义void GameInterface.viewMoreGames(Contextcontext);参数定义参数名称类型意义注释：contextContext游戏项目的上下文环境3.6计费流程与接口3.6
24、.1计费流程业务流程业务流程说明1）用户发起购买请求：用户使用移动游戏，出发购买道具流程。按照上面流程图，短信方式购买道具时，用户的付费请求将先送到短信网关进行处理，再送达游戏平台。如果用户当前不具备短信发送条件，例如无卡或者异网用户，则付费方式采用HTTP网络请求方式，直接送达至游戏平台。2）游戏平台处理付费请求：游戏平台收到付费请求后，进行处理，鉴权，验证等逻辑，对于合法的付费请求将允许付费，并向游戏服务器同步付费结果。3） 付费结果提示：无论是短信方式还是HTTP方式发起的付费请求，付费成功后，游戏平台将会把扣费成功的短信下行给用户。4）道具使用： 游戏客户端与自身游戏服务器进行交互，完
25、成道具发放逻辑。处理流程 处理流程描述结合业务流程，可以将一次用户的购买行为，按照接口调用顺序分为：1）用户触发付费，游戏开发者中调用SDK付费接口（3.6.2章节）。2）SDK通过短信（或HTTP）方式上行付费请求，并送至游戏平台。游戏平台处理付费请求，并向游戏服务器发送付费结果通知。3）游戏开发者监听付费结果通知（通知接口见3.6.3），并根据付费结果处理业务使用（道具发放）逻辑。3.6.2计费接口按照上述业务及处理流程，用户触发道具购买时，游戏开发者调用如下接口，完成计费计费请求的发送，通过不同的参数值完成各种计费要求。如果游戏希望在计费结束，比如计费成功、失败或用户取消计费后，处理自定
26、义的逻辑，需实现IPayCallback回调。（特殊说明：对于网游业务，下放道具的处理逻辑，不应根据IPayCallback的回调结果，实际上必须根据游戏平台的付费结果通知。例如：对于短信计费，SDK的IPayCallback给出的付费结果只是短信发送成功，并不是真正的付费成功）。注：如果是权益类道具（由游戏合作方申报计费点时指定为：权益道具，并由产品经理确认，除此之外，都是普通道具），则需要调用重载计费接口，即：第三个参数propsType为PropsType.RIGHTS。此时，billingCallback的onResult结果若为成功，应下放道具给用户。接口定义void GameInt
27、erface.doBilling(Context context, boolean useSms, boolean isRepeated, String billingIndex, String cpParam, IPayCallback billingCallback);void GameInterface.doBilling(Context context, boolean useSms, int propsType, String billingIndex, String cpParam, IPayCallback billingCallback);参数定义参数名称类型意义注释：contextContext触发计费接口的Context对象计费UI修改为dialog展现模式，故需要游戏开发者调用接口时传递当前context参数useSmsboolean选择采用短信方式发起付费，还是HTTP计费方式true：短信计费，false：联网计费。此参数，无特殊要求，均应填true。isRepeatedboolean该计费点是否是非强制计费点（见1.2章节）如果该参数传递true,表示本次计费的计费点是可重复计费的计费点，SDK不自动保存计费
