应用接入规范

1、接入流程

(1)线上流程

应用服务商在公共服务体系门户上注册服务商账号,完善企业资质信息;

服务商信息审核通过后,可创建应用,需选择职教或者基教,填写应用信息并上传应用图片等,并在线申请接入某一区域(职教应用需直接接入到职教区域或职教学校);

区域教育行政部门管理员在线审核通过后,服务商可依据本规范进行技术调试;独立应用需线下与央馆申请对接方式;

服务商提交应用上线申请,区域教育行政部门管理员和学校管理员对应用进行审查测试,测试通过的应用可上架;

应用上架后,接入到区域的应用可被接入区域教育行政部门管理员和学校管理员选用,上级区域已选用的,下级区域不需要重复选用即可直接使用,经体系枢纽推送至各级平台用户空间,默认全部展示;接入级别为个人的应用,经体系枢纽推送至各级平台用户空间,默认在“更多应用”或者“应用管理”里面展示,用户可以按需自主选用;

应用服务商只需在体系中完成一次技术接入,上架后可被各区域和学校选用,可以快速形成用户流量,方便应用的规模化使用。


(2)时序图

(3)应用信息说明

基本信息

应用名称:应用的完整名称。应用名称需要具有一定概括性,使用户通过应用名称可大致了解该应用的性质、面向对象等要素。Web端应用名称长度在4-8个中文汉字范围内为最佳展现效果,H5应用名称长度在3-5个中文汉字范围内为最佳展现效果。

应用分类:根据应用的内容性质选择应用的所属分类,包括备课授课、互动课堂、协作互动、网络课程、网络教研、作业测评、数字图书馆、语言学习。

应用接入级别:应用所属的接入级别,可选择:国家级、省级、市级、区县级、校级或个人,将显示在各级教育云平台的用户空间。

应用URL:应用实际的访问地址。平台应用在Web端url和H5应用url中二选一;pc端独立应用填写web页面url;移动端独立应用需同时填写Web页面url和H5页面url。

面向对象:应用针对的使用人群,范围:学生、老师、家长、机构或不限。

应用简介:应用的描述、介绍,显示在应用详情页面。应用简介是在教育云平台应用列表中展示的对应用简单的介绍,此处介绍无需特别详细,但可让用户了解到该应用主体内容、优势等要素,达到吸引用户群点击进入应用的目的。应用简介中不允许出现该应用以外的信息,包括应用厂商网址、地址、联系方式等。应用简介长度在58~78个中文汉字范围内为最佳展现效果。

收费说明:应用需对包含内付费项目进行收费说明,列明有多少收费项,对主要收费项进行详细说明。

访问规则:目前有两种访问规则:单点登录、创建新账号,两种规则二选一;单点登录指平台用户登录后可以直接跳转使用应用;创建新账号指用户需创建新用户登录或者绑定在应用上的账号并使用应用。

企业客服:企业的QQ客服,方便用户及时反馈问题。

演示账号:添加老师、学生和家长的演示账号,便于用户在不登录的场景下即可通过演示账号了解应用基本信息。

应用图标:即应用LOGO,需要具有一定代表性,具体格式要求如下:

图标背景为单色系,web端应用4px圆角;h5应用10px圆角;图标主体图形为纯色图形,#FFFFFFF;图标存储为png格式,24位色透明底,web端应用72*72px;h5应用96*96px;建议在设计过程中,在四周空出几个像素点使得设计的图标与其他图标在视觉上一致,例如:96 x 96 px 图标可以画图区域大小可以设为 88 x 88 px, 四周留出4个像素用于填充(无底色);72x 72 px 图标可以画图区域大小可以设为 68 x 68 px, 四周留出2个像素用于填充(无底色)。图标图形设计含义必须符合应用名称。

应用截图:应用截图是用户在进入应用详情页后,对其展示的应用内部实际截图,可以让用户直观的了解到该应用的展现风格、操作风格等使用体验要素。应用截图中不允许出现该应用以外的信息,包括应用厂商网址、地址、联系方式等。应用截图要求提供两张jpg格式、720*500px的图片。


2、 实现步骤

接入国家公共服务体系的应用,实现步骤按照应用的使用场景分为两种:

平台应用:使用区域平台的用户体系,用户实名认证后,支持通过空间或者平台移动端免登录使用应用,详见平台应用接入实现步骤;

