产品间接口规范说明书.docx

1、产品间接口规范说明书1 简介本文档描述了vivo授权接口的使用说明。1.1 缩略语和术语缩略语/术语全称说明 clientid 第三方服务IDclient_id是vivo标识对第三方的唯一性标识，就是在接入前申请的appid做为clientid clientsecret 第三方服务器密钥第三方访问vivo的密钥，用于签名，不能在公网中传输，在接入前申请的appkey做为clientsecret accesstoken 访问令牌在用户授权许可下，授权服务器下发给客户端的一个授权凭证，可以用access token获取用户授权的信息 refreshtoken 刷新令牌刷新令牌的作用在于更新访问令牌

2、，访问令牌的有效期一般较短，这样在访问令牌失效时，可以利用刷新令牌去授权服务器换取新的访问令牌，是否需要该令牌是由第三方自行选择 redirecturi 回调地址回调地址作用主要体现在PC端接入授权：OAuth2.0 是一类基于回调的授权协议，在授权码模式中，整个授权需要分为两步进行，第一步下发授权码，第二步根据第一步拿到的授权码请求授权服务器下发访问令牌。OAuth 在第一步下发授权码时，是将授权码以参数的形式添加到回调地址后面，并以 302 跳转的形式进行下发一般回调地址都是根据H5自身的业务配置，如果某个业务仅仅有apk，而没有PC端的授权业务，可以简单配置为该公司的相关主域名注意：开发

3、者平台里面“回调地址”需要填写回调域名，而不是具体的回调地址，回调域名必须严格是scheme:host形式，不能加路径。https和http是不同scheme，不可混用。eg：可用于配置开发者平台。而不可以配置在开发者平台接入vivo第三方授权之前，需要提前申请APPID、APPKEY、回调地址（redirectUrl），申请流程详见2.12 接入前准备2.1 申请APPID和APPKEY2.1.1 快应用接入帐号联系与您对接的商务（对内直接联系张秋云），说明需要接入vivo帐号的快应用。提供您的快应用名称，快应用包名，开发者平台帐号，快应用icon，回调地址给到对应商务。从商务处获取appi

4、d与appkey数据。2.2 游戏接入方式不需要接任何SDK，直接调用API即可：3 必要说明3.1 应该选择哪种授权模式我们提供了授权码/标准模式、简化模式两种方案供开发者选择。（1）授权码模式/标准模式（authorization code）是功能最完整、流程最严密的授权模式。它的特点就是通过客户端的后台服务器，与服务提供商的认证服务器进行互动。（2）简化模式（implicit grant type）不通过第三方应用程序的服务器，直接在浏览器中向认证服务器申请令牌，跳过了授权码这个步骤，因此得名。所有步骤在浏览器中完成，令牌对访问者是可见的，且客户端不需要认证。这两类模式各有自己的应用场景

5、，在选择上除非您的应用没有服务端，否则我们强烈建议你选择使用授权码模式授权。相对于简化模式来说，虽然授权码模式多了一次请求，但是在授权码模式下可以基于 clientsecret 来验证 APP 的真实性，同时授权码模式会下发刷新令牌，当访问令牌过期时可以通过刷新令牌在后台静默更新访问令牌，而无须再次让用户授权。4 账户授权功能接入账户SDK提供了标准授权和简化授权两种方式4.1 授权码/标准授权方式标准授权方式，授权SDK给应用返回授权Code，应用需要将Code传给应用自己的业务服务器，业务服务器再访问账户服务器获以获取AccessToken和RefreshToken1.标准授权方式流程图如

6、下：2.标准模式下用户信息获取流程图：4.1.1 客户端调用SDK获取授权码Code【Client对接】小游戏官方API文档：4.1.2 应用服务器根据code获取AccessToken和RefreshToken【服务器对接】用户在授权页同意授权后，客户端会生成一个授权认证码code，应用需要将code传递给应用自己的服务器，由服务器获取AccessToken和RefreshToken，并将AccessToken返回给客户端。备注：以下接口都是post请求，要设置成表单形式提交，参数放在url后面即可请求头设置：Content-Type:application/x-www-form-urlen

