中国移动游戏基地Android游戏SDK使用说明

游戏基地Android游戏SDK使用说明中国移动游戏基地2013年10月31日文件状态： 草稿 正式发布 正在修改文件标识：当前版本：V2.1.4作者：金怀香完成日期：2013-10-31版本历史版本/状态作者参与者起止日期备注2.1.4金怀香王安福2013-10-31创建支持混合支付目录1引言41.1编写目的41.2术语及缩略词41.3适用对象及范围42SDK概述52.1 总体描述52.1.1概述52.1.2 SDK使用准备52.2游戏初始化接口62.2.1游戏计费信息配置文件62.2.2应用程序加载接口72.2.3游戏初始化接口72.2.4设置登录透传参数接口82.2.5游戏登录结果回调接口82.3 游戏启动画面102.4 游戏退出接口102.5 更多游戏接口112.6游戏计费接口112.6.1计费流程112.6.2 计费接口122.7网游登录同步接口142.8计费同步接口152.9 获取游戏背景音乐开关163 Unity3D引擎游戏的开发163.1 复制资源文件163.2 编辑AndroidManifest.xml文件163.3 为游戏增加Unity3D脚本164常见问题：181 引言1.1 编写目的游戏基地Android游戏SDK使用说明及其SDK，是为了简化合作伙伴对游戏计费等功能的开发流程。1.2 术语及缩略词试玩转激活：游戏在启动后，允许用户试用一段时间或指定关卡后，再触发计费的业务。计费点：游戏在平台申报的激活点信息，包含：计费点名称、价格、及唯一标识代码等信息强制计费点：即一次性付费的计费点，通常也是必须要付费的计费点，否则用户无法继续使用游戏或者进入下一关卡。非强制计费点：即可重复购买的计费点，通常是游戏中道具或金币，用户可以多次购买的计费点。1.3 适用对象及范围适用于策划人员、系统设计人员、开发工程师和测试工程师2 SDK概述2.1 总体描述2.1.1概述中国移动Android游戏SDK开发包提供给任何可信任的第三方合作伙伴，可信任的第三方合作伙伴通过游戏基地提供的开发规范实现用户在Android游戏中的计费等功能。SDK开发包已经包含开发规范所涉及的游戏标准开发要求的实现，包括游戏LOGO制作要求，游戏开始画面，游戏计费交互模块，网络（CMNET/CMWAP/WIFI）检测，以及游戏退出确认画面等等。合作伙伴只需将SDK集成到游戏中，并调用相应的接口函数即可完成对开发规范所涉及的游戏标准要求的实现。2.1.2 SDK使用准备SDK开发包包括以下几个文件与目录：1. SDK开发资源包： SDK目录中包含SDK的资源文件，请复制SDK目录中的所有目录与文件，并拷贝至各自的游戏工程中），如下：1）拷贝APIA）拷贝Native API将SDK/libs目录中的文件全部拷贝到游戏libs下。B）拷贝JAVA API将SDK/runtime目录文件， 直接复制到游戏根目录下， 切勿将runtime下面的jar文件放入libs下面编译，否则会报编译错误，例如：bad range。2）拷贝SDK资源A）将SDK/res文件夹中的内容拷贝至游戏工程目录中。B）将SDK/assets文件夹中的所有文件拷贝至游戏相同的工程目录中，不能删除其中的任何文件， 否则导致非正常运行。3）替换游戏厂商logo或游戏logo将assets/OpeningAnimation目录下的两个图片：g_logo_sp.png，g_logo_cp.png替换成合作伙伴自己的logo；当SP和CP是同一厂商时，即该两个图片一样时，请将其中一个Logo图片换成游戏Logo，避免重复展示。另外：合作伙伴提供的logo大小不超过118x118像素，宽度和高度都不能超过。4）添加SDK提供的Activity引用将SDKAndroidManifest.xml.activity.txt中的文本Copy到游戏的AndroidManifest.xml中Activity的横竖屏配置（android:screenOrientation），最好设置成游戏主界面的横竖屏设置。 5）添加SDK需要的use-permision将SDKAndroidManifest.xml.permision.txt中的文本Copy到游戏的AndroidManifest.xml注意：不要重复添加use-permision项。6）为游戏主入口添加中国移动游戏基地标识（Intent-Filter）为游戏主入口Activity添加中国移动游戏基地标识，如下：2. 示例工程（Sample目录中为游戏计费实现的实例，详细的Sample程序源文件在Sample/GameDemo/文件夹下），请不要直接拷贝Sample的示例代码，根据游戏时间情况，处理接口调用逻辑。3. 开发文档（游戏基地Android游戏开发SDK使用说明.doc）2.2游戏初始化接口2.2.1游戏计费信息配置文件在APK包的assets目录下包含登录及计费相关数据文件，文件内容均已加密。SDK提供了测试使用的Charge.xml、ConsumeCodeInfo.xml。游戏开发者需要确认这两个文件已在游戏的assets目录下存在，否则编译不通过。待游戏提交至移动平台后，动态替换该文件内容（替换成游戏实际业务及计费信息）。注意：该两个文件是计费的核心数据，请勿擅自修改其内容，否则计费失败。另：请将SDKassetsConfig.xml也一并复制到游戏assets目录，该文件与计费无关，是SDK的版本标识，但是必须包含。针对客户端网游业务，游戏开发者在集成SDK过程中，无法直接测试真实的登录与购买道具流程；因为SDK提供的Charge.xml及ConsumeCodeInfo.xml信息是测试数据。若要完成登录及购买道具测试，请CP将集成SDK的游戏提交至游戏管理平台，并点击同步自测，可以从平台上下载含真实业务信息的包体内容，并用指定的测试号码（同步自测时给出的号码）完成登录及购买道具测试。2.2.2应用程序加载接口游戏开发者在集成SDK，务必先自定义全局Application。Application里面代码必须包含：System.loadLibrary(megjb);示例代码如下:public class CmgameApplication extends Application public void onCreate() System.loadLibrary(megjb); AndroidManifest.xml中配置：2.2.3游戏初始化接口游戏的初始化是实现游戏计费的必须操作。在游戏启动之后计费之前，务必调用如下方法，否则无法使用计费功能。1 GameInterface.initializeApp(Activity main);如果合作伙伴希望自定义计费界面的游戏名称，游戏提供商及客服电话信息（SDK默认采用平台上申报业务时填写的客服电话），可以调用重载接口2实现：2 GameInterface.initializeApp(Activity main, String gameName, String provider, String serviceTel);注：初始化接口中将完成用户登录流程，如果合作方需要用户登录信息可在初始化后到其网游服务器登录同步接口中去获取，详细实现请见2.7章节。参数描述:参数名称类型意义注释：actActivity游戏项目的上下文环境该Activity需要在游戏运行期间不能被finish掉，否则计费会出现不可预知问题gameNameString移动计费界面展现的游戏名称传null时，SDK使用平台申报的业务名称providerString移动计费界面展现的游戏提供商名称传null时，SDK使用平台中合作伙伴管理栏目中填写的内容提供商名称serviceTelString移动计费界面展现的客服电话大多数情况，不需要指定该值，SDK会从使用平台上业务申报时指定的客服电话调用示例:GameInterface.initializeApp(this);2.2.4设置登录透传参数接口描述：由于SDK会自动完成登录流程，登录成功后，移动平台系统将会登录结果同步到游戏服务器，则游戏开发者需要根据此参数，取得登录开始与结束的唯一对应关系。该参数的使用方式，需要结合2.7章节，才有意义。接口定义：GameInterface.setExtraArguments(String args);参数描述:参数名称类型意义注释：argsString可扩展的自定义业务参数集合，对于网游业务，可以用该接口设置登录透传参数 调用示例：String cpparam = “20131031101034z”;GameInterface.setExtraArguments(new Stringcpparam)2.2.5游戏登录结果回调接口SDK会在2.2.3章节初始化接口中实现登录流程，并通过该接口告知游戏开发者登录结果。游戏开发者根据该接口的回调结果向自有游戏服务器获取登录结果的用户信息，并完成自身业务处理逻辑。通常的业务处理场景：游戏开发者在收到该接口的成功回调结果后，需要自行发起客户端与游戏服务器的交互，从自有游戏服务器获取登录用户信息。游戏自有服务器地址的配置及开发规范见2.7章节。接口定义：GameInterface. setLoginListener (Context context, ILoginCallback callback);参数描述:参数名称类型意义注释：contextContext触发该接口的应用上下文环境callbackILoginCallback登录结果的回调接口。回调方法：onResult(int resultCode, String userId, Object ogj);resultCode：登录结果。枚举定义：LoginResult.UNKOWN 没有登录LoginResult. SUCCESS_IMPLICIT 隐式登录成功LoginResult. FAILED_IMPLICIT 隐式登录失败。LoginResult. SUCCESS_EXPLICIT 显式登录成功LoginResult. FAILED_EXPLICIT 显式登录失败。userId：用户伪码：当前登录的用户伪码。调用示例:GameInterface.setLoginListener(BillingDemo.this, new ILoginCallback() Overridepublic void onResult(int resultCode, String userId, Object ogj) if (LoginResult.SUCCESS_EXPLICIT = resultCode | LoginResult.SUCCESS_IMPLICIT = resultCode) System.out.println(Login success);else if (LoginResult.FAILED_EXPLICIT = resultCode | LoginResult.FAILED_IMPLICIT = resultCode) System.out.println(Login fail);else System.out.println(Login unkown););2.3 游戏启动画面在AndroidManifest.xml中的主入口Activity配置为GameOpenActivity（即SDK提供的游戏启动画面的Activity）。游戏原来的主入口Activity请添加到res/values/g_strings.xml中的g_class_name字符串中，使得启动画面完成后即启动游戏例如：your.game.ui.Entry另外：该方式可以通过接口GameInterface.isMusicEnabled()来判断用户是否选择开启背景音效，接口详细定义见（2.9章节）如果游戏使用的API Level是小于等于3的情况，即：游戏是基于Android 1.5开发的，那么还需要设置一个低版本标识，(API 小于4的情况，Android本身不支持图片自适配，故可能导致SDK中的界面元素被放大，UI效果差)true，这样SDK会读取该标识，并完成开机界面的自适配。2.4 游戏退出接口游戏退出时，需调用该接口完成退出逻辑，该接口是与2.2.2章节成对出现，前者用户初始化SDK实例，后者用于释放SDK占用的资源及内存，并实现退出确认界面。调用接口：GameInterface.exit(Context context, GameExitCallback callback);参数描述:参数名称类型意义注释：contextContext触发该接口的应用上下文环境callbackGameExitCallback用户在退出界面回调处理接口。开发者需要实现其中的接口方法：onConfirmExit()。和onCancelExit()。onConfirmExit()表示用户确认退出操作的接口方法，这里面通常是资源释放代码。onCancelExit()表示用户取消退出，此时需要回到原游戏界面。调用示例：（具体可以参考Demo示例的BillingDemo.java）GameInterface.exit(BillingDemo.this, new GameExitCallback() Overridepublic void onConfirmExit() /确认退出逻辑Overridepublic void onCancelExit() /取消退出逻辑);2.5 更多游戏接口点击游戏主菜单界面的更多游戏按钮，调用下面接口：GameInterface.viewMoreGames(Contextcontext);参数描述:参数名称类型意义注释：contextContext游戏项目的上下文环境2.6游戏计费接口2.6.1计费流程网游计费流程：如下流程图。（其中包含网游产品自有游戏服务器交互流程）2.6.2 计费接口通过GameInterface中的doBilling接口，可以直接启动计费Activity进行计费，计费Activity内部已经实现了默认的处理方法，合作伙伴只需要监听计费成功或失败的状态即可。合作伙伴调用如下接口，完成计费流程，通过不同的参数值完成各种计费要求。如果游戏希望在计费结束，比如计费成功、失败或用户取消计费后，处理自定义的逻辑，请实现IPayCallback回调，其他情况可直接传null值。如果游戏中某个计费点需要重复计费，请将isRepeated参数传true值。网游游戏需传此参数，计费成功后将其同步至其网游服务器，可作为此次计费的流水号。GameInterface.doBilling(Context context, Boolean useSms, Boolean isRepeated, String billingIndex, String cpParam, IPayCallback billingCallback);参数描述：参数名称类型意义注释：contextContext触发计费接口的Context对象计费UI修改为dialog展现模式，故需要游戏开发者调用接口时传递当前context参数useSmsBoolean选择采用短信计费还是联网计费方式true：短信计费，false：联网计费isRepeatedBoolean该计费点是否是非强制计费点如果该参数传递true,表示本次计费的计费点是可重复计费的计费点，SDK不自动保存计费标志位；传递false则为一次性计费的计费点，SDK将自动保存计费标志位，用户下一次玩到该计费点时，不会重复跳出计费界面。billingIndexString计费点索引游戏中设置的计费点索引，对应于中国移动游戏基地游戏平台该游戏内容下“激活点信息”中的“激活点计费代码”的后三位(见图示如下)。该计费点计费代码的后三位为“000”则billingIndex设置为“000”，若该计费点计费代码的后三位为“001”则billingIndex设置为“001”，以此类推。cpParamStringcpParamcpParam透传参数，此参数由合作方规则（16byte）,在计费完成后游戏平台会将计费结果及此参数一并同步到网游服务器计费结果地址上去，可作为此次付费流水号。billingCallbackIPayCallback计费结果的回调逻辑BillingResult.SUCCESS:计费成功的回调处理，BillingResult.FAILED：计费失败后的回调处理，BillingResult.CANCELLED：用户不进行计费的回调处理，中国移动游戏基地游戏平台游戏内容下“激活点信息”中的“激活点计费代码”的后三位示例，计费点“激活游戏”的代码后三位为“001”，计费点“超级弹簧”的代码后三位为“004”。代码调用示例：对计费代码后三位为”001”的计费点(非重复计费的计费点)进行付费IPayCallback billingCallback = new IPayCallback() Overridepublic void onResult(int resultCode, String billingIndex, Object arg) System.out.println(“Billing result of items“+billingIndex+” is: ” + resultCode);GameInterface.doBilling(this, true, false, “000”, “2013101610121270”, billingCallback);特别说明：计费接口要在游戏的主线程里调用2.7网游登录同步接口合作方通过此接口获得游戏业务平台同步的用户信息。接口地址：http:/indexURL?userId=xxx&key=xxx&channelId=xxxx®ion=xxx&cpparam=xxx其中：indexURL是网游合作方在业务申报时提交的网游服务器用户信息同步接口。接口相关参数：同步接口表参数名称重要性类型长度（字节）描述信息userIdMString10用户伪码keyMString24用户登录网游的事务ID，与返回给客户端的KEY一致。channelIdMString88位渠道代码regionOString30用户归属地信息cpparamOString16透传参数合作方接口的返回值：返回内容为普通文本，内容如下：Content-Type: text/plain; charset=UTF8rContent-Length: xxrr02.8计费同步接口此接口地址由合作方提供。在游戏申报时，合作方需要提供该款网游接收用户购买道具通知的接口，并在游戏上线过程中确保同步服务器的正常，以免影响用户计费。http:/:?userId=XXXX&contentId=XXXXX&consumerCode=XXXX&cpId&hRet=XXXX&versionId=XXXX&cpparam=XXXX&packageID=XXXX游戏业务平台以XML报文的方式把数据POST给上面的URL，合作方返回的内容也是XML形式。输入参数输入参数表标识符重要性类型长度（字节）描述userIdMString10用户伪码contentIdMString12计费代码consumeCodeMString12道具计费代码cpIdMString6合作代码hRetMString4平台计费结果（状态码外码）0-成功 其他-失败versionIdMString6版本号2_0_0, 统一填写2_0_0cpparamOString16CP透传参数packageIDOString12套餐包ID(非局数据ID)110072400263071600018500600037200171030711906210071382973893726XYZ2.9 获取游戏背景音乐开关游戏启动的第一个界面(2.3章节)，即：用户选择是否开启音效界面，用户选择是，则游戏需要实现有背景音乐的逻辑，否则反之，游戏开发者可根据此接口判断用户是否选择了开启音效：GameInterface.isMusicEnabled()注：该接口用于2.3章节中的第一种启动方式。3 Unity3D引擎游戏的开发3.1 复制资源文件l 将SDKassets目录中的文件复制到AssetsPluginsAndroidassets下。l 将SDKres下面的文件复制到AssetsPluginsAndroidres下。l 将SDKruntime下面的文件复制到AssetsPluginsAndroidruntime下。l 请将g_strings.xml中的g_class_name配置为游戏真实的入口地址，默认是com.unity3d.player.UnityPlayerActivityl 添加Application定义,详见2.2.2章节，将自定义的application java class 导出一个jar，放入libs目录即可。3.2 编辑AndroidManifest.xml文件编辑AndroidManifest.xml文件，将开机动画设置为游戏入口Activity，对真实的游戏入口进行配置，同时加上必须的权限配置。1）添加SDK提供的Activity引用将SDKAndroidManifest.xml.activity.txt中的文本Copy到游戏的AssetsPluginsAndroidAndroidManifest.xml中2）添加SDK需要的user-permision将SDKAndroidManifest.xml.permision.txt中的文本Copy到游戏的AssetsPluginsAndroidAndroidManifest.xml中（注意重复内容）3.3 为游戏增加Unity3D脚本1 添加SDK提供的C#脚本文件将SDKUnity3DCmBillingAndroid.cs文件Copy到AssetsPluginsAndroid中2 在游戏初启动界面，调用接口CmBillingAndroid.Instance.InitializeApp()参数：无调用该接口完成SDK计费流程需要的信息。该接口需在游戏一启动时调用。调用示例见SDK提供的Demo脚本，CmBillingAndroidDemo。3 在游戏启动后，判断用户是否开启音效接口：CmBillingAndroid.Instance.IsMusicEnabled();返回值：bool类型，标识用户是否选择开启音效游戏开发者需要根据该返回值，设定游戏背景音乐是否开启。调用示例见SDK提供的Demo脚本，CmBillingAndroidDemo。4 在游戏需要弹出计费界面的场景调用计费接口：CmBillingAndroid.Instance.DoBilling(bool useSms, bool isRepeated, String index, String cpParam,String gameObject, String runtimeScriptMethod);参数：useSms：是否采用短信计费模式，true是，false则采用联网计费isRepeated：标识此次计费的计费点，是否是需要重复计费的计费点，是则SDK不保存计费标志，用户可继续对该计费点付费，false，则只能计费一次。index：计费点索引，详细介绍请参考2.4.2章节。cpParam: cpParam透传参数，此参数由合作方规则（16byte）,在计费完成后游戏平台会将计费结果及此参数一并同步到网游服务器计费结果同步地址上去，可作为此次计费的流水号。gameObject：游戏场景中的对象，SDK内部完成计费逻辑后，并把计费结果通过Unity内部API（com.unity3d.player.UnityPlayer.UnitySendMessage(String gameObject,StringruntimeScriptMethod,Stringargs)）通知到Unity，故游戏开发者需要指定一个游戏对象和该对象的运行脚本，用于侦听SDK的计费结果。runtimeScriptMethod：隶属于gameObject对象的运行时脚本的方法名称，该方法会在收到通知后触发。调用示例见SDK提供的Demo脚本，CmBillingAndroidDemo。5 获取计费结果接口：监听SDK付费结果：通过监听SDK的付费请求，获取计费结果，如接口4中定义的gameObject和runtimeScriptMethod参数，