独立应用:可以独立下载安装并登录使用的移动端或者pc端应用,统一走独立应用接入流程。手机端的独立应用需提供web页面推送至用户空间,以便用户扫码下载和扫码登录;同时手机端也需提供H5页面推送至平台移动端,可由平台用户在平台移动端打开H5应用页面并实现单点登录或账号绑定。PC端独立应用需提供web页面推送至用户空间,可由用户空间web页面直接启动本地安装的程序并单点登录或绑定账号。详见独立应用接入实现步骤。


1)web端应用接入

该类应用是指汇聚到各级平台(类似国家平台)中的web端应用,支持平台用户登录平台后使用。

    i.  流程

    

                                            图 17 web端应用接入流程

i.  获取平台传递的参数

在平台接入规范中说明了,用户登录平台后访问应用会传递2个参数,下面详细介绍参数的含义:

ticket:平台调用体系对外接口获取的用户会话票据,里面包含了用户的部分信息,2分钟内使用一次有效;

sysCode:来源编码(区域或者机构),平台传递给应用使用。

ii.    接口调用步骤

①获取接口访问令牌

应用调用体系接口的第一步,访问令牌是服务商使用接口的凭证,通过访问令牌服务商可以使用自身权限下的各种接口。

l http://IP:PORT/apigateway/getAccessToken

l Post请求参数:

appId:应用id,系统自动生成APPID和APPKEY;

timeStamp:当前时间戳;

keyInfo:根据Hmac算法APPID+APPKEY+timeStamp的加密数据;

sysCode:系统来源编码。

l 具体API请参照《开放接口规范》。

②验证用户会话Ticket

应用获取了从平台传递过来的用户会话ticket后,可以根据ticket验证是否用户登录的状态和用户部分信息。

l 调用接口信息如下:

n  请求地址:

http://IP:PORT/userSession/validaTicket?accessToken=ACCESS_TOKEN

n  请求报文:

{

  "ticket":"eUg3OTQ1OWVjMjItZDdjYy0xMWU2LTk5YzctODQzYTRiMzI4NWVlMTQ4NDExODQzNDE3NQ=="

}

n  应答报文:

{

  "retCode": "000000",

  "retDesc": "success",

  "data": {

        "userId": "0040032E20184955GHJHK9EACA1501F8F",

    "name": "周力*",

        "gender": "1",

        "dafaultIdentity": "1",

    "orgRelList":[

  {

           "orgCode": "31450069822",

     "orgName": "某某中学",

     "orgIdentity": "1"

  }

]

      }

    }

n  具体API请参照《开放接口规范》。


2)移动端H5应用

该类应用是指汇聚到移动端平台(类似国家平台移动端)中的H5应用,支持移动端平台用户免登录使用。

        i.  流程

    

                               图 18 移动端H5应用接入流程

i.  获取平台移动端传递的参数

在平台接入规范中说明了,用户登录平台移动端后访问应用会传递2个参数,下面详细介绍参数的含义:

ticket:平台调用体系对外接口获取的用户会话票据,里面包含了用户的部分信息,2分钟内使用一次有效;

sysCode:来源编码(区域或者机构),平台传递给应用使用。

ii.    接口调用步骤

①获取接口访问令牌

应用调用体系接口的第一步,访问令牌是服务商使用接口的凭证,通过访问令牌服务商可以使用自身权限下的各种接口。

l http://IP:PORT/apigateway/getAccessToken

l Post请求参数:

appId:应用id,系统自动生成APPID和APPKEY;

timeStamp:当前时间戳;

keyInfo:根据Hmac算法APPID+APPKEY+timeStamp的加密数据;

sysCode:系统来源编码。

l 具体API请参照《开放接口规范》

②验证用户会话Ticket

应用获取了从平台传递过来的用户会话ticket后,可以根据ticket验证是否用户登录的状态和用户部分信息。

l 调用接口信息如下:

n  请求地址:

http://IP:PORT/userSession/validaTicket?accessToken=ACCESS_TOKEN

n  请求报文:

{

  "ticket":"eUg3OTQ1OWVjMjItZDdjYy0xMWU2LTk5YzctODQzYTRiMzI4NWVlMTQ4NDExODQzNDE3NQ=="

}

