中国移动游戏基地Android游戏SDK使用说明Word文件下载.docx
《中国移动游戏基地Android游戏SDK使用说明Word文件下载.docx》由会员分享,可在线阅读,更多相关《中国移动游戏基地Android游戏SDK使用说明Word文件下载.docx(20页珍藏版)》请在冰豆网上搜索。
2.3游戏启动画面10
2.4游戏退出接口10
2.5更多游戏接口11
2.6游戏计费接口11
2.6.1计费流程11
2.6.2计费接口12
2.7网游登录同步接口14
2.8计费同步接口15
2.9获取游戏背景音乐开关16
3Unity3D引擎游戏的开发16
3.1复制资源文件16
3.2编辑AndroidManifest.xml文件16
3.3为游戏增加Unity3D脚本16
4常见问题:
18
1引言
1.1编写目的
游戏基地Android游戏SDK使用说明及其SDK,是为了简化合作伙伴对游戏计费等功能的开发流程。
1.2术语及缩略词
试玩转激活:
游戏在启动后,允许用户试用一段时间或指定关卡后,再触发计费的业务。
计费点:
游戏在平台申报的激活点信息,包含:
计费点名称、价格、及唯一标识代码等信息
强制计费点:
即一次性付费的计费点,通常也是必须要付费的计费点,否则用户无法继续使用游戏或者进入下一关卡。
非强制计费点:
即可重复购买的计费点,通常是游戏中道具或金币,用户可以多次购买的计费点。
1.3适用对象及范围
适用于策划人员、系统设计人员、开发工程师和测试工程师
2SDK概述
2.1总体描述
2.1.1概述
中国移动Android游戏SDK开发包提供给任何可信任的第三方合作伙伴,可信任的第三方合作伙伴通过游戏基地提供的开发规范实现用户在Android游戏中的计费等功能。
SDK开发包已经包含开发规范所涉及的游戏标准开发要求的实现,包括游戏LOGO制作要求,游戏开始画面,游戏计费交互模块,网络(CMNET/CMWAP/WIFI)检测,以及游戏退出确认画面等等。
合作伙伴只需将SDK集成到游戏中,并调用相应的接口函数即可完成对开发规范所涉及的游戏标准要求的实现。
2.1.2SDK使用准备
SDK开发包包括以下几个文件与目录:
1.SDK开发资源包:
SDK目录中包含SDK的资源文件,请复制SDK目录中的所有目录与文件,并拷贝至各自的游戏工程中),如下:
1)拷贝API
A)拷贝NativeAPI
将SDK/libs目录中的文件全部拷贝到游戏libs下。
B)拷贝JAVAAPI
将SDK/runtime目录文件,直接复制到游戏根目录下,切勿将runtime下面的jar文件放入libs下面编译,否则会报编译错误,例如:
badrange…。
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引用
将SDK\AndroidManifest.xml.activity.txt中的文本Copy到游戏的AndroidManifest.xml中
Activity的横竖屏配置(android:
screenOrientation),最好设置成游戏主界面的横竖屏设置。
5)添加SDK需要的use-permision
将SDK\AndroidManifest.xml.permision.txt中的文本Copy到游戏的AndroidManifest.xml
注意:
不要重复添加use-permision项。
6)为游戏主入口添加中国移动游戏基地标识(Intent-Filter)
为游戏主入口Activity添加中国移动游戏基地标识,如下:
<
activityandroid:
name="
.Example"
android:
label="
@string/app_name"
>
intent-filter>
actionandroid:
android.intent.action.MAIN"
/>
categoryandroid:
android.intent.category.LAUNCHER"
/intent-filter>
android.intent.action.CHINAMOBILE_OMS_GAME"
android.intent.category.CHINAMOBILE_GAMES"
2.示例工程(Sample目录中为游戏计费实现的实例,详细的Sample程序源文件在Sample/GameDemo/文件夹下),请不要直接拷贝Sample的示例代码,根据游戏时间情况,处理接口调用逻辑。
3.开发文档(游戏基地Android游戏开发SDK使用说明.doc)
2.2游戏初始化接口
2.2.1游戏计费信息配置文件
在APK包的assets目录下包含登录及计费相关数据文件,文件内容均已加密。
SDK提供了测试使用的Charge.xml、ConsumeCodeInfo.xml。
游戏开发者需要确认这两个文件已在游戏的assets目录下存在,否则编译不通过。
待游戏提交至移动平台后,动态替换该文件内容(替换成游戏实际业务及计费信息)。
注意:
该两个文件是计费的核心数据,请勿擅自修改其内容,否则计费失败。
另:
请将SDK\assets\Config.xml也一并复制到游戏assets目录,该文件与计费无关,是SDK的版本标识,但是必须包含。
针对客户端网游业务,游戏开发者在集成SDK过程中,无法直接测试真实的登录与购买道具流程;
因为SDK提供的Charge.xml及ConsumeCodeInfo.xml信息是测试数据。
若要完成登录及购买道具测试,请CP将集成SDK的游戏提交至游戏管理平台,并点击《同步自测》,可以从平台上下载含真实业务信息的包体内容,并用指定的测试号码(同步自测时给出的号码)完成登录及购买道具测试。
2.2.2应用程序加载接口
游戏开发者在集成SDK,务必先自定义全局Application。
Application里面代码必须包含:
System.loadLibrary("
megjb"
);
示例代码如下:
publicclassCmgameApplicationextendsApplication{
publicvoidonCreate(){
System.loadLibrary("
}
}
AndroidManifest.xml中配置:
applicationandroid:
icon="
@drawable/icon"
.CmgameApplication"
2.2.3游戏初始化接口
游戏的初始化是实现游戏计费的必须操作。
在游戏启动之后计费之前,务必调用如下方法,否则无法使用计费功能。
1GameInterface.initializeApp(Activitymain);
如果合作伙伴希望自定义计费界面的游戏名称,游戏提供商及客服电话信息(SDK默认采用平台上申报业务时填写的客服电话),可以调用重载接口2实现:
2GameInterface.initializeApp(Activitymain,StringgameName,Stringprovider,StringserviceTel);
注:
初始化接口中将完成用户登录流程,如果合作方需要用户登录信息可在初始化后到其网游服务器登录同步接口中去获取,详细实现请见2.7章节。
参数描述:
参数名称
类型
意义
注释:
act
Activity
游戏项目的上下文环境
该Activity需要在游戏运行期间不能被finish掉,否则计费会出现不可预知问题
gameName
String
移动计费界面展现的游戏名称
传null时,SDK使用平台申报的业务名称
provider
移动计费界面展现的游戏提供商名称
传null时,SDK使用平台中合作伙伴管理栏目中填写的内容提供商名称
serviceTel
移动计费界面展现的客服电话
大多数情况,不需要指定该值,SDK会从使用平台上业务申报时指定的客服电话
调用示例:
GameInterface.initializeApp(this);
2.2.4设置登录透传参数接口
描述:
由于SDK会自动完成登录流程,登录成功后,移动平台系统将会登录结果同步到游戏服务器,则游戏开发者需要根据此参数,取得登录开始与结束的唯一对应关系。
该参数的使用方式,需要结合2.7章节,才有意义。
接口定义:
GameInterface.setExtraArguments(String[]args);
参数描述:
args
String[]
可扩展的自定义业务参数集合,对于网游业务,可以用该接口设置登录透传参数
调用示例:
Stringcpparam=“20131031101034z”;
GameInterface.setExtraArguments(newString[]{cpparam})
2.2.5游戏登录结果回调接口
SDK会在2.2.3章节初始化接口中实现登录流程,并通过该接口告知游戏开发者登录结果。
游戏开发者根据该接口的回调结果向自有游戏服务器获取登录结果的用户信息,并完成自身业务处理逻辑。
通常的业务处理场景:
游戏开发者在收到该接口的成功回调结果后,需要自行发起客户端与游戏服务器的交互,从自有游戏服务器获取登录用户信息。
游戏自有服务器地址的配置及开发规范见2.7章节。
接口定义:
GameInterface.setLoginListener(Contextcontext,ILoginCallbackcallback);
context
Context
触发该接口的应用上下文环境
callback
ILoginCallback
登录结果的回调接口。
回调方法:
onResult(intresultCode,StringuserId,Objectogj);
resultCode:
登录结果。
枚举定义:
LoginResult.UNKOWN没有登录
LoginResult.SUCCESS_IMPLICIT隐式登录成功
LoginResult.FAILED_IMPLICIT隐式登录失败。
LoginResult.SUCCESS_EXPLICIT显式登录成功
LoginResult.FAILED_EXPLICIT显式登录失败。
userId:
用户伪码:
当前登录的用户伪码。
GameInterface.setLoginListener(BillingDemo.this,newILoginCallback(){
@Override
publicvoidonResult(intresultCode,StringuserId,Objectogj){
if(LoginResult.SUCCESS_EXPLICIT==resultCode||LoginResult.SUCCESS_IMPLICIT==resultCode){
System.out.println("
Loginsuccess"
}elseif(LoginResult.FAILED_EXPLICIT==resultCode||LoginResult.FAILED_IMPLICIT==resultCode){
Loginfail"
}else{
Loginunkown"
}
});
2.3游戏启动画面
在AndroidManifest.xml中的主入口Activity配置为GameOpenActivity(即SDK提供的游戏启动画面的Activity)。
游戏原来的主入口Activity请添加到res/values/g_strings.xml中的g_class_name字符串中,使得启动画面完成后即启动游戏
例如:
stringname="
g_class_name"
your.game.ui.Entry<
/string>
另外:
该方式可以通过接口GameInterface.isMusicEnabled()来判断用户是否选择开启背景音效,接口详细定义见(2.9章节)
如果游戏使用的APILevel是小于等于3的情况,即:
游戏是基于Android1.5开发的,那么还需要设置一个低版本标识,(API小于4的情况,Android本身不支持图片自适配,故可能导致SDK中的界面元素被放大,UI效果差)
gc_billing_islow_version"
true<
,这样SDK会读取该标识,并完成开机界面的自适配。
2.4游戏退出接口
游戏退出时,需调用该接口完成退出逻辑,该接口是与2.2.2章节成对出现,前者用户初始化SDK实例,后者用于释放SDK占用的资源及内存,并实现退出确认界面。
调用接口:
GameInterface.exit(Contextcontext,GameExitCallbackcallback);
GameExitCallback
用户在退出界面回调处理接口。
开发者需要实现其中的接口方法:
onConfirmExit()。
和onCancelExit()。
onConfirmExit()
表示用户确认退出操作的接口方法,这里面通常是资源释放代码。
onCancelExit()
表示用户取消退出,此时需要回到原游戏界面。
调用示例:
(具体可以参考Demo示例的BillingDemo.java)
GameInterface.exit(BillingDemo.this,newGameExitCallback(){
@Override
publicvoidonConfirmExit(){
//确认退出逻辑
publicvoidonCancelExit(){
//取消退出逻辑
2.5更多游戏接口
点击游戏主菜单界面的《更多游戏》按钮,调用下面接口:
GameInterface.viewMoreGames(Contextcontext);
2.6游戏计费接口
2.6.1计费流程
网游计费流程:
如下流程图。
(其中包含网游产品自有游戏服务器交互流程)
2.6.2计费接口
通过GameInterface中的doBilling接口,可以直接启动计费Activity进行计费,计费Activity内部已经实现了默认的处理方法,合作伙伴只需要监听计费成功或失败的状态即可。
合作伙伴调用如下接口,完成计费流程,通过不同的参数值完成各种计费要求。
如果游戏希望在计费结束,比如计费成功、失败或用户取消计费后,处理自定义的逻辑,
请实现IPayCallback回调,其他情况可直接传null值。
如果游戏中某个计费点需要重复计费,请将isRepeated参数传true值。
网游游戏需传此参数,计费成功后将其同步至其网游服务器,可作为此次计费的流水号。
GameInterface.doBilling(Contextcontext,BooleanuseSms,BooleanisRepeated,StringbillingIndex,StringcpParam,IPayCallbackbillingCallback);
参数描述:
触发计费接口的Context对象
计费UI修改为dialog展现模式,故需要游戏开发者调用接口时传递当前context参数
useSms
Boolean
选择采用短信计费还是联网计费方式
true:
短信计费,false:
联网计费
isRepeated
该计费点是否是非强制计费点
如果该参数传递true,表示本次计费的计费点是可重复计费的计费点,SDK不自动保存计费标志位;
传递false则为一次性计费的计费点,SDK将自动保存计费标志位,用户下一次玩到该计费点时,不会重复跳出计费界面。
billingIndex
计费点索引
游戏中设置的计费点索引,对应于中国移动游戏基地游戏平台该游戏内容下“激活点信息”中的“激活点计费代码”的后三位(见图示如下)。
该计费点计费代码的后三位为“000”则billingIndex设置为“000”,若该计费点计费代码的后三位为“001”则billingIndex设置为“001”,以此类推。
cpParam
cpParam透传参数,此参数由合作方规则(16byte),在计费完成后游戏平台会将计费结果及此参数一并同步到网游服务器计费结果地址上去,可作为此次付费流水号。
billingCallback
IPayCallback
计费结果的回调逻辑
BillingResult.SUCCESS:
计费成功的回调处理,BillingResult.FAILED:
计费失败后的回调处理,BillingResult.CANCELLED:
用户不进行计费的回调处理,
中国移动游戏基地游戏平台游戏内容下“激活点信息”中的“激活点计费代码”的后三位示例,计费点“激活游戏”的代码后三位为“001”,计费点“超级弹簧”的代码后三位为“004”。
代码调用示例:
对计费代码后三位为”001”的计费点(非重复计费的计费点)进行付费
IPayCallbackbillingCallback=newIPayCallback(){
publicvoidonResult(intresultCode,StringbillingIndex,Objectarg){
System.out.println(“Billingresultofitems[“+billingIndex+”]is:
”+resultCode);
};
GameInterface.doBilling(this,true,false,“000”,“2013101610121270”,billingCallback);
特别说明:
计费接口要在游戏的主线程里调用
2.7网游登录同步接口
合作方通过此接口获得游戏业务平台同步的用户信息。
接口地址:
http:
//indexURL?
userId=xxx&
key=xxx&
channelId=xxxx&
region=xxx&
cpparam=xxx
其中:
indexURL是网游合作方在业务申报时提交的网游服务器用户信息同步接口。
接口相关参数:
同步接口表
重要性
长度(字节)
描述信息
userId
M
10
用户伪码
key
24
用户登录网游的事务ID,与返回给客户端的KEY一致。
channelId
8
8位渠道代码
region
O
30
用户归属地信息
cpparam
16
透传参数
合作方接口的返回值:
返回内容为普通文本,内容如下:
Content-Type:
text/plain;
charset=UTF8\r
Content-Length:
xx\r
\r
2.8计费同步接口
此接口地址由合作方提供。
在游戏申报时,合作方需要提供该款网游接收用户购买道具通知的接口,并在游戏上线过程中确保同步服务器的正常,以免影响用户计费。
//<
host>
[:
port>
]<
/script>
?
userId=XXXX&
contentId=XXXXX&
consumerCode=XXXX&
cpId&
hRet=XXXX&
versionId=XXXX&
cpparam=XXXX&
packageID=XXXX
游戏业务平台以XML报文的方式把数据POST给上面的URL,合作方返回的内容也是XML形式。
输入参数
输入参数表
标识符
描述
contentId
12
计费代码
consumeCode
道具计费代码
cpId
6
合作代码
hRet
4
平台计费结果(状态码外码)0-成功其他-失败
versionId
版本号2_0_0,统一填写2_0_0
CP透传参数
packageID
套餐包ID(非局数据ID)
xmlversion="
1.0"
encoding="
UTF-8"
request>