1. 授权背景

授权是指插件通过调用淘宝开放平台API获取用户隐私数据（如商品、订单等）时，为保证用户数据的安全与隐私，需要取得的用户授权令牌Access Token。

插件开发者（ISV）可使用如下两种方式获取用户数据：

• 通过QAP的QN.top接口获取用户数据：用此方式，无需关心授权相关问题，QAP中会自动处理去调用API返回数据。

• 通过插件自有服务端获取用户数据：用此方式，就需要关心授权获取及授权更新问题。

授权示例

{
    "access_token": "50008401113yNbaZzmwHqtCVr1d6d8918g8bFvinuXEHIOi0jrXDDWkTxCQGECOxLZ6",
    "expires_in": 600,
    "start": 1502423982571,
    "refresh_token": "50003401a13kQLspddeFy7NVw1e7dd9fcgHdymagtWlEbDqtgKTzQLOa4gv3ZxI48uw",
    "re_expires_in": 15474443,
    "usession_id": "1d9540000475fb30f58b444e5de958be66264ee101fe0d8aee8012867328171",
    "sub_taobao_user_nick": "qn店铺测试账号002:fh",
    "taobao_user_id": "2256639411",
    "sub_taobao_user_id": "2867328171",
    "taobao_user_nick": "qn店铺测试账号002",
    "r1_expires_in": 8843,
    "r2_expires_in": 8843,
    "w1_expires_in": 8843,
    "w2_expires_in": 0
}

2. 授权获取

插件通过自有服务端调用淘宝开放平台api获取用户数据时，需要向QAP获取授权信息。QAP会确保返回的授权信息R1安全级别的授权有效性，安全级别详见淘宝开放平台插件授权介绍。

授权信息有两种方式可以获取

2.1 通过页面参数获取

插件在打开之前，QAP会通过授权功能获取授权信息，然后将授权信息以插件打开URL参数的形式给到插件开发者（ISV），帮助插件实现授权。

该获取方式只针对打开插件的第一个页面有效。

import {Util} from 'nuke';
const getSearchParameter = Util.urlHelper.getSearchParameter;
const search = Util.Location.search;
console.log('authString==>',getSearchParameter(search,'authString'));

2.2 通过QN.sso接口获取

插件在打开之后，可以通过QN.sso获取QAP中的授权信息。

该获取方式在所有页面中都能调用。

QN.sso({
}).then(result => {
    console.log(result.data);
}, error => {
    console.log(error);
});

3. 授权更新

当插件自有服务端使用QAP提供的授权信息向淘宝开放平台请求用户数据出错时，如果错误跟授权信息相关，需要请求QAP更新用户的授权信息。

授权信息在下列两种情况下需要更新：

3.1 授权信息无效

当QAP提供的授权信息出现异常或者在调用链路中出错，需要重新刷新授权

更新示例

QN.sso({
	query: {
        forceRefresh: true //强制刷新授权，更新r1，r2，w1，w2授权有效期
    },
}).then(result => {
    console.log(result.data);
}, error => {
    console.log(error);
});

3.2 安全级别不足

为了更加灵活的对淘宝开放平台开放的数据进行安全管控，降低用户数据泄露或者被恶意修改的风险，淘宝开放平台推出了安全等级的概念。
淘宝开放平台对API（或者API字段）及 应用分别打了r1、r2、w1、w2 和 0,1,2,3四种安全级别的标记。与 r1、r2、w1、w2对应的是在access token（session key）颁发时增加了4个过期时间。

因QAP无法判断给出的授权信息会被使用于请求哪个安全级别的API，插件获取到的授权信息只确保了access_token与r1的有效性。当淘宝开放平台服务返回如下错误码时，需要插件调用QN.sso刷新授权。

父错误码 code

子错误码 sub_code

更新示例

QN.sso({
	query: {
        forceRefresh: true //强制刷新授权，更新r1，r2，w1，w2授权有效期
    },
}).then(result => {
    console.log(result.data);
}, error => {
    console.log(error);
});

4. 变更说明

• 从5.9.8开始获取授权新提供forceReAuth选项，当插件订购过期、用户取消授权、权限受限等时，强制弹出授权页面引导用户重新授权。
• Android端从6.0.1版本开始从授权信息中去除r1_valid、r2_valid、w1_valid、w2_valid字段，保持与iOS端一直
• Android端从6.0.1版本开始将授权信息中r1_expire_in、r2_expires_in、w1_expires_in、w2_expires_in数据类型从string修改为number
• iOS端从6.0.1将从授权信息中start单位从秒变更为毫秒。

5. 注意事项：

5.1 授权信息的加签校验

通过页面参数获取授权信息时，可对参数进行加签校验

• 把URL#号之后除sign外所有key和value按照参数的首字母顺序排列，以 key1+value+key2+value….的方式拼接在一起，再在其前后加上的AppSecret，然后转成utf-8编码，接着进行md5加密，最后全部转大写。

• md5(utf-8:AppSecret+k1+v1+k2+v2+…+kn+vn + AppSecret) 与 URL中sign参数进行比对，相同则校验通过。

  5.2 OAuth授权的使用说明

  QAP插件禁止再使用OAuth对用户进行授权，原因如下

• 千牛授权的refresh_token可以通过taobao.top.auth.token.refresh接口刷新获取新的token。每次刷新后原来refresh_token作废，都要更新成最新返回的refresh_token用于下次刷新。

• QAP提供了本地离线包加载页面的机制，插件入口页面如果是离线包中的地址，无法再拼接授权url进行授权。
• 拼接授权url进行授权会跳转到用户登录页面，与QAP整体的用户体验不一致。

6. 附录：

• 淘宝开放平台用户授权介绍
• 淘宝开放平台API类目

FAQ