7、coded;charset=utf-8接口说明请求消息协议类型：HTTPS（POST请求）数据格式：Text服务URL：消息方向：第三方服务-账户系统请求参数：参数参数名称类型必填参数说明基本参数timestamp时间戳long是请求的当前时间戳，时间戳和服务器时间戳进行校正过，时间戳是自 1970 年 1 月 1 日（00:00:00 GMT）以来的毫秒数nonce随机字符串String是随机字符串sign签名String是签名【附录有关于签名的算法的详细说明】业务参数client_id第三方服务唯一标识 String是vivo账户系统用来识别第三服务，由vivo分配给第三方服务code授权

8、认证码String是授权认证码grant_type授权类型String是固定值:authorization_coderedirect_uri授权认证成功后，重定向第三方服务URLString否授权认证成功后，重定向URL需要进行UrlEncoderscope授权范围String否scope不填默认为user_baseinfo，表示静默授权的，用户无感知。多个授权用“|”分隔示例：响应消息：expires_in:3600,access_token:33145fb20aa24bbdd54a8ffeecc63130,state:200,refresh_token:33bada653235返回状态:

9、状态码提示信息4000无效的请求，如签名不通过，请求过期4001未授权4.1.3 根据AccessToken获取用户授权信息【服务器对接】根据AccessToken获取用户授权的信息服务器会验证AccessToken的合法性，当AccessToken合法时，返回的信息包括头像、昵称、用户的唯一标识openid， AccessToken有效期24小时。接口说明请求消息协议类型：HTTPS（get请求）数据格式：Text服务URL：消息方向：第三方服务-账户系统请求参数：参数参数名称类型必填参数说明基本参数timestamp时间戳long是请求的当前时间戳，时间戳和服务器时间戳进行校正过, 时间戳

