产品间接口规范说明书.docx
《产品间接口规范说明书.docx》由会员分享，可在线阅读，更多相关《产品间接口规范说明书.docx（15页珍藏版）》请在冰豆网上搜索。
产品间接口规范说明书
1简介
本文档描述了vivo授权接口的使用说明。
1.1缩略语和术语
缩略语/术语
全称
说明
clientid
第三方服务ID
client_id是vivo标识对第三方的唯一性标识，就是在接入前申请的appid做为clientid
clientsecret
第三方服务器密钥
第三方访问vivo的密钥，用于签名，不能在公网中传输，在接入前申请的appkey做为clientsecret
accesstoken
访问令牌
在用户授权许可下，授权服务器下发给客户端的一个授权凭证，可以用accesstoken获取用户授权的信息
refreshtoken
刷新令牌
刷新令牌的作用在于更新访问令牌，访问令牌的有效期一般较短，这样在访问令牌失效时，可以利用刷新令牌去授权服务器换取新的访问令牌，是否需要该令牌是由第三方自行选择
redirecturi
回调地址
回调地址作用主要体现在PC端接入授权：
OAuth2.0是一类基于回调的授权协议，在授权码模式中，整个授权需要分为两步进行，第一步下发授权码，第二步根据第一步拿到的授权码请求授权服务器下发访问令牌。
OAuth在第一步下发授权码时，是将授权码以参数的形式添加到回调地址后面，并以302跳转的形式进行下发
一般回调地址都是根据H5自身的业务配置，如果某个业务仅仅有apk，而没有PC端的授权业务，可以简单配置为该公司的相关主域名
注意：
开发者平台里面“回调地址”需要填写回调域名，而不是具体的回调地址，回调域名必须严格是scheme:
host形式，不能加路径。
https和http是不同scheme，不可混用。
eg：
可用于配置开发者平台。
而不可以配置在开发者平台
接入vivo第三方授权之前，需要提前申请APPID、APPKEY、回调地址（redirectUrl），申请流程详见2.1
2接入前准备
2.1申请APPID和APPKEY
2.1.1快应用接入帐号
Ø联系与您对接的商务（对内直接联系张秋云），说明需要接入vivo帐号的快应用。
Ø提供您的快应用名称，快应用包名，开发者平台帐号，快应用icon，回调地址给到对应商务。
Ø从商务处获取appid与appkey数据。
2.2游戏接入方式
不需要接任何SDK，直接调用API即可：
3必要说明
3.1应该选择哪种授权模式
我们提供了授权码/标准模式、简化模式两种方案供开发者选择。
（1）授权码模式/标准模式（authorizationcode）是功能最完整、流程最严密的授权模式。
它的特点就是通过客户端的后台服务器，与"服务提供商"的认证服务器进行互动。
（2）简化模式（implicitgranttype）不通过第三方应用程序的服务器，直接在浏览器中向认证服务器申请令牌，跳过了"授权码"这个步骤，因此得名。
所有步骤在浏览器中完成，令牌对访问者是可见的，且客户端不需要认证。
这两类模式各有自己的应用场景，在选择上除非您的应用没有服务端，否则我们强烈建议你选择使用授权码模式授权。
相对于简化模式来说，虽然授权码模式多了一次请求，但是在授权码模式下可以基于clientsecret来验证APP的真实性，同时授权码模式会下发刷新令牌，当访问令牌过期时可以通过刷新令牌在后台静默更新访问令牌，而无须再次让用户授权。
4账户授权功能接入
账户SDK提供了标准授权和简化授权两种方式
4.1授权码/标准授权方式
标准授权方式，授权SDK给应用返回授权Code，应用需要将Code传给应用自己的业务服务器，业务服务器再访问账户服务器获以获取AccessToken和RefreshToken
1.标准授权方式流程图如下：
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-urlencoded;charset=utf-8
接口说明
⏹请求消息
⏹协议类型：
HTTPS（POST请求）
⏹数据格式：
Text
⏹服务URL：
⏹消息方向：
第三方服务->账户系统
⏹请求参数：
参数
参数名称
类型
必填
参数说明
基本参数
timestamp
时间戳
long
是
请求的当前时间戳，时间戳和服务器时间戳进行校正过，时间戳是自1970年1月1日（00:
00:
00GMT）以来的毫秒数
nonce
随机字符串
String
是
随机字符串
sign
签名
String
是
签名【附录有关于签名的算法的详细说明】
业务参数
client_id
第三方服务唯一标识
String
是
vivo账户系统用来识别第三服务，由vivo分配给第三方服务
code
授权认证码
String
是
授权认证码
grant_type
授权类型
String
是
固定值:
authorization_code
redirect_uri
授权认证成功后，重定向第三方服务URL
String
否
授权认证成功后，重定向URL需要进行UrlEncoder
scope
授权范围
String
否
scope不填默认为user_baseinfo，表示静默授权的，用户无感知。
多个授权用“|”分隔
⏹示例：
⏹响应消息：
{"expires_in":
3600,"access_token":
"33145fb20aa24bbdd54a8ffeecc63130",
"state":
"200","refresh_token":
"33bada653235"}
返回状态:
状态码
提示信息
"4000"
无效的请求，如签名不通过，请求过期
"4001"
未授权
4.1.3根据AccessToken获取用户授权信息【服务器对接】
根据AccessToken获取用户授权的信息——服务器会验证AccessToken的合法性，当AccessToken合法时，返回的信息包括头像、昵称、用户的唯一标识openid，AccessToken有效期24小时。
接口说明
⏹请求消息
⏹协议类型：
HTTPS（get请求）
⏹数据格式：
Text
⏹服务URL：
⏹消息方向：
第三方服务->账户系统
⏹请求参数：
参数
参数名称
类型
必填
参数说明
基本参数
timestamp
时间戳
long
是
请求的当前时间戳，时间戳和服务器时间戳进行校正过,时间戳是自1970年1月1日（00:
00:
00GMT）以来的毫秒数
nonce
随机字符串
String
是
随机字符串
sign
签名
String
是
签名，签名规则见附录
业务参数
client_id
第三方服务唯一标识
String
是
vivo账户系统用来识别第三服务，由vivo分配给第三方服务，client_id就是申请的APPID
access_token
授权令牌
String
是
授权令牌
scope
授权范围
String
否
scope不填默认为user_baseinfo，表示静默授权的，用户无感知。
多个授权用“|”分隔
⏹示例：
⏹响应消息：
{
"avatar":
"http:
//***/web/images/online/banner_",
"nickname":
"zhangwtest",
"openid":
"29fd78ff8b65eaef",
"state":
"200"
}
返回状态:
状态码
提示信息
"4000"
请求无效
"5001"
Token过期
"5002"
授权不足
"5003"
Token无效
4.1.4根据RefreshToken获取新AccessToken【服务器对接】
AccessToken有效期是24小时，当AccessToken过期后可用RefreshToken获取新的AccessTokent和RefreshToken，原有的AccessTokent和RefreshToken会失效
接口说明
⏹请求消息
⏹协议类型：
HTTPS（POST请求）
⏹数据格式：
Text
⏹服务URL：
⏹消息方向：
第三方服务->账户系统
⏹请求参数：
参数
参数名称
类型
必填
参数说明
基本参数
timestamp
时间戳
long
是
请求的当前时间戳，时间戳和服务器时间戳进行校正过，时间戳是自1970年1月1日（00:
00:
00GMT）以来的毫秒数
nonce
随机字符串
String
是
随机字符串
sign
签名
String
是
签名【附录有关于签名的算法的详细说明】
业务参数
client_id
第三方服务唯一标识
String
是
vivo账户系统用来识别第三服务，由vivo分配给第三方服务
code
授权认证码
String
是
默认先传1
grant_type
授权类型
String
是
固定值:
authorization_code
redirect_uri
授权认证成功后，重定向第三方服务URL
String
是
授权认证成功后，重定向URL需要进行UrlEncoder
scope
授权范围
String
是
scope不填默认为user_baseinfo，表示静默授权的，用户无感知。
多个授权用“|”分隔
refresh_token
刷新accesstoken使用，上一步接口返回
String
是
刷新accesstoken使用，上一步接口返回
⏹示例：
⏹响应消息：
{
"access_token":
"",
"refresh_token":
"zhangwtest",
"expires_in":
3600,
"state":
"200"
}
状态码
提示信息
"4000"
请求无效
"4001"
Token过期
4.2简化授权方式——不推荐
3.简化模式获取AccessToken流程图
简化模式SDK直接返回AccessToken给应用，不需要经过业务服务器【请慎重考虑】。
4.简化模式获取用户信息
代码示例：
stAccessToken（newOauthCallback（）{
@Override
publicvoidonStartLoading（）{
//授权开始，应用可在此处显示loading圈
}
@Override
publicvoidonResult（OauthResultresult）{
}
@Override
publicvoidonEndLoading（）{
//授权结束，应用可在此处关闭loading圈
}
}）;
OauthResult说明：
参数
说明
statusCode
授权的结果：
200：
授权成功
12：
用户取消授权（取消登录时不会有此回调）
13：
授权失败-网络无法连接
14：
授权失败-其他错误
accesstoken;
授权AccessToken
expireIn
AccessToken的有效期，单位是秒
当应用接收回调或者退出当前页面时，需要解注册Listener，方法如下：
isterOauthCallback（）;
总结：
简化授权模式流程简单，适用于没有业务服务器的应用，安全性比较弱
5使用授权登录的解决方案
以下整理的是通用的第三方授权登录解决方案，与vivo账号授权无关，仅供应用参考：
●方案一【授权码模式、简化模式都适用】
思想：
应用建立自己的ID与vivo的openid进行绑定，步骤如下：
（1）应用拿到AccessToken后，调用业务服务器获取用户信息（调用vivo账户服务器）,如果校验通过，则执行步骤2，否则返回失败。
（2）根据vivo的openid去业务数据库查阅,如果没有账户,则生成新的账户并与vivo的openid建立映射关系；如果有账户,就返回已有的账户信息给客户端，应用同时可以生成自己的登录态，以便应用后续进行合法性判别。
优点：
授权成功之后，业务就不再依赖vivo账号。
●方案二【适用于授权码模式】
思想：
假设用户已经获得授权，则下次登录时只需要验证AccessToken是否有效，无效则重新获取授权，有效则无需重新获得授权，步骤如下：
（1）用户向自己的服务器请求登录，登录方式为vivo登录，附带上次登录返回的的AccessToken
（2）应用服务器收到用户的登录请求，向vivo账号服务器发送AccessToken是否有效的验证请求如下：
如果AccessToken有效，服务端将信息返回给客户端，客户端成功登录。
如果AccessToken无效，服务端可尝试利用RefreshToken刷新到新的AccessToken重新验证，验证成功则登录成功，否则登录失败。
注：
RefreshToken拥有较长的有效期（30天），当RefreshToken失效的后，需要用户重新授权。
6附录-服务器签名算法
6.1MD5签名
1、生成待签名的字符串
在请求参数中，除去签名参数（即sign），把其它的参数按照字段的顺序排序，排序完成后再把所有的参数用&符号连接起来，这样就完成了待签名的字符串。
2、签名
目前暂只支持MD5签名。
MD5是一种摘要生成算法，通过在签名原始串后加上第三方的CientSecret（接入前申请的APPKEY）密钥的内容，进行MD5运算，形成的摘要字符串即为签名结果。
第三方可以使用提供的工具类把所有请求所求参数放到Map中生成paraMap，用第三方服务申请的client_id（接入前申请的APPID）对应的client_secret（接入前申请的APPKEY）作为签名密钥，调用PartnerSignUtil的sign方法生成生成签名作为参数放在url后即可！
如client_secret:
4e53b6bf60659bf3c2d1b9
sign=MD5（text+client_secret）=（"client_id=c1ebe4661cdc4bd3ab6977c3561b9dee&code=386cdb374ad63fd05b2a22b&grant_type=authorization_code&nonce=08ad5f076cd9a5879fd741f5×tamp="+"4e53b6bf60659bf3c2d1b9"）
/**
*签名字符串
*@paramparaMap需要签名的参数Map
*@paramkey签名的密钥
*@return签名结果
*/
publicstaticStringsign（MapparaMap,Stringkey）{
StringsaltValue=key;
return（paraMap,saltValue,SIGNATURE）;
}
6.2MD5签名工具
5FAQ
1、接入了SDK，为什么都是H5登录
答：
授权SDK会根据vivo手机内置的账户apk版本决定使用H5登录还是Native登录。
当没有账户apk或者账户apk版本过低时，采用H5登录
升级会员 