DB44-T 2008-2017 移动游戏联运平台接入技术要求

备案号：57238-2017DB44DB44/T2008—2017移动游戏联运平台接入技术要求Accesstechniquerequirementsformobilegamesjointoperationplatform2017-06-23发布2017-09-23实施广东省质量技术监督局发布IDB44/T2008—2017 12规范性引用文件 13术语和定义 14缩略语 25平台的接入 35.1平台体系架构 35.2总体流程 35.3接入方式与流程 46平台接口 66.1游戏内容供应商接口 66.2充值接口 6.3游戏推广渠道接口 附录A（资料性附录）游戏内容供应商实例参考 参考文献 DB44/T2008—2017本标准按照GB/T1.1—2009给出的规则起草。本标准由广东省质量技术监督局提出并归口。本标准起草单位：有米科技股份有限公司、华南理工大学、广州市标准化研究院、广州大娱信息科技有限公司、江苏米游信息科技有限公司、广州君海网络科技有限公司、广州常游信息科技有限公司、珠海爱游唯科技有限公司。本标准主要起草人：董守斌、胡金龙、陈第、梁铭俊、陈江玲、王贺珍、白桂洪、黄淦、王进。本标准为首次发布。DB44/T2008—20171移动游戏联运平台接入技术要求本标准规定了移动游戏联运平台的体系架构、平台的接入方式及流程，并定义了移动游戏联运平台和其平台运营的移动游戏之间的一系列应用程序接口。本标准适用于消费者通过移动网络利用随身携带的移动终端（手机或平板电脑等）行操作的游戏。2规范性引用文件下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅所注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。JT/T0088.3中国金融移动支付应用基础第3部分：支付应用标识符JR/T0088.4中国金融移动支付应用基础第4部分：支付账户介质识别码JR/T0092中国金融移动支付客户端技术规范YD/T2360移动游戏业务平台技术要求3术语和定义YD/T2360界定的以及下列术语和定义适用于本文件。3.1移动游戏联运平台mobilegamesjointoperationplatform为移动游戏供应商和游戏用户提供双向服务，保障双方利益，并通过提升用户服务获得收益而构建的与移动游戏经营、运作相关的平台。3.2移动终端mobileterminal手机及通过使用无线通信方式连接的笔记本电脑、平板电脑、POS机、车载电脑等计算机设备（又称为移动通信终端）。3.3游戏内容供应商gamecontentprovider提供需要网络连接的移动游戏的开发商或者代理商。3.4游戏推广渠道商gamepromotionchannelprovider提供游戏推广服务，将游戏分发到终端用户的代理商。3.5DB44/T2008—20172游戏内容服务器gamecontentserver提供游戏在线服务（包括通过移动网络为移动游戏提供数据通信服务，以及与外部合作提供数据服务）的服务器系统。3.6游戏币gamecurrency由移动游戏平台推出的可以用于移动游戏内人物升级或购置道具物品的一种虚拟货币。3.7第三方支付thethird-partypayment移动用户在使用APP的过程中，通过移动游戏联运平台开发的支付接口，利用第三方支付平台完成交易过程。3.8第三方支付平台thethird-partypaymentplatform与各大银行签约，且具备一定实力和信誉保障的第三方独立机构提供的交易支持平台。在通过第三方支付平台的交易中，买方选购商品后，使用第三方平台提供的账户进行货款支付，由第三方通知卖家货款到达。3.9游戏推广渠道gamepromotionchannel为移动游戏提供推广方案，使游戏最终达到终端用户的方式。3.10媒体渠道mediachannel通过移动应用APP，以广告主的身份在移动广告平台进行游戏推广的方式。3.11厂商渠道manufacturerchannel通过移动终端设备生产商内置移动游戏来进行游戏推广的方式。3.12自有平台ownplatform对自营的游戏进行推广的厂商自建网站或者应用。4缩略语下列缩略语适用于本文件。APPCPDCPS应用按行动分成按下载分成按收益分成ApplicationCostPerActionCostPerDownloadCostPerSaleDB44/T2008—20173CPT按时长分成CostPerTimePOSPointOfSalesSDK软件开发套件SoftwareDevelopmentKitUD用户自定义UserDefinedUI用户界面UserInterface5平台的接入5.1平台体系架构移动游戏联运平台是一个为移动游戏内容供应商和游戏用户提供双向服务的平台，支持账户储值、实时结算、统一登录以及游戏客服功能。它不仅能够同时运营多款移动游戏，而且为用户提供统一的通行证和游戏充值服务，并和游戏内容供应商共享收益。移动游戏联运平台体系架构见图1所示，该平台主要提供三大功能：游戏内容供应商的接入、第三方支付的接入以及游戏推广功能。针对这三大功能，平台提供三种类型的SDK接口：游戏内容供应商接口、充值接口以及游戏推广渠道接口。图1移动游戏联运平台体系架构5.2总体流程移动游戏联运平台日常运营总体流程（见图2）包含三个方面的流程，通过这些流程的共同协作，DB44/T2008—20174实现游戏客户端和游戏服务器之间的正常登录校验。这三个方面的流程分别是：a)登录流程：移动游戏联运平台、游戏客户端和游戏内容供应商之间的初始化、注册登录、登出、切换账号、退出等基础操作相关流程；b)充值流程：移动游戏联运平台、游戏客户端和第三方支付平台之间的充值流程；c)推广流程：移动游戏联运平台和游戏推广渠道的推广流程。图2移动游戏联运平台总体流程5.3接入方式与流程5.3.1游戏内容供应商的接入与登录流程游戏内容供应商向移动游戏联运平台提供游戏产品，应具有若干游戏内容服务器的基础设备支持，确保游戏产品能快速接入。图3为登录流程图，流程主要分以下几步：a)游戏客户端调用SDK登录接口来显示登录界面，引导用户通过平台自身账号登录，或者通过平台认可的第三方登录方式来登录游戏；b)登录成功后，返回用户信息（包含用户ID、时间戳、签名）给游戏客户端，游戏客户端需要将用户信息传到游戏内容供应商服务器进行登录校验，校验方法按6.1.2.3执行，游戏内容供应DB44/T2008—20175商服务器将校验结果通知游戏客户端。5.3.2第三方支付的接入与充值流程第三方支付的接入为用户提供快捷方便的消费渠道，包含微信支付、支付宝支付、银行卡支付等支付方式。第三方支付的接入，应由第三方支付平台提供其自定义支付接口，移动游戏联运平台使用该接口与第三方支付平台通信。支付接口负责移动游戏联运平台与第三方支付平台的连接，该接口通过设置一些相关的接口参数，确保交易顺利完成。图4为充值流程图，流程主要分以下几步：a)游戏客户端调用SDK充值接口显示充值界面，引导用户操作，游戏客户端提交“订单请求”给移动游戏联运平台，移动游戏联运平台返回“订单信息”给游戏客户端；b)游戏客户端向第三方支付平台发送“支付请求”进行扣费，第三方支付平台返回“支付确认”给游戏客户端，并将订单及消费信息“订单确认”发送给移动游戏联运平台；c)移动游戏联运平台收到“订单确认”后调用游戏内容供应商服务器充值结果通知接口，将“充值回调结果”发送给游戏内容供应商服务器；d)游戏内容供应商服务器对“充值回调结果”进行“充值校验”，校验成功需返回成功标识到移动游戏联运平台，充值结果通知参数及游戏内容供应商服务器校验方法按6.1.3.2执行；e)游戏内容供应商“发送游戏币”给游戏客户端，用户完成充值过程。5.3.3游戏推广渠道的接入游戏推广渠道将游戏产品以APP形式或其他形式快速的推广给用户。游戏推广渠道的接入，需要游戏推广渠道商提供其自定义渠道接口，移动游戏联运平台使用该接口与游戏推广渠道进行通信。游戏推广渠道接口方便移动游戏联运平台对游戏内容供应商的游戏产品进行推广与运营。如图5所示，移动游戏联运平台通过与游戏推广渠道商进行合作，其中合作方式包括收益分成CPS、行动分成CPA、下载分成CPD、时长分成CPT等，将游戏产品分发到游戏推广渠道商，游戏推广渠道商将游戏产品以APP形式或其他形式推广给移动终端。推广的形式由移动游戏联运平台将同一个游戏软件套件分别包装成不同的渠道套件，对即将要投放的各种渠道，渠道套件都分别有一个对应的内嵌渠道号，用于后续对推广效果的统计和评估。DB44/T2008—20176游戏推广渠道商3.推广方式移动终端游戏推广3.推广方式移动终端渠道接口1.分发游戏产品2.确认合作方式移动游戏联运平台服务器图5游戏推广流程6平台接口6.1游戏内容供应商接口6.1.1概述移动游戏联运平台和移动游戏内容供应商之间的游戏内容供应商接口包含用户账号接口、虚拟币管理接口、增值服务接口三部分（见图6）。各部分具体的接口实例可参考附录A。图6游戏内容供应商接口的结构图6.1.2用户账号接口6.1.2.1初始化接口初始化接口要求如下：DB44/T2008—20177a)描述：该接口用于SDK初始化移动游戏联运平台账户，包括设置游戏应用ID（AppID）和游戏应用密码（AppSecret）等参数，并设置初始化回调和账号回调；b)调用方式：在游戏主界面的创建函数中调用初始化接口，初始化AppID和AppSecret等参数，并设置初始化回调监听器和账号回调监听器，该方法确保调用一次即可；c)接口的名称：例如：/account/Init；d)初始化接口的输入/输出参数：见表1，其中Code为行为状态码，标记SDK的状态正常与否，GameUserInfo为游戏用户信息，至少应包含平台用户唯一标志OpenId，用户签名Sign和时间戳timestamp。表1初始化接口的输入/输出参数6.1.2.2登录接口登录接口要求如下：a)描述：该接口用于在SDK初始化成功后，调用用户登录平台账号的界面，在此界面用户可以完成切换账户、登录及注册等操作；b)调用方式：在初始化接口回调初始化成功后，在UI线程调用登录接口来显示登录界面，完成用户的登录及注册操作。操作成功后，登录回调接口返回用户ID（Uid）、时间戳Timestamp、登录签名Sign。游戏内容供应商需要将登录信息传回游戏联运平台服务器，在游戏内容供应商服务器进行登录校验，详情参考登录校验部分；c)接口的名称：例如：/account/Login；d)登录接口的输入/输出参数：见表2，其中输入由用户自定义逻辑，不做规范要求，输出包含用户ID（Uid）、发生时间（Timestamp）、登录签名（Sign）。表2登录接口的输入/输出参数6.1.2.3登录接口校验登录接口校验要求如下：a)描述：用于游戏客户端登录成功后，将用户的登录信息传到游戏服务端做登录态验证，游戏内容供应商需要将登录信息传回游戏联运平台服务器，在游戏内容供应商服务器进行登录校验；b)调用方式：接口接受联运平台用户ID、登录时间、待验证用户登录态以及通信密钥，返回用户登录合法标识给游戏联运平台服务器；DB44/T2008—20178c)接口的名称：例如：/account/LoginCheck；d)登录接口校验的输入/输出参数：见表3，其中，OpenId为联运平台用户唯一标识，Timestamp为用户登录时间，Sign为用户登录签名,Server_secret为服务端通信密钥，以上信息用来判断玩家登录是否合法。表3登录接口校验的输入/输出参数6.1.2.4登出接口登出接口要求如下：a)描述：该接口用于用户手动登出账号，该接口需要切换账户时调用，游戏正常退出不需要手动调用该接口；b)调用方式：使用登出接口，该接口将触发登出回调函数；c)接口的名称：例如：/account/Logout；d)登出接口的输入/输出参数：见表4，登出接口的输入输出不做规范，由用户自定义。表4登出接口的输入/输出参数6.1.2.5上报玩家信息接口上报玩家信息接口要求如下：a)描述：游戏内容服务器通过该接口上报游戏角色信息，以便跟踪处理账号纠纷等问题，通过在合适的时机（例如创建角色、登录角色以及角色等级变动）调用此接口，上报游戏角色信息；b)调用方式：游戏内容服务器需在相应的时机使用SDK开发软件套件的设置角色信息接口来上报游戏角色信息，在不同的时机分别使用不同的参数，例如，设置角色信息接口的上报时机参数的可能值可以为表5所示；c)接口的名称：例如：/account/Submit；d)上报玩家信息接口的输入/输出参数：见表6，其中GameRolerInfo为要上报的游戏用户信息，接口返回值由用户自定义。DB44/T2008—20179表5游戏角色信息上报时机参数表表6上报玩家信息接口的输入/输出参数6.1.2.6账号中心接口账号中心接口要求如下：a)描述：游戏内容供应商需在游戏主界面或者设置页等二级页面中增加一个进入账号中心的入口，比如一个“账号中心”的按钮，用户点击之后，游戏调用账号中心接口进入账号中心界面，用户在账号中心界面可以完成切换账号、修改密码、绑定移动终端设备、查看充值记录等功能；b)调用方式：使用SDK开发软件套件的账号管理器来调用账号中心接口；c)接口的名称：例如：/account/UserCenter；d)账号中心接口的输入/输出参数：见表7，账号中心接口由用户自定义。表7账号中心接口的输入/输出参数6.1.3虚拟币管理接口6.1.3.1充值接口a)描述：游戏内容供应商调用此接口实现用户充值功能，充值模式有两种，定额模式和汇率模式：定额模式下，用户不允许修改充值金额，只能充值固定档位的金额；汇率模式下，用户可在充值过程中随意修改充值的金额，游戏需根据用户实际充值的金额发放对应比例的游戏币；b)调用方式：用户点击充值按钮支付，游戏调用充值接口来显示充值界面，在充值界面上接管用户充值流程，完成充值过程；c)接口的名称：例如：/manage/Charge；d)充值接口的输入/输出参数：见表8，其中PaymentInfo为订单信息，Code为行为状态码，用来标识SDK状态，输出由用户自定义。DB44/T2008—2017表8充值接口的输入/输出参数6.1.3.2充值接口校验充值接口校验要求如下：a)描述：用户充值成功后，移动游戏联运平台需调用游戏联运平台服务器充值结果通知接口，将充值结果通知给游戏内容供应商服务器，以便发放虚拟货币给用户。充值结果通知应采用重发机制，即，若移动游戏联运平台没有收到游戏内容供应商服务器返回的成功标志，平台应对同一笔订单的通知进行周期性重发；b)调用方式：移动游戏联运平台用GET的方式，从游戏内容供应商服务器获取成功标志；c)接口的名称：例如：/manage/ChargeCheck；d)充值接口校验的输入/输出参数：见表9，其中Param为Param类型的请求参数，该请求参数包含一系列参数键值对，具体见表10，Server_secret为联运平台密钥，用来校验充值接口，MD5value为产生的参数签名值。表9充值接口校验的输入/输出参数表10充值接口校验请求参数6.1.4增值服务接口DB44/T2008—20176.1.4.1浮动菜单接口浮动菜单接口要求如下：a)描述：在SDK初始化后（如果在SDK初始化前调用，则可能导致后台控制浮动菜单的相关功能失效游戏内容供应商可在游戏界面显示充值业务浮动菜单。充值业务浮动菜单主要功能有“账户”（账户中心入口）、“虚拟货币”（虚拟货币充值）、“礼包”（获取虚拟礼包）、“隐藏”（隐藏浮动菜单）；b)调用方式：SDK初始化后，在需要显示浮动菜单的界面，调用浮动菜单创建接口。游戏内容供应商可调用隐藏浮动菜单接口来隐藏浮动菜单；可调用显示浮动菜单接口来显示浮动菜单；在显示浮动菜单的界面销毁时，需要在销毁处理函数中调用销毁浮动菜单接口来销毁浮动菜单；c)接口的名称：例如：/service/Menu；d)浮动菜单接口的输入/输出参数：见表11，接口的各项参数主要由用户自定义。表11浮动菜单接口的输入/输出参数6.1.4.2退出接口退出接口要求如下：a)描述：该接口用于游戏退出前的SDK相关资源的回收，直接退出可能导致下次启动时出现异常。该接口需要在UI线程中调用，调用后会弹出对话框，游戏可以通过回调获知用户是选择退出或继续游戏；b)调用方式：须在UI线程中调用退出SDK接口函数，在退出对话框的监听器中可以实现用户成功退出和未成功退出的游戏逻辑；c)接口的名称：例如：/service/Exit；d)退出接口的输入/输出参数：见表12，其中Code为行为状态码，标识玩家是否成功退出，输出参数由用户自定义。表12退出接口的输入/输出参数6.2充值接口充值接口应符合JR/T0088.3、JR/T0088.4和JR/T0092的相关要求。6.3游戏推广渠道接口当游戏推广渠道商和移动游戏联运平台达成推广合作时，移动游戏联运平台为每个游戏推广渠道商赋予一个唯一的渠道号。移动游戏联运平台将同一个游戏软件套件分别包装成不同的渠道套件，每个渠DB44/T2008—2017道套件都内嵌一个对应的渠道接口参数，用于后续对推广效果的统计和评估。游戏推广渠道接口参数见表13，其中Channel为渠道号，游戏推广渠道商利用渠道号上报信息给游戏联运平台，输出参数自定义。表13游戏推广渠道接口的输入/输出参数DB44/T2008—2017（资料性附录）游戏内容供应商实例参考A.1用户账号接口A.1.1初始化接口在游戏主Activity的onCreate函数中调用PaySDKManager.initSDK()。初始化AppID和AppSecret等参数，并设置初始化回调（InitCallbackListener）和账号回调（AccountCallbackListener）（如果移动游戏联运平台有切换账户功能，该功能需马上登出当前移动游戏联运平台账户（触发onLogout回调,SDK所触发的onLogout回调第二个参数object为null，开发者可以通过这个参数来判断onLogout回调是来自SDK还是自己手动调用相关登出接口），因此必须在登出回调接口onLogout里面实现登出当前游戏角色、回到游戏初始界面的相关逻辑，否则可能会造成充值错误）。该方法确保调用一次即可。GameParamInfogameParamInfo=newGameParamInfo();//Toast.makeText(context,"初始化成功",Toast.LENGTH_SHORT).show();//Toast.makeText(context,"初始化失败:"+message,Toast..show();}}publicvoidonLogin(intcode,//登录成功后,SDK返回一个GameUserInfo结构,里面包含平台用户唯一标志OpenId,用户签名//"登录成功,用户id:"+userInfo//"用户sign:"+userIn//"timestamp:"+userInfo.getT//Toast.LENGTH_SHORT).show();DB44/T2008—2017//用户按返回键,退出了SDK登录界面,需要进行相关的操作,比如弹出对话框提醒用户重新登}}//通过自定义数据object判断onLogout//object非空时可以用传回的objec//toast("注销成功,用户自定义数据object="+object.toString());//toast("注销成功");}}}});A.1.2登录接口在SDK初始化接口回调初始化成功后，在UI线程调用SDK登录接口PaySDKManager.showLoginView()，注意如果不在UI线程调用可能导致自动登陆时无法弹出处理窗口、用户无法切换账户，SDK将完成用户的登录及注册操作。操作成功后，登录回调接口返回用户Uid、时间戳Timestamp、登录签名Sign。PaySDKManager.showLoginView(context);A.1.3登录接口校验游戏客户端登录成功后，需要将用户的登录信息传到游戏服务端做登录态验证。*@param$openidDB44/T2008—2017returnfalse;}$sign2=md5($signstr);}A.1.4登出接口如果游戏内容供应商需要手动登出账号，使用SDK登出接口PaySDKManager.logoutAccount()。该接口将触发onLogout回调（logoutAccount()中第二个参数为自定义数据，并会在其触发的onLogout中作为参数返回，开发者可通过该参数判断onLogout回调的来源该接口在需要切换账户时调用，游戏正常退出不需要手动调该接口。A.1.5上报玩家信息接口游戏内容供应商必须接入该接口上报玩家信息，以便跟踪处理账号纠纷等问题，通过在合适的时机(创建角色、登录角色以及角色等级变动)调用PaySDKManager.setGameRolerInfo()接口，上报游戏玩家角色信息。GameRolerInforolerInfo=newGameRolerInfo();rolerInfo.setRoleLevel("12rolerInfo.setRoleName("foorolerInfo.setServerName("server_name");*GameRolerInfo.AT_LOGIN_GAM*GameRolerInfo.AT_CREATE_R*GameRolerInfo.AT_LEVE*PaySDKManager.setGameRolerInfo(this,GameRolerInfo.AT_LOGIN_GAME,rolerInfo);A.1.6账号中心接口DB44/T2008—2017游戏内容供应商必须在游戏主界面或者设置页等二级页面中增加一个进入SDK账号中心的入口，比如“账号中心”按钮，用户点击后，游戏调用SDK账号中心接口PaySDKManager.showAccountManagerView()进入账号中心界面，用户在账号中心界面可以完成切换账号、修改密码、绑定手机、查看充值记录等功能。A.2虚拟币管理接口A.2.1充值接口虚拟币充值接口示例如下：PaymentInfopaymentInfo=newPaym//业务类型，SERVICE_TYPE_QUOTA(固定额度模式，充值金额在支付页面不可修改)，SERVICE_TpaymentInfo.setServiceType(PaymentInfo.SERVICE_TYPE_RATE);paymentInfo.setRoleName("foo");}}A.2.2充值接口校验DB44/T2008—2017用户充值成功后，移动游戏联运平台服务器需要调用游戏服务器充值结果通知接口，将充值结果通知给游戏服务器，以便发放虚拟货币给用户。充值结果通知重发机制:若移动游戏联运平台服务端没有收到网游服务端返回的“success”成功标识，将对同一笔订单的通知进行周期性重发(间隔时间为指数型:2分钟,4分钟,8分钟......总共重试10次)。调用方式：GET*@paramstring$secrfunctiongetSignatureksort($params);}//通过md5算法为签名字符串生成一个md5签名,该签名就是我们要追加的sign参数值returnmd5($str);}callbackInfo="rtt7ru35p服务端密钥：待签名字符串：amount=6callbackInfo=rtt7ru35pd92yjidd4caeyp6ln2igpdtopenId=bf7f618e37285527orderId=m201523orderStatus=1payType=UPMPremark=serverId签名结果：DB44/T2008—2017A.3增值服务接口A.3.1浮动菜单接口此接口需在SDK初始