产品间接口规范说明书文档格式.docx
- 文档编号:20523709
- 上传时间:2023-01-23
- 格式:DOCX
- 页数:15
- 大小:126.72KB
产品间接口规范说明书文档格式.docx
《产品间接口规范说明书文档格式.docx》由会员分享,可在线阅读,更多相关《产品间接口规范说明书文档格式.docx(15页珍藏版)》请在冰豆网上搜索。
开发者平台里面“回调地址”需要填写回调域名,而不是具体的回调地址,回调域名必须严格是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
签名
签名【附录有关于签名的算法的详细说明】
业务参数
client_id
第三方服务唯一标识
vivo账户系统用来识别第三服务,由vivo分配给第三方服务
code
授权认证码
grant_type
授权类型
固定值:
authorization_code
redirect_uri
授权认证成功后,重定向第三方服务URL
否
授权认证成功后,重定向URL需要进行UrlEncoder
scope
授权范围
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请求)
请求的当前时间戳,时间戳和服务器时间戳进行校正过,时间戳是自1970年1月1日(00:
签名,签名规则见附录
vivo账户系统用来识别第三服务,由vivo分配给第三方服务,client_id就是申请的APPID
access_token
授权令牌
{
"
avatar"
http:
//***/web/images/online/banner_"
nickname"
zhangwtest"
openid"
29fd78ff8b65eaef"
请求无效
5001"
Token过期
5002"
授权不足
5003"
Token无效
4.1.4根据RefreshToken获取新AccessToken【服务器对接】
AccessToken有效期是24小时,当AccessToken过期后可用RefreshToken获取新的AccessTokent和RefreshToken,原有的AccessTokent和RefreshToken会失效
默认先传1
refresh_token
刷新accesstoken使用,上一步接口返回
3600,
4.2简化授权方式——不推荐
3.简化模式获取AccessToken流程图
简化模式SDK直接返回AccessToken给应用,不需要经过业务服务器【请慎重考虑】。
4.简化模式获取用户信息
代码示例:
stAccessToken(newOauthCallback(){
@Override
publicvoidonStartLoading(){
//授权开始,应用可在此处显示loading圈
}
publicvoidonResult(OauthResultresult){
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&
timestamp="
+"
4e53b6bf60659bf3c2d1b9"
)
/**
*签名字符串
*@paramparaMap需要签名的参数Map
*@paramkey签名的密钥
*@return签名结果
*/
publicstaticStringsign(Map<
String,String>
paraMap,Stringkey){
StringsaltValue=key;
return(paraMap,saltValue,SIGNATURE);
6.2MD5签名工具
5FAQ
1、接入了SDK,为什么都是H5登录
答:
授权SDK会根据vivo手机内置的账户apk版本决定使用H5登录还是Native登录。
当没有账户apk或者账户apk版本过低时,采用H5登录
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 产品 间接 规范 说明书