10、是自 1970 年 1 月 1 日（00:00:00 GMT）以来的毫秒数nonce随机字符串String是随机字符串sign签名String是签名，签名规则见附录业务参数client_id第三方服务唯一标识 String是vivo账户系统用来识别第三服务，由vivo分配给第三方服务，client_id就是申请的 APPIDaccess_token授权令牌String是授权令牌scope授权范围String否scope不填默认为user_baseinfo，表示静默授权的，用户无感知。多个授权用“|”分隔示例：响应消息： avatar:http:/*/web/images/online/bann

11、er_, nickname: zhangwtest, openid: 29fd78ff8b65eaef, state: 200返回状态: 状态码提示信息4000 请求无效5001Token 过期5002授权不足5003 Token无效4.1.4 根据RefreshToken获取新AccessToken 【服务器对接】AccessToken有效期是24小时，当AccessToken过期后可用RefreshToken获取新的AccessTokent 和RefreshToken，原有的AccessTokent 和RefreshToken会失效 接口说明请求消息协议类型：HTTPS（POST请求）数据

12、格式：Text服务URL：消息方向：第三方服务-账户系统请求参数：参数参数名称类型必填参数说明基本参数timestamp时间戳long是请求的当前时间戳，时间戳和服务器时间戳进行校正过，时间戳是自 1970 年 1 月 1 日（00:00:00 GMT）以来的毫秒数nonce随机字符串String是随机字符串sign签名String是签名【附录有关于签名的算法的详细说明】业务参数client_id第三方服务唯一标识 String是vivo账户系统用来识别第三服务，由vivo分配给第三方服务code授权认证码String是默认先传1grant_type授权类型String是固定值:authori

13、zation_coderedirect_uri授权认证成功后，重定向第三方服务URLString是授权认证成功后，重定向URL需要进行UrlEncoderscope授权范围String是scope不填默认为user_baseinfo，表示静默授权的，用户无感知。多个授权用“|”分隔refresh_token刷新accesstoken使用，上一步接口返回String是刷新accesstoken使用，上一步接口返回示例：响应消息： access_token: , refresh_token: zhangwtest, expires_in:3600, state: 200状态码提示信息4000请求无

14、效4001Token 过期4.2 简化授权方式不推荐3.简化模式获取AccessToken流程图简化模式SDK直接返回AccessToken给应用，不需要经过业务服务器【请慎重考虑】。4.简化模式获取用户信息代码示例：stAccessToken(new OauthCallback() Override public void onStartLoading() / 授权开始，应用可在此处显示loading圈 Override public void onResult(OauthResult result) Override public void onEndLoading() / 授权结束，应用

15、可在此处关闭loading圈 );OauthResult说明：参数说明statusCode授权的结果：200：授权成功12：用户取消授权（取消登录时不会有此回调）13：授权失败-网络无法连接14：授权失败-其他错误accesstoken;授权AccessTokenexpireInAccessToken的有效期，单位是秒当应用接收回调或者退出当前页面时，需要解注册Listener，方法如下：isterOauthCallback();总结：简化授权模式流程简单，适用于没有业务服务器的应用，安全性比较弱 5使用授权登录的解决方案以下整理的是通用的第三方授权登录解决方案，与vivo账号授权无关，仅供应

16、用参考：方案一【授权码模式、简化模式都适用】思想：应用建立自己的ID与vivo的openid进行绑定，步骤如下：（1）应用拿到AccessToken后，调用业务服务器获取用户信息（调用vivo账户服务器）,如果校验通过，则执行步骤2，否则返回失败。（2）根据vivo的openid去业务数据库查阅,如果没有账户,则生成新的账户并与vivo的openid建立映射关系；如果有账户,就返回已有的账户信息给客户端，应用同时可以生成自己的登录态，以便应用后续进行合法性判别。优点：授权成功之后，业务就不再依赖vivo账号。方案二【适用于授权码模式】思想：假设用户已经获得授权，则下次登录时只需要验证Acces

17、sToken是否有效，无效则重新获取授权，有效则无需重新获得授权，步骤如下：（1）用户向自己的服务器请求登录，登录方式为vivo登录，附带上次登录返回的的AccessToken（2）应用服务器收到用户的登录请求，向vivo账号服务器发送AccessToken是否有效的验证请求如下：如果AccessToken有效，服务端将信息返回给客户端，客户端成功登录。如果AccessToken无效，服务端可尝试利用RefreshToken刷新到新的AccessToken重新验证，验证成功则登录成功，否则登录失败。注：RefreshToken拥有较长的有效期（30天），当RefreshToken失效的后，需要

18、用户重新授权。6附录-服务器签名算法6.1MD5签名1、生成待签名的字符串在请求参数中，除去签名参数（即sign），把其它的参数按照字段的顺序排序，排序完成后再把所有的参数用&符号连接起来，这样就完成了待签名的字符串。2、签名目前暂只支持MD5签名。MD5 是一种摘要生成算法，通过在签名原始串后加上第三方的CientSecret(接入前申请的APPKEY)密钥的内容，进行MD5运算，形成的摘要字符串即为签名结果。第三方可以使用提供的工具类把所有请求所求参数放到Map中生成paraMap，用第三方服务申请的client_id(接入前申请的APPID)对应的client_secret(接入前申请的

19、APPKEY)作为签名密钥，调用PartnerSignUtil的sign方法生成生成签名作为参数放在url后即可！如client_secret: 4e53b6bf60659bf3c2d1b9sign=MD5(text+client_secret)=(client_id=c1ebe4661cdc4bd3ab6977c3561b9dee&code=386cdb374ad63fd05b2a22b&grant_type=authorization_code&nonce=08ad5f076cd9a5879fd741f5×tamp= + 4e53b6bf60659bf3c2d1b9) /* * 签名字符串 * param paraMap 需要签名的参数Map * param key 签名的密钥 * return 签名结果 */ public static String sign(Map paraMap, String key) String saltValue = key; return (paraMap, saltValue, SIGNATURE); 6.2MD5签名工具5 FAQ1、接入了SDK，为什么都是H5登录答：授权SDK会根据vivo手机内置的账户apk版本决定使用H5登录还是Native登录。当没有账户apk或者账户apk版本过低时，采用H5登录