游戏业务平台合作方开发规范

游 戏 业 务 平 台 游 戏 开 发 规 范G a m e D e v e l o p m e n t S p e c i f i c a t i o no f G a m e M a s t e r P l a t f o r m版本号： 1 . 2 . 1 0中国移动通信有限公司发布I目录1. 范围. 12. 修订历史 . 13. 规范性引用文件 . 24. 术语、定义和缩略语 . 25. 业务概述 . 35.1. 业务概念 . 35.2. 业务开放范围 . 35.3. 业务类型 . 35.3.1. 按使用方式分类 . 35.3.2. 按计费方式分类 . 35.3.3. 按用户消费方式分类 . 46. 游戏界面要求: . 46.1. 应用界面设计基本原则 . 46.2. 游戏业务平台相关接口调用的入口说明 . 56.2.1. 游戏点数充值（包括所有单机和网络游戏）： . 56.2.2. 游戏点数消费（仅限网络游戏和需要购买道具的单机游戏，包括短信计费的单机游戏）： . 56.2.3. 游戏点数余额及明细查询： . 56.3. 游戏激活界面设计 . 66.4. 应用界面文字格式要求 . 76.5. 短信计费业务订购页面要求 . 87. 数据类型 . 87.1. 基本类型 . 87.2. 复合类型 . 87.3. 状态码 . 107.4. 系统级错误代码 . 108. 接口要求 . 118.1. 单机游戏(8.1 节特指下载游戏客户端后，用话费或点数消费完整版游戏（一次性激活、终身使用)的接口要求) . 118.1.1. 描述 . 118.2. WAP 单机业务（8.2 特指按次计费的图文游戏） . 138.2.1. 地址解释 . 138.2.2. WAP 单机业务代理 . 138.2.3. 消费WAP 单机业务 . 158.3. 游戏业务包 . 168.3.1. 订购游戏业务包 . 168.4. 手机网游 (8.4 节特指需下载客户端的手机网游的接口要求) . 178.4.1. 登录手机网游 . 178.4.2. 用户充值 . 208.4.3. 购买道具 . 238.4.4. 查询剩余点数 . 268.4.5. 查询充值记录 . 28QB-II8.4.6. 查询消费历史记录 . 308.5. 单机游戏（8.5 节特指在下载单机游戏后,需购买道具、关卡、物品等业务时的接口要求，以下简称“客户端单机购买道具类业务”） . 368.5.1. 登录客户端单机购买道具类业务 . 368.5.2. 用户充值 . 388.5.3. 购买道具 . 398.5.4. 查询剩余点数 . 408.5.5. 查询充值记录 . 418.5.6. 查询消费历史记录 . 418.6. WAP 网游业务(8.6 节特指使用游戏免费，在游戏中用点数购买道具计费的图文游戏。以下简称“WAP 网游业务”) . 418.6.1. 登录WAP 网游业务 . 418.6.2. 用户充值 . 438.6.3. 购买道具 . 438.6.4. 查询剩余点数 . 438.6.5. 查询充值记录 . 438.6.6. 查询消费历史记录 . 438.7. 单机游戏下载后触发计费 . 438.7.1. 描述 . 438.7.2. 处理流程 . 448.7.3. JAD 规范 . 448.8. 短信计费 . 458.8.1. 描述 . 458.8.2. 处理流程 . 458.8.3. 短信格式 . 458.8.4. 长号码 . 468.8.5. 短信示例 . 4. 客户端单机业务（一个计费点） . 4. 客户端单机业务（多个计费点） . 4. 客户端网游业务（多个计费点） . 479. 附录. 50附录A：内容上传 . 50附录B：WAP 网关与联网服务器的接口 . 53附录C：状态码列表（包括错误代码） . 53附录D：业务接入申请表 . 61附录E：充值代码列表 . 64附录F：J2ME 客户端JAD 文件规范 . 66QB-III前言本标准规定了中国移动游戏业务平台与其上运营的游戏间的开发接口及相关协议，是各游戏开发商开发游戏的依据，以满足游戏业务平台的要求。本标准主要包括以下几方面内容： 业务概述、游戏界面要求、数据类型和接口要求等。本标准由中移 号文件印发。本标准由中国移动通信有限公司技术部提出并归口。本标准由中国移动通信有限公司技术部负责解释，具体细节由中国移动通信有限公司研究院负责解释。本标准起草单位：中国移动通信研究院本标准主要起草人： 何彬QB-11. 范围本标准规定了中国移动游戏业务平台上的游戏开发规范，供各游戏 CP/SP 在开发游戏时使用。2. 修订历史时间 内容 版本号 作者2008-5-22 添加WAP 代理接口描述及WAP 参数透传说明 1.1.1 卢伟勤2008-5-23 完善网游相关接口的文档 1.1.2 卢伟勤2008-5-27 增加附录C、附录D、附录E增加接口流程图1.2.0 梁秋实2008-6-3 修订A） 附录 A：内容上传实体包格式B） 附录 B：WAP 网关与联网服务器的接口1.2.1 梁秋实2008-6-16 增加客户端单机游戏购买道具类业务 1.2.2 刘景岩2008-7-9 修订充值渠道代码以及完善打包规范 1.2.4 梁秋实2008-8-18 状态码列表补充，增加错误码1304，1305，1306，1307，13081.2.5 甘竹芳2008-8-26 状态码列表补充，增加错误码2210，2211，2213，2214（为门户提供的PortalQuery 接口所使用的状态码）1.2.6 甘竹芳2008-9-19 增加“8.7 单机游戏下载后触发计费”章节的内容增加附录F：J2ME 客户端JAD 文件规范1.2.7 梁秋实2008-11-7 新增“短信计费”功能，支持客户端单机短信激活计费、客户端单机试玩转激活业务和客户端网游道具业务（参见8.8 短信计费）。1.2.8 梁秋实2008-11-12 增加状态码：1802,1310,1401,1402,1403,398,399；修订202 状态码含义；参见附录C。增加 51 元100 元充值代码的定义，参见附录E。1.2.8 梁秋实2008-11-13 增加：6.5.短信计费业务订购页面要求。 1.2.8 李倩2008-12-30 修订接口URL 错误:.输入参数增加”/bizcontrol”.接口地址增加”/bizcontrol”.接口地址增加”/bizcontrol”1.2.9 梁秋实2009-01-16 修订点数计费业务价格说明与用户点数余额不足不需要向用户提示余额不足信息1.2.10 刘景岩2009-01-19 增加“8.8.6. 短信购买道具结果通知接口”和“. 同步计费结果” 的内容1.2.10 梁秋实QB-23. 规范性引用文件下列文件中的条款通过本标准的引用而成为本标准的条款。凡是注日期的引用文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本标准，然而，鼓励根据本标准达成协议的各方研究是否可使用这些文件的最新版本。凡是不注日期的引用文件，其最新版本适用于本标准。1 游戏业务平台总体技术要求V1.0.0 中国移动通信有限公司1 游戏业务平台设备规范V1.0.0 中国移动通信有限公司2 游戏业务平台接口规范V1.0.0 中国移动通信有限公司3 游戏业务平台业务规范V1.0.0 中国移动通信有限公司4超文本传送协议（Hypertext Transfer Protocol） -HTTP/1.1-RFC 26165 SOAP 协议 V1.16 SOAP 协议 V1.27HTTP鉴权(HTTP Authentication: Basic and DigestAccess Authentication)-RFC26174. 术语、定义和缩略语下列术语、定义和缩略语适用于本标准：词语 解释OTA Over The Air, 即空中、无线方式HTTP Hyper Text Transfer Protocol，超文本传输协议XML eXtensible Markup Language 可扩展标记语言SOAP Simple Object Access Protocol 简单对象访问协议CP Content Provider内容提供商SP Service Provider 服务提供商CMGP 游戏业务平台业务网元 指www portal、 wap portal、网游服务器等QB-35. 业务概述5.1. 业务概念游戏业务平台是统一接入中国移动游戏业务的平台，通过与各类门户等外围系统进行业务交互，提供内容管理、营销管理、点数管理、统计分析等能力给外围设备开展游戏类业务。5.2. 业务开放范围本业务向能够通过 GPRS、3G 网络接入到中国移动的手机用户开放。游戏业务平台所有业务计费以及联网游戏运行，均必须使用 CMWAP 联网；游戏业务平台合作方开发的客户端应用程序须对未选择CMWAP 联网的用户进行友好提示。游戏业务平台客户端业务可以是由 J2ME、Symbian、Windows Mobile、Mophun、C+等语言开发5.3. 业务类型5.3.1. 按使用方式分类 单机游戏：在使用过程中通常不需要通过移动网络与游戏网络服务器或其他客户端发生互动的游戏叫单机游戏，仅触发联网进行激活、计费、上传积分等游戏属于单机游戏。单机游戏包括但不限于单机java 和单机symbian 游戏。 手机网游：在使用过程中需要通过移动网络与游戏网络服务器或其他客户发生互动的游戏叫手机网游，但不包括仅用联网实现激活、上传积分等功能的游戏。 图文游戏：即 WAP 游戏，为不需下载客户端而直接联网使用的游戏。游戏业务平台将图文游戏分为两类：WAP 单机游戏：指按进入游戏次数收取用户费用的图文游戏，即按次计费的图文游戏。以下简称“WAP 单机业务”WAP 网游业务：指使用游戏免费，在游戏中需购买道具计费的图文游戏。游戏业务平台可为图文游戏中的道具提供计费。以下简称“WAP 网游业务”5.3.2. 按计费方式分类游戏业务平台上的游戏计费包含流量费和信息费，本分类方式只基于信息费。依据信息费，可分为按次计费和按月计费两种： 按次计费：指按照成功下载次数或按成功激活次数收取费用的方式。a) 按次游戏不需要退订；b) 按次游戏可以设计为下载计费也可以为激活计费；c) 用户可以选择话费或点数消费方式。QB-4 按月计费：指按月收取月信息费的游戏。此类游戏使用时需要连接承载平台，用户下载时并不触发计费，在使用此游戏时，此游戏到承载平台进行鉴权，按自然月计费，用户在每个自然月第一次使用时触发计费。a) 次月用户再次使用时将要求用户重新确认收费方式，如果用户不使用则不收取信息费；b) 按自然月计费游戏无需退订，当月不使用不计费；。C) 用户可以选择话费或点数消费方式。 包月计费5.3.3. 按用户消费方式分类.点数消费方式当用户购买手机网游的道具或单机游戏时，如果游戏点数余额满足定价要求，则从用户游戏帐户中扣除，产生点数消耗，平台将依据点数消耗的实际情况与SP 进行分帐。点数消费适用于不限定计费频次、不限定计费点触发时间的业务，手机网游一般采取点数计费的方式。游戏业务平台支持用户下载游戏客户端后使用到一定次数、某个关卡、购买某种道具时触发点数支付计费。游戏业务平台可以提供游戏客户端下载（计费/免费），无客户端业务（如WAP 网游业务）可直接联网使用，两者均可在游戏进行中触发计费；游戏业务平台还可以提供同一业务多次点数支付计费，用户在使用此类业务时需先在游戏业务平台的用户帐户中充值。用户每月可向其游戏帐户充值游戏点数，充值金额将从话费中扣除。. 话费消费方式指用户下载或激活游戏时，所需费用直接从用户的手机话费中扣除。6. 游戏界面要求:6.1. 应用界面设计基本原则游戏 CP/SP 开发的客户端应用程序的操作界面必须与手机已有功能的操作习惯一致；游戏程序启动界面必须使用中国移动指定的统一标识，游戏LOGO 必须按照中国移动手机游戏标识使用规范.pdf制作，LOGO 展现必须符合规范内容，不应出现必要LOGO 内容的缺失或不必要LOGO 内容的增添，当SP 与CP 是同一厂商时，即SP 与CP 的LOGO 一致时，静态LOGO 图片则应只展现一次该LOGO，动态图片则应在其中一个LOGO 的位置放置该游戏的游戏LOGO，以避免重复；游戏主菜单界面必须有一个“更多游戏”的选项指向中国移动指定的WAP 链接，链接地址QB-5为：/gcomm1/portal/spchannel.do?url=/wap/s.do?j=3channel所有游戏必须按照附录 C，根据相关状态码向用户提示规范用语。6.2. 游戏业务平台相关接口调用的入口说明6.2.1. 游戏点数充值（包括所有单机和网络游戏）：A）在应用（游戏）的主菜单界面，必须有“游戏点数”充值的入口；B）在应用（游戏）的游戏界面，必须有至少一处的明显位置为“游戏点数”充值的入口；C）在“游戏点数”充值界面，必须有“游戏点数”介绍说明和“游戏点数”充值的帮助信息。6.2.2. 游戏点数消费（仅限网络游戏和需要购买道具的单机游戏，包括短信计费的单机游戏）：A）在应用（游戏）的游戏界面，必须有至少一处的明显位置为“游戏点数”消费的入口；B）在“游戏点数”消费界面，必须显示与上报业务局数据一致的资费说明；C）在“游戏点数”消费界面，必须有“游戏点数”介绍说明和“游戏点数”消费的帮助信息。D）在道具资费说明中，必须写明价格为“XX 点（等同于YY 元人民币）”，XX 代表道具的点数价格，YY 代表道具的人民币价格，点数和人民币元的比例关系为100：1；例如：道具名称为“刀”，价格需写明为“需200 点（等同于2 元人民币）”6.2.3. 游戏点数余额及明细查询：A）在“游戏点数”充值和“游戏点数”消费界面必须显示游戏点数余额；B）在应用（游戏）的游戏界面，必须有至少一处的明显位置为“游戏点数”余额及明细查询的入口C）在游戏界面中，必须有至少一处的明显位置为“购买物品（道具）”查询的入口，用户可以查询该游戏的所有购买物品或道具的明细，包括物品（道具）的名称，购买时间和所消耗的游戏点数。D）在“游戏点数”余额及明细查询界面，用户可以查询购买点数的详细记录和消费点数的详细记录，详细记录按照消费时间倒序排列（即时间较近的记录排列在前，时间较远的记录排列在后）E）在“游戏点数”余额查询界面，必须有“游戏点数”介绍说明和“游戏点数”余额查询的帮助信息。帮助信息如下：1、游戏点数：游戏点数是移动梦网游戏频道的为用户提供的一种游戏支付方式，用户可以使用账户中的点数来购买游戏或消费游戏道具。QB-62、点数充值：每个用户在移动梦网游戏频道都有自己的账户，用户可以通过话费购买点数的方式给自己的账户充值，1 元话费可购买100 点点数，每月最多可以购买50 元即5000 点点数。3、点数账户：每个用户的手机号码在移动梦网游戏频道都有一个固定的点数账户，用户可以使用账户内的点数购买游戏和在不同的游戏中购买道具，点数账户并不是用户在某款游戏中的游戏账户。F）游戏点数消费和充值记录查询界面中应包含的内容：1、充值记录查询和点数消费记录查询应该提供用户可选时间范围2、点数消费界面应显示：消费时间、道具名称、道具数量、消费金额3、点数消费记录只显示用户在本游戏中的消费记录消费记录4、充值记录查询应显示全平台充值记录，包括其他渠道的充值记录，充值界面应显示：充值时间、充值渠道、充值金额5、游戏中点数道具消费项，应明确告知用户道具名称，道具价格，以及确定购买按钮（参见6.2.2 中的相关说明）。游戏业务平台已经实现当用户购买道具或业务其点数余额不足时，平台自动为用户将相应话费转换成为该道具或业务所需相应点数并直接进行购买，所以当用户余额不足时不应再弹出“点数余额不足，请充值”的提示，而应该将用户购买请求直接转发游戏业务平台进行处理6.3. 游戏激活界面设计除游戏业务平台配置并生效了局数据的计费点外，游戏中一律不得出现其他平台代计费点（例如短信、WAP 代计费等）。话费消费和点数消费的方式不能同时存在于一个游戏中。按不同用户的消费方式分类，不同的激活界面设计要求如下：6.3.1 话费计费：用话费消费完整版游戏（下载免费，一次激活终身使用）1、激活界面必须设计在主菜单之前，游戏标识（LOGO）之后，如果游戏设计了开场图文或动画展示，则可以把开场图文或动画展示放置在激活界面之前。2、在开始游戏正常进行5 分钟内必须可测试到激活点3、激活提示语必须包括以下信息：游戏名称、游戏价格、一次激活终身使用、需要使用CMWAP联网、如您曾激活过本游戏则此次激活不扣费，对于部分在JAVA 连网设置中默认使用代理,三星手机（如D508D608）应做额外处理，当用户激活失败时应提示用户关闭JAVA 联网设置中的代理。1300 状态激活成功后应显示以下信息：提示激活成功，告知扣费金额。1301 状态激活成功后应显示以下信息：提示激活成功，告知用户并未扣费。QB-76.3.2 点数计费：用点数消费完整版游戏（下载免费，一次激活终身使用）1、激活界面必须设计在主菜单之前，游戏标识（LOGO）之后，如果游戏设计了开场图文或动画展示，则可以把开场图文或动画展示放置在激活界面之前。2、在开始游戏正常进行5 分钟内必须可测试到激活点3、激活提示语必须包括以下信息：游戏名称、游戏价格、一次激活终身使用、需要使用CMWAP联网、如您曾激活过本游戏则此次激活不扣费，对于部分在JAVA 连网设置中默认使用代理,三星手机（如D508D608）应做额外处理，当用户激活失败时应提示用户关闭JAVA 联网设置中的代理。激活提示语必须在屏幕明显位置，用户在不拖动滚屏情况下即可看到激活提示说明1300 状态激活成功后应显示以下信息：提示激活成功，告知扣费金额。1301 状态激活成功后应显示以下信息：提示激活成功，告知用户并未扣费。4、当用户点数余额不足时应提示用户充值，并提供WAP 充值页面入口，用户充值成功后可正常返回游戏界面。6.3.3 点数计费：用点数灵活消费游戏内关卡、道具等（下载免费、道具收费、关卡收费、特殊功能收费等）1、在满足规定的情况下, 消费点可设置在游戏进行的任意阶段（消费点设置相关规定请参见游戏频道暂行管理规范V2.0），但在游戏开始后正常进行10 分钟内必须可测试到至少一个消费点；2、具备6.2 节所有功能。6.4. 应用界面文字格式要求对于在手机中显示的应用程序名称，所有可以用中文表示的文件名，必须用中文表示，以便于用户在手机内查找已订购应用；对于应用程序内向用户呈现的显示界面，所有可以用中文表示的内容，必须用中文表示；要求能在应用所支持的手机上正确显示；此中文显示要求包括各菜单选项，帮助信息，指示信息。QB-86.5. 短信计费业务订购页面要求(1) 必须明确提示用户订购业务（或道具）名称；(2) 必须明确提示用户订购业务（或道具）价格，在道具资费说明中，必须写明价格为“XX点（等同于YY 元人民币）”，XX 代表道具的点数价格，YY 代表道具的人民币价格，点数和人民币元的比例关系为100：1；例如：道具名称为“刀”，价格需写明为：需“200 点”（等同于2 元人民币）(3) 提示页面必须包括以下内容：“如果您账户余额不足，系统将自动为您补足金额。”7. 数据类型7.1. 基本类型类型名称 类型描述Char 字符类型String 字符串Int 整型Float 浮点型Date 日期格式7.2. 复合类型XML 格式采用W3C 的1.0 规范，字符集采用UTF-8。要求每个XML 消息格式都是以起始。接口协议使用 HTTP 协议，落地方为发起方提供访问的URL，发起方使用HTTP POST方法发送请求报文并得到应答报文，发起方作为落地方的HTTP 客户端，落地方作为发起方的HTTP 服务器。因此，各个参与方需要同时实现HTTP 客户端以及服务器的功能。确定 返回您是否购买？需“XX点”（等同于YY元人民币）如果您账，户余额不足系统将自动为您补足金额QB-9XML 报文放置在HTTP 的BODY 里面，要求是UTF-8 的编码。同时要保证HTTP 的BODY 里面仅放置XML 完整报文。消息格式采用 XMLSchema 来定义，遵循/2001/XMLSchema 的国际标准。UserID描述：用于标识用户的Schema。表7-1字段名称重要性 字段类型 长度 字段描述userIdType 必须 String 1 用户标识类型1：用手机号码标识（不带86）2：用登录ID 标识3：用userId 标识4：用手机号码和登录ID 标识5：其他使用多个标识userLabel 必须 String 20 用户标识QueryChargeRecord描述：查询用户充值记录时，返回的信息。表7-2字段名称重要性 字段类型 长度 字段描述hRet 必须 String 4 参考相应返回值Status 必须 String 4 状态信息userIdType 必须 String 1 用户标识类型userLabel 必须 String 20 用户标识startSequence 必须 String 8 本次查询的起始序号recordCount 必须 String 8 返回记录数目chargeList 必须ConsumerSchema 明细清单ConsumerSchema描述：用于描述消费记录具体信息的Schema。表7-3字段名称重要性 字段类型 长度 字段描述date M String 16 消费日期格式为yyyymmdd hh24:miconsumerType M string 1 消费类型O ：开户A：充值C：消费X：注销point M Float 4 点数cpId O String 12 合作方代码cpServiceId O String 12 业务代码或充值代码serviceName O String 12 充值名称或业务名称，或道具名称QB-10QueryBalanceResp描述：查询用户剩余点数时，返回的信息。表7-4字段名称重要性 字段类型 长度 字段描述hRet 必须 String 4 参考相应返回值msgType 必须 String 30 操作类型Status 必须 String 4 状态信息userIdType 必须 String 1 用户标识类型userLabel 必须 String 20 用户标识point 必须 Float 4 剩余点数，精确到小数点后2 位SyncInfo描述：同步给网游服务器的信息。表7-5字段名称重要性 字段类型 长度 字段描述userId 必须 String 8 用户伪码key 必须 String 8 签名key7.3. 状态码系统内状态码：内码是指系统内部逻辑处理的返回状态，合作方应该根据系统内码来显示用户提示。系统外状态码：外码用于合作方做业务逻辑判断：0代表成功；1代表失败。失败原因可以参见内码说明。举例：1.内码：1300 对应外码为0，表示计费成功，用户应该可以进入游戏。而1300的定义表示这次计费请求实际产生了费用。2.内码：1301 对应外码为0，表示计费成功，用户应该可以进入游戏。而1301的定义表示用户之前已经已经具备该业务的定购关系，本次计费请求不产生实际费用，用户可以进入游戏。详细状态码列表请参见附录C。7.4. 系统级错误代码请参见附录C。QB-118. 接口要求8.1. 单机游戏(8.1 节特指下载游戏客户端后，用话费或点数消费完整版游戏（一次性激活、终身使用)的接口要求)8.1.1. 描述用户消费单机游戏，只有用户第一次播放时计费。图 8-1：用户购买单机游戏流程图QB-. 单机游戏RMS 写入规则. 输入参数http:/:/bizcontrol/OrderSingleGame?sender=202&cpId=xxx&cpServiceId=xxx&packageId=xxx&channelId=xxx表8-1参数名称重要性 类型 长度 描述信息sender 必须 String 3 网元编号，此处填写“202”cpId 必须 String 6 合作方IDcpServiceId 必须 String 12 业