n  应答报文:

{

  "retCode": "000000",

  "retDesc": "success",

  "data": {

        "userId": "0040032E20184955GHJHK9EACA1501F8F",

    "name": "周力*",

        "gender": "1",

        "dafaultIdentity": "1",

    "orgRelList":[

  {

           "orgCode": "31450069822",

     "orgName": "某某中学",

     "orgIdentity": "1"

  }

]

   }

  }

n  具体API请参照《开放接口规范》。


(1) 独立应用接入实现步骤

国家公共服务体系中提供了一系列类型的接口,包括会话接口、独立应用实名认证接口、独立应用登记接口、用户信息相关的接口,下面会以独立应用接入为例详细说明下独立应用在对接改造过程会使用到的接口。可以独立下载安装并登录使用的移动端或者pc端应用,统一走独立应用接入流程。

手机端的独立应用需提供web页面推送至用户空间,以便用户扫码下载和扫码登录;同时手机端也需提供H5页面推送至平台移动端,可由平台用户在平台移动端打开H5应用页面并实现单点登录或账号绑定。

PC端独立应用需提供web页面推送至用户空间,可由用户空间web页面直接启动本地安装的程序并单点登录或绑定账号。

独立应用因其特殊的使用场景,接入方式需企业线下与中央电教馆沟通明确,目前存在三种接入方式,三种方式可根据央馆的要求进行选择性接入。三种接入方式分别说明如下。


1实名认证方式

用户登录独立应用并在体系统一的实名认证页面完成认证,推荐采取此种方式。

            i.  流程    

            

                        图 19 实名认证方式流程

    i.  获取体系会话

用户登录应用后需要通过实名校验,成功则返回会话usessionId和会话票据Ticket,未实名认证则返回体系实名认证地址进行实名认证。

获取体系会话接口中会使用该接口验证第三方独立应用的用户是否通过服务体系实名认证,通过验证已实名就创建体系会话返回,未通过则返回体系实名认证地址,独立应用自行跳转后进行实名认证。注:因各应用触发实名认证的操作各异,此处为避免体系直接跳转失败影响用户实名认证体验以及减少体系对跳转地址的合法性校验损耗,需各独立应用自行处理页面跳转。

获取体系会话接口中的可选请求参数适用于本地已经是实名制注册的独立应用,独立应用在获取体系会话的时候需要提示用户是否授权将独立应用上的手机号、姓名、身份证号等实名信息传递给服务体系,如果用户同意授权,则可以携带实名信息到体系,用户在服务体系的实名认证页面上确认实名信息即可完成认证,无需用户再次输入实名信息;如果用户不同意授权,则独立应用不能携带实名信息到体系认证页面。该授权操作作为独立应用接入体系后上线的重要监管项,请各独立应用严格遵循。

l 调用接口信息如下:

n  请求地址:

http://IP:PORT/userSession/validateSession?accessToken=ACCESS_TOKEN

n  Post请求参数:

         userId:独立应用用户Id

         loginAccount: 用户应用登录帐号

         phone:实名认证的手机号码

name:真实姓名

              idCardNo:身份证号码       

n  应答报文:

    {

       "retCode": "000000",

       "retDesc": "success

    }

i.  实名认证页面

未实名认证,则返回报文如下:

   {

       "retCode": "300027",

       "retDesc": "该用户未实名请跳转实名页面进行认证",

"data": {

"certUrl":http://fwtx-open.cdn.bcebos.com/bmp-web/certification/indexPage?param=*****",

          }

     }

根据返回的certUrl地址,跳转到体系实名认证页面,如下图:

                                                图 20 PC端实名认证页面


                  

                              图 21 手机端实名认证页面1

                                       

                                                

                                            图 22 手机端实名认证页面2



用户跳转到实名认证页面,完成实名认证操作成功后,再次获取体系会话则会返回会话usessionId和会话票据Ticket,方可继续使用独立应用。

i.  接口调用步骤

①获取接口访问令牌

应用调用体系接口的第一步,访问令牌是服务商使用接口的凭证,通过访问令牌服务商可以使用自身权限下的各种接口。

l  http://IP:PORT/apigateway/getAccessToken

l  Post请求参数:

appId:应用id,系统自动生成APPID和APPKEY;

timeStamp:当前时间戳;

