和游戏网游SDK开发文档.docx
- 文档编号:24643692
- 上传时间:2023-05-29
- 格式:DOCX
- 页数:35
- 大小:233.98KB
和游戏网游SDK开发文档.docx
《和游戏网游SDK开发文档.docx》由会员分享,可在线阅读,更多相关《和游戏网游SDK开发文档.docx(35页珍藏版)》请在冰豆网上搜索。
和游戏网游SDK开发文档
和游戏网游SDK
开发文档
(Android版)
2014年9月18日
文件状态:
[]草稿
[]正式发布
[√]正在修改
文件标识:
当前版本:
V2.2.1
完成日期:
2014-9-18
TableofContents
1引言
1.1介绍
本文档的目的是为中国移动游戏业务合作方开发Android网游提供说明指导,对Android网游SDK的集成方式和步骤进行描述,介绍了游戏业务平台与合作方游戏间的技术开发接口规,以便于游戏开发商开发游戏业务。
本文档主要包括以下几方面容:
中国移动游戏基地安卓网游业务总体概述、Android网游系统结构及流程说明、Android网游SDK集成步骤、Android网游SDK接口说明、合作方游戏服务器接口说明、Unity3D引擎游戏适配、常见问题等。
本文档适用于中国移动游戏基地安卓网游SDK集成开发者。
本文档参考了以下规文档最新版本:
序号
标准编号
标准名称
发布单位
[1]
QB-D-XXX-XXXX
中国移动游戏业务设备规
中国移动通信集团公司
[2]
QB-D-XXX-XXXX
中国移动游戏业务接口规
中国移动通信集团公司
[3]
QB-D-XXX-XXXX
中国移动游戏业务总体技术要求
中国移动通信集团公司
[4]
QB-D-XXX-XXXX
游戏业务平台合作方开发规
中国移动通信集团公司
[5]
QB-E-XXX-XXXX
中国移动游戏大厅客户端规
中国移动通信集团公司
1.2术语及缩略词
词语
解释
CP
ContentProvider,容提供商
HTTP
HyperTextTransferProtocol,超文本传输协议
ICON
游戏业务的展示图标
LOGO
游戏业务容提供商、服务提供商的商标
OTA
OverTheAir,空中无线下载技术
SP
ServiceProvider,服务提供商
SDK
SoftwareDevelopmentKit的缩写,中文即“软件开发工具包”。
广义上指辅助开发某一类软件的相关文档、例和工具的集合。
XML
ExtensibleMarkupLanguage,可扩展标记语言
UAProfile
由开放移动联盟提出,描述用户终端的配置信息
URL
UniversalResourceLocator,统一资源定位符
点数
游戏业务平台中进行各种交易的通用货币
计费点
游戏在平台申报的激活点信息,包含:
计费点名称、价格、及唯一标识代码等信息
强制计费点
即一次性付费的计费点,通常也是必须要付费的计费点,否则用户无法继续使用游戏或者进入下一关卡。
非强制计费点
即可重复购买的计费点,通常是游戏中道具或金币,用户可以多次购买的计费点。
iGop
游戏业务管理平台,完成CP资质评审,游戏业务评审,测试及商用。
游戏平台
游戏业务通过使用移动游戏SDK与之交互的核心支付平台。
游戏服务器
合作方按照移动游戏规自行实现的游戏服务器,用于完成同移动游戏平台进行数据交互与通信的服务器。
2总体概述
2.1总体流程
●总体流程图
●总体流程说明
合作方开发者需根据此总流程图集成使用移动游戏SDK。
Ø必选流程:
1、游戏应用配置
集成SDK必须先配置游戏运行的必选配置(自定义Application)。
此版本SDK需要游戏自定义Application类,加载SDK核心接口容。
Application的定义与使用方式详见3.1章节。
2、游戏启动画面
集成移动SDK启动画面(按照移动游戏规,游戏的首个启动画面必须包含移动游戏LOGO),启动画面展现移动LOGO。
启动画面的具体集成方式详见3.2章节。
启动画面结束后,需要通过3.2.2接口获得用户是否开启游戏背景音乐的选项。
开发者根据此接口返回值设置游戏背景音乐。
3、游戏初始化
启动画面结束后,进入游戏容,合作方开发者需要对SDK进行初始化,即调用3.3章节,调用此接口的同同时,SDK会进行用户登录。
该接口部会进行用户登录,登录流程及接口详见3.4章节。
4、游戏付费
用户进入游戏商店就行购买道具时,进入游戏付费流程。
付费流程及接口详见3.6章节。
5、游戏退出
用户游戏结束后,选择退出游戏,合作方开发者需要调用退出接口(3.7章节)完成游戏退出逻辑。
Ø可选流程:
按照移动游戏接入规,需要合作方在游戏主菜单添加关于、更多游戏等功能菜单。
更多游戏详见3.5章节。
2.2集成步骤
●SDK开发资源包:
SDK目录中包含SDK的资源文件,请复制SDK目录中的所有目录与文件,并拷贝至各自的游戏工程中),如下:
1)拷贝API
A)拷贝NativeAPI
将SDK/libs目录中的文件全部拷贝到游戏libs下。
B)拷贝JAVAAPI
将SDK/runtime目录文件,直接复制到游戏根目录下,切勿将runtime下面的jar文件放入libs下面编译,否则会报编译错误,例如:
badrange…(不同编译环境均需要按照此要求引用此jar,如遇编译问题,请参考章节4)。
2)拷贝SDK资源
A)将SDK/res文件夹中的容拷贝至游戏工程目录中。
B)将SDK/assets文件夹中的所有文件拷贝至游戏相同的工程目录中,不能删除其中的任何文件,否则导致非正常运行。
3)添加SDK提供的Activity引用
将SDK\AndroidManifest.xml.activity.txt中的文本Copy到游戏的AndroidManifest.xml中。
Activity的横竖屏配置(android:
screenOrientation),最好设置成游戏主界面的横竖屏设置。
4)添加SDK需要的use-permision
将SDK\AndroidManifest.xml.permision.txt中的文本Copy到游戏的AndroidManifest.xml
注意:
不要重复添加use-permision项。
5)为游戏主入口添加中国移动游戏基地标识(Intent-Filter)
为游戏主入口Activity添加中国移动游戏基地标识,如下:
name="android.intent.action.MAIN"/> name="android.intent.category.LAUNCHER"/> name="android.intent.action.CHINAMOBILE_OMS_GAME"/> name="android.intent.category.CHINAMOBILE_GAMES"/> 注意: 如果游戏的主入口Activity没有添加移动游戏标识,则测试会不通过。 ●示例工程: (Sample目录中为游戏计费实现的实例,详细的Sample程序源文件在Sample/GameSample/文件夹下),请不要直接拷贝Sample的示例代码,根据游戏时间情况,处理接口调用逻辑。 3详细接口 3.1应用程序加载接口 游戏开发者在集成SDK,务必先自定义全局Application。 Application里面代码必须包含,下行代码(注意: 该接口必须放在Application中进行加载,不可放在Activity的onCreate中): System.loadLibrary("megjb"); 示例代码如下: (注意: 该类的package路径应用必须与AndroidManifest.xml中的一致,如下代码示例中,黄色标注,否则游戏无常启动)。 package.cmgame.sdk; publicclassCmgameApplicationextendsApplication{ publicvoidonCreate(){ try{ System.loadLibrary("megjb"); }catch(Exceptione){…} } } AndroidManifest.xml中配置: xmlversion="1.0"encoding="utf-8"? > android="schemas.android./apk/res/android" package="cn.cmgame.sdk" android: versionCode="2"android: versionName="1.2"> icon="drawable/icon" android: label="string/app_name"android: name=".CmgameApplication"> …… 3.2游戏启动接口 3.2.1游戏启动画面配置 按照中国移动合作方游戏接入规,需要在游戏的首个启动页面展现移动游戏相关LOGO,此规要求SDK已经自带完成,游戏开发者只需要按照特定集成方式使用即可。 具体使用方法: 在AndroidManifest.xml中的主入口Activity配置为GameOpenActivity(即SDK提供的游戏启动画面的Activity)。 游戏原来的主入口Activity请添加到res/values/g_strings.xml中的g_class_name字符串中,使得启动画面完成后即启动游戏。 例如: 特殊说明: 如果游戏使用的APILevel是小于等于3的情况,即: 游戏是基于Android1.5及以下API版本开发的,那么还需要设置一个低版本标识,(API小于4的情况,Android本身不支持图片自适配,故可能导致SDK中的界面元素被放大,UI效果差)。 3.2.2游戏音效接口 游戏启动的第一个界面(3.2.1章节),即: 用户选择是否开启音效界面,用户选择《是》,则游戏需要实现有背景音乐的逻辑,否则反之,游戏开发者可根据此接口判断用户是否选择了开启音效: ●接口定义 booleanGameInterface.isMusicEnabled() ●返回值 返回false,则游戏中应关闭音效,否则开启。 3.3游戏初始化接口 游戏的初始化是实现游戏计费的必须操作。 在游戏启动之后计费之前,务必调用如下方法,否则无法使用计费功能。 该接口提供2个重载方法,如果合作伙伴希望自定义计费界面的游戏名称,游戏提供商及客服信息(SDK默认采用平台上申报业务时填写的客服),可以调用重载接口2实现。 ●接口定义 voidGameInterface.initializeApp(Activitymain); voidGameInterface.initializeApp(Activitymain,StringgameName,Stringprovider,StringserviceTel); ●参数定义 参数名称 类型 意义 注释: act Activity 游戏项目的上下文环境 该Activity需要在游戏运行期间不能被finish掉,否则计费会出现不可预知问题 gameName String 移动计费界面展现的游戏名称 传null时,SDK使用平台申报的业务名称 provider String 移动计费界面展现的游戏提供商名称 传null时,SDK使用平台中合作伙伴管理栏目中填写的容提供商名称 serviceTel String 移动计费界面展现的客服 大多数情况,不需要指定该值,SDK会从使用平台上业务申报时指定的客服 3.4登录流程及接口 3.4.1登录流程 该登录流程是移动游戏用户登录移动用户中心体系的过程。 业务流程图: 流程描述: 1)用户下载安装移动游戏: 用户从移动线上渠道或其他渠道下载已商用的游戏 2)用户登录: 用户安装完成后启动游戏,集成此游戏SDK的游戏会向游戏平台发送登录请求,游戏平台验证当前用户的登录请否合法有效,并进行用户登录。 具体: 登录的请求由SDK自动发起(即在3.3接口中完成),另外,为便于步骤4中的客户端与服务器数据交互,游戏开发者可根据自身需要调用登录透传参数接口(3.4.2章节)用于记录客户端每次登录的流水号。 3)登录结果通知: a)游戏平台把登录结果返回给游戏服务器(服务器通过登录同步URL接口获得)。 b)游戏平台把登录结果返回给游戏客户端(客户端通过登录结果监听接口获得,详见: 3.4.3章节) 4)游戏客户端同游戏服务器交互: 此步骤由游戏开发者自选是否需要执行。 如果游戏希望从移动游戏平台获得更多的用户数据,则可以通过该步骤从自身游戏服务器提取。 客户端与服务器的每次登录凭证或流水号可以通过设置登录透传参数接口(3.4.4章节)完成。 3.4.2客户端登录透传参数设置接口 按照3.4.1登录流程: 在步骤2,SDK发起登录流程后,如果需要在登录完成后,客户端与游戏服务器进行数据交互,则需要通过该接口设置登录的流水号作为每次登录的唯一凭证。 注: 该接口需在初始化之前调用 ●接口定义 voidGameInterface.setExtraArguments(String[]args); ●参数定义 参数名称 类型 意义 注释: args String[] 可扩展的自定义业务参数集合,对于网游业务,可以用该接口设置登录透传参数 该参数必须16个字节,请勿包含SDK保留字符,如: “&=·”另,其中不能含有空格,同时尽量避免使用特殊字符 ●调用示例 Stringcpparam=“21270”; GameInterface.setExtraArguments(String[]{cpparam}) 3.4.3客户端登录结果回调接口 按照3.4.1登录流程: 在步骤2,SDK发起登录流程后,如果游戏希望通过SDK获得本次登录用户的用户ID,可以通过设置该监听接口完成。 此接口仅仅返回移动游戏登录结果中的用户伪码(即移动用户中心用户ID: 统称UID),游戏容可以使用此UID关联玩家身份,也可忽略此UID。 ●接口定义 voidGameInterface.setLoginListener(Contextcontext,ILoginCallbackcallback); ●参数定义 参数名称 类型 意义 注释: context Context 触发该接口的应用上下文环境 callback ILoginCallback 登录结果的回调接口。 回调方法: onResult(intresultCode,StringuserId,Objectobj); resultCode: 详见下面返回结果定义。 userId: 即为移动用户UID。 obj: 扩展额外参数。 ●客户端登录返回码 登录结果。 在SDK中使用常量类进行定义,即: LoginResult LoginResult.UNKOWN用户没有发起登录(如网络原因,或者用户取消登录) LoginResult.SUCCESS_IMPLICIT隐式登录成功。 LoginResult.FAILED_IMPLICIT隐式登录失败。 LoginResult.SUCCESS_EXPLICIT显式登录成功。 LoginResult.FAILED_EXPLICIT显式登录失败。 ●调用示例 GameInterface.setLoginListener(this,newILoginCallback(){ Override publicvoidonResult(intresultCode,StringuserId,Objectogj){ if(LoginResult.SUCCESS_EXPLICIT==resultCode){ //用户登录成功的游戏业务逻辑代码 …… }elseif(LoginResult.FAILED_EXPLICIT==resultCode){ //用户登录失败的游戏业务逻辑代码 …… }else{ //用户取消登录的游戏业务逻辑代码 …… } } }); 3.4.4获取登录同步结果 按照3.4.1登录流程: 合作方可以通过此接口获得游戏平台同步的用户伪码(userId),网游事务ID,合作方ID,计费代码,渠道代码,透传参数,用户归属地,用户终端等额外扩展信息。 该接口由游戏平台主动调用游戏服务器提供的URL地址,并通过GET方式透传用户登录结果。 故: 游戏提供商需要在iGop上申报网游业务时,指定该登录同步URL。 ●接口地址: indexURL? userId=xxx&key=xxx&cpId=xxx&cpServiceId=xxx&channelId=xxx&p=xxx®ion=xxx&Ua=xxx 注: indexURL即为是网游合作方在业务申报时在iGop上提交的用户信息同步URL。 (IGOP平台游戏信息页中显示截图) ●提交方式: GET ●相关参数: 参数名称 重要性 类型 长度(字节) 描述信息 userId M String 10 用户伪码 key M String 24 用户登录网游的事务ID,与返回给客户端的KEY一致。 cpId M String 6 合作方ID cpServiceId M String 12 计费代码 channelId M String 8 8位渠道代码 p O String 16 透传参数(即2.3.2接口设置的登录透传参数) region O String 30 用户归属地信息 Ua M String 用户手机型号(短UA形式),如用户手机型号为MOT-MOTORAZRV8_CMCC/1.0linuxOS/2.6.10Release/06.30.2007.Browser/Opera8.50Profile/MIDP-2.0Configuration/CLDC-1.1software/R601_G_90.44.2BR则平台传递ua为MOT-MOTORAZRV8 ●合作方接口的返回值: 合作方游戏服务器,收到游戏平台提供的登录结果同步数据后,应立即给出响应,否则整个登录过程会被阻塞,则游戏平台认为登录失败。 返回容为普通文本,容如下: Content-Type: text/plain;charset=UTF8\r Content-Length: xx\r \r 0 3.5更多游戏接口 按照中国移动合作方游戏接入规,游戏主菜单需要添加《更多游戏》入口。 点击此按钮,需调用如下接口实现更多游戏逻辑。 ●接口定义 voidGameInterface.viewMoreGames(Contextcontext); ●参数定义 参数名称 类型 意义 注释: context Context 游戏项目的上下文环境 3.6计费流程与接口 3.6.1计费流程 ●业务流程 ●业务流程说明 1)用户发起购买请求: 用户使用移动游戏,出发购买道具流程。 按照上面流程图,短信方式购买道具时,用户的付费请求将先送到短信网关进行处理,再送达游戏平台。 如果用户当前不具备短信发送条件,例如无卡或者异网用户,则付费方式采用HTTP网络请求方式,直接送达至游戏平台。 2)游戏平台处理付费请求: 游戏平台收到付费请求后,进行处理,鉴权,验证等逻辑,对于合法的付费请求将允许付费,并向游戏服务器同步付费结果。 3)付费结果提示: 无论是短信方式还是HTTP方式发起的付费请求,付费成功后,游戏平台将会把扣费成功的短信下行给用户。 4)道具使用: 游戏客户端与自身游戏服务器进行交互,完成道具发放逻辑。 ●处理流程 ●处理流程描述 结合业务流程,可以将一次用户的购买行为,按照接口调用顺序分为: 1)用户触发付费,游戏开发者中调用SDK付费接口(3.6.2章节)。 2)SDK通过短信(或HTTP)方式上行付费请求,并送至游戏平台。 游戏平台处理付费请求,并向游戏服务器发送付费结果通知。 3)游戏开发者监听付费结果通知(通知接口见3.6.3),并根据付费结果处理业务使用(道具发放)逻辑。 3.6.2计费接口 按照上述业务及处理流程,用户触发道具购买时,游戏开发者调用如下接口,完成计费计费请求的发送,通过不同的参数值完成各种计费要求。 如果游戏希望在计费结束,比如计费成功、失败或用户取消计费后,处理自定义的逻辑,需实现IPayCallback回调。 (特殊说明: 对于网游业务,下放道具的处理逻辑,不应根据IPayCallback的回调结果,实际上必须根据游戏平台的付费结果通知。 例如: 对于短信计费,SDK的IPayCallback给出的付费结果只是短信发送成功,并不是真正的付费成功)。 注: 如果是权益类道具(由游戏合作方申报计费点时指定为: 权益道具,并由产品经理确认,除此之外,都是普通道具),则需要调用重载计费接口,即: 第三个参数propsType为PropsType.RIGHTS。 此时,billingCallback的onResult结果若为成功,应下放道具给用户。 ●接口定义 voidGameInterface.doBilling(Contextcontext,booleanuseSms,booleanisRepeated,StringbillingIndex,StringcpParam,IPayCallbackbillingCallback); voidGameInterface.doBilling(Contextcontext,booleanuseSms,intpropsType,StringbillingIndex,StringcpParam,IPayCallbackbillingCallback); ●参数定义 参数名称 类型 意义 注释: context Context 触发计费接口的Context对象 计费UI修改为dialog展现模式,故需要游戏开发者调用接口时传递当前context参数 useSms boolean 选择采用短信方式发起付费,还是HTTP计费方式 true: 短信计费,false: 联网计费。 此参数,无特殊要求,均应填true。 isRepeated boolean 该计费点是否是非强制计费点(见1.2章节) 如果该参数传递true,表示本次计费的计费点是可重复计费的计费点,SDK不自动保存计费
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 游戏 网游 SDK 开发 文档