keyInfo:根据Hmac算法APPID+APPKEY+timeStamp的加密数据;

sysCode:系统来源编码。

l  具体API请参照《开放接口规范》。

②获取体系会话接口调用

应用用户在登陆或注册时,通过获取体系会话来验证是否实名,已实名的则返回体系会话和体系ticket,未实名的则跳转到实名认证页面。

l  调用接口信息如下:

n  请求地址:

http://ip:port/userSession/validateSession?accessToken=ACCESS_TOKEN

n  请求报文:

{

  "userId": "1234",

  "loginAccount": "12345678901"
}

n  应答报文:

{
  "retCode": "000000",
  "retDesc": "success",
  "data": {

        "usessionId": "0040032E20184955GHJHK9EACA1501F8F",

        "ticket": "eUg3OTQ1OWVjMjItZDdjYy0xMWU2LTk5YzctODQzYTRiMzI4NWVlMTQ4NDExODQzNDE3NQ=="

  }
}

n  具体API请参照《开放接口规范》。

2)页面登记方式

第三方用户(应用本身的用户)在应用登录后,通过独立应用实名登记接口进行校验,未进行实名登记的跳转到独立应用实名登记页面进行登记,已进行实名登记的直接返回登记成功,包括手机端和PC端,要求每次登录都需要进行使用登记。以独立应用接入到服务体系的应用需实现应用自身用户和平台空间用户同时使用的应用场景,包括直接登录使用应用和通过空间使用两种使用方式。

I:直接登录使用用户

用户直接登录使用独立应用时,应用方需调用体系独立应用用户登记接口进行校验,未登记需跳转到实名登记页面进行登记,已登记的则正常使用应用,便于国家服务体系监管独立应用的使用情况。

        i.  流程

                                   


                                图 23直接登录使用应用登记页面方式



i.  接口调用步骤

①获取接口访问令牌

应用调用体系接口的第一步,访问令牌是服务商使用接口的凭证,通过访问令牌服务商可以使用自身权限下的各种接口。

l http://IP:PORT/apigateway/getAccessToken

l Post请求参数:

appId:应用id,系统自动生成APPID和APPKEY;

timeStamp:当前时间戳;

keyInfo:根据Hmac算法APPID+APPKEY+timeStamp的加密数据;

sysCode:系统来源编码。

l 具体API请参照《开放接口规范》。

②独立应用用户登记

独立应用调用体系独立应用用户登记接口进行实名登记校验,未实名登记的需跳转到登记页面来登记APP用户id和用户账号。

l 调用接口信息如下:

n  请求地址:

http://IP:PORT/cert/independentAppRegister?accessToken=ACCESS_TOKEN

n  请求报文:

{

              "userId": "1234",

  "loginAccount": "12345678901",

"type": "1"--登记类型(0:接口登记,1:页面登记)
}

n  应答报文:

           {
          "retCode": "000000",
          "retDesc": "成功"
       }

n  具体API请参照《开放接口规范》。

根据返回的registerUrl地址,跳转到体系实名登记页面,如下图:


     


                                                       图 24 PC端登记页面


                                             


                                                            图 25手机端登记页面1

                                             

                                                

                                                            图 26 手机端登记页面2


            II.登录平台空间使用独立应用

            i.  手机端独立应用使用流程

                

                                                    图 27手机端独立应用

            ii.  PC端独立应用使用流程


                                                            图 28 PC端独立应用



iii.  获取平台传递的参数

在平台接入规范中说明了,用户登录平台后访问应用会传递2个参数,下面详细介绍参数的含义:

ticket:平台调用体系对外接口获取的用户会话票据,里面包含了用户的部分信息,使用一次有效

sysCode:来源编码(区域或者机构),平台传递给应用使用

验证用户会话Ticket接口拿到当前用户登录信息和体系id之后,可以进行如下操作:

手机端独立应用:生成二维码图片,用户通过安装好的app扫描生成二维码后,查询本地账号与体系id的绑定关系。未绑定则进行体系id和APP本地账号绑定,成功绑定后调用独立APP关联体系实名用户接口;已绑定则应用根据绑定关系,可获取到登录用户体系id对应的APP账号信息,实现单点登录。

PC端独立应用:用户通过网页启动安装好的pc端应用,查询本地账号与体系id的绑定关系。未绑定则进行体系id和本地账号绑定,成功绑定后调用独立应用关联体系实名用户接口。已绑定则应用根据绑定关系,可获取到登录用户体系id对应的pc端账号信息,实现单点登录。

iV.    接口调用步骤

①获取接口访问令牌

应用调用体系接口的第一步,访问令牌是服务商使用接口的凭证,通过访问令牌服务商可以使用自身权限下的各种接口。

l http://IP:PORT/apigateway/getAccessToken

l Post请求参数:

appId:应用id,系统自动生成APPID和APPKEY;

timeStamp:当前时间戳;

keyInfo:根据Hmac算法APPID+APPKEY+timeStamp的加密数据;

sysCode:系统来源编码。

l 具体API请参照《开放接口规范》。

②验证用户会话Ticket

应用获取了从平台传递过来的用户会话ticket后,可以根据ticket验证是否用户登录的状态和用户部分信息。

l 调用接口信息如下:

n  请求地址:

http://IP:PORT/userSession/validaTicket?accessToken=ACCESS_TOKEN

n  请求报文:

{

  "ticket":"eUg3OTQ1OWVjMjItZDdjYy0xMWU2LTk5YzctODQzYTRiMzI4NWVlMTQ4NDExODQzNDE3NQ=="

}

n  应答报文:

{

  "retCode": "000000",

  "retDesc": "success",

  "data": {

        "userId": "0040032E20184955GHJHK9EACA1501F8F",

    "name": "周力*",

        "gender": "1",

        "dafaultIdentity": "1",

    "orgRelList":[

  {

           "orgCode": "31450069822",

     "orgName": "某某中学",

     "orgIdentity": "1"

  }

]

   }

  }

n  具体API请参照《开放接口规范》。

③独立应用关联体系实名用户接口调用

应用用户和平台账号绑定后,根据会话ticket验证获取到体系用户id,以及app对应账号信息,来调用独立APP关联体系实名用户接口。

l 调用接口信息如下:

n  请求地址:

http://IP:PORT/cert/independentAppValidateUser?accessToken=ACCESS_TOKEN

n  请求报文:

{

  "userId": "1234",

         "loginAccount": "12345678901",

"personId": "12345678901"

}

n  应答报文:

{
  "retCode": "000000",
  "retDesc": "success"
}

n  具体API请参照《开放接口规范》。


3)接口登记方式

        

第三方用户(应用本身的用户)在应用登录后,通过独立应用实名登记接口进行登记,包括手机端和PC端,要求每次登录都需要进行使用登记。以独立应用接入到服务体系的应用需实现应用自身用户和平台空间用户同时使用的应用场景,包括直接登录使用应用和通过空间使用两种使用方式。

I.    直接登录使用应用

用户直接登录使用独立应用时,应用方需调用体系独立应用用户登记接口,便于国家服务体系监管独立应用的使用情况。

i.  流程

    

                            图 29直接登录使用应用



    ii.  接口调用步骤

①获取接口访问令牌

应用调用体系接口的第一步,访问令牌是服务商使用接口的凭证,通过访问令牌服务商可以使用自身权限下的各种接口。

l http://IP:PORT/apigateway/getAccessToken

l Post请求参数:

appId:应用id,系统自动生成APPID和APPKEY;

timeStamp:当前时间戳;

keyInfo:根据Hmac算法APPID+APPKEY+timeStamp的加密数据;

sysCode:系统来源编码。

l 具体API请参照《开放接口规范》。

②独立应用用户登记

独立应用调用体系独立应用用户登记接口来登记APP用户id和用户账号。

l 调用接口信息如下:

n  请求地址:

http://IP:PORT/cert/independentAppRegister?accessToken=ACCESS_TOKEN

n  请求报文:

{

             "userId": "1234",

  "loginAccount": "12345678901",

"type": "0",--登记类型(0:接口登记,1:页面登记)

"orgId": "12345678901"—体系机构Id,应用需要与本地机构Id映射,type=0时为必选参数
}

n  应答报文:

           {
          "retCode": "000000",
          "retDesc": "成功"
       }

n  具体API请参照《开放接口规范》。


II.登录平台空间使用独立应用

实现步骤、流程、接口同页面登记方式,详见上文②页面登记方式。