JS_SDK使用说明

特别说明：
JS SDK 获取地址：//connect.qq.com/qc_jssdk.js

为了让应用更快接入，腾讯提供了JS SDK。 JS SDK是现有最简单的接入QQ互联的方式。
JS SDK基于QQ互联OAuth2.0协议的client-side模式，封装了登录流程与API列表中的所有OpenAPI调用方法。开发者不需了解协议，只需要前台交互，以及将相关的参数修改成自身对应的参数即可使用。同时，QQ互联又提供了可供第三方高级需求进行自行配置的可选参数与相关函数，使开发者可以根据自身需求灵活使用。
本JS SDK不需要配置任何跨域文件，支持在绝大多数主流浏览器下使用；对于少数老版本的浏览器，需要浏览器支持flash插件来完成跨域通信的问题。

1. 实现QQ登录功能

开发者只需要按以下四个步骤粘贴代码到网页，即可实现QQ登录功能，过程非常简单快速。
Demo地址：https://github.com/734407088/qq_connenct_demo

1.1 引用JS SDK的JavaScript文件

1. 首先需要申请接入QQ登录，并成功获取到appid和appkey。
2. 在html页面适当的位置引入JS脚本包（将下面代码中的“APPID”替换为申请接入QQ登录时获得的appid；"REDIRECTURI"替换为申请接入QQ登录时输入的回调地址）：

<script type="text/javascript"  charset="utf-8"
    src="http://connect.qq.com/qc_jssdk.js"
    data-appid="APPID"
    data-redirecturi="REDIRECTURI"
></script>

注意：回调地址必须以http或https开头。

1.2. 放置QQ登录按钮

在html页面需要插入QQ登录按钮的位置，粘贴如下代码：

<span id="qqLoginBtn"></span>
<script type="text/javascript">
    QC.Login({
       btnId:"qqLoginBtn"	//插入按钮的节点id
});
</script>

上述代码中放置了一个html元素节点，并给该节点指定全页面唯一的id，例如上面例子中的<span id="qqLoginBtn"></span>。开发者也可将其改成自定义的元素id。
上述步骤正确执行后，页面粘贴上述代码处会出现如下按钮：

点击该按钮，即可发起登录请求。
若需要对登录按钮进行设置，请自定义登录按钮。将修改后的代码粘贴到页面中放置登录按钮处。
JS SDK封装了获取Access Token以及OpenID的方法，因此开发者不需要再开发代码进行获取，直接调用QQ登录OpenAPI即可。

使用QC.Login(options, loginFun, logoutFun, outCallBackFun)进行初始化

options参数说明：

参数名	参数值	描述
btnId	String 可选	插入按钮元素的Id
scope	String 可选，默认all	用户需要确认的scope授权项
size	String 可选，默认B_S	按钮尺寸 [A_XL, A_L, A_M, A_S, B_M, B_S, C_S]

1.3. 回调地址页面

该步骤的作用是回调地址将获取到的Access Token和OpenID返回给调用页面。
在回调地址页面，即1.1节中回调地址“REDIRECTURI”指定的页面，粘贴如下代码：

<script type="text/javascript"
src="//connect.qq.com/qc_jssdk.js" charset="utf-8" data-callback="true"></script>

注意：如果回调地址页与加入QQ登录按钮是同一个页面，则只需要引用一次脚本文件。

1.4. 调用QQ登录OpenAPI

（1）调用方式说明
QQ互联在JS SDK中封装了所有的OpenAPI接口，开发者只需要传递OpenAPI名称，以及OpenAPI需要的相关参数，就可以调用OpenAPI。
调用OpenAPI时，请统一遵循下述调用方式：

QC.api(api, paras, fmt, method)

函数说明：
用JS SDK协助调用OpenAPI。
参数说明：

参数名称	是否必须	描述
api	必须	指定要调用的OpenAPI名称。例如：调用add_t时，OpenAPI名称为“add_t”。各OpenAPI的名称具体请参见API列表。
paras	必须	指定要调用的OpenAPI对应的参数。各参数使用JSON的键值对格式列出。 OpenAPI对应的参数具体请参见API列表中各OpenAPI的参数说明。注意：此处参数不需要自行传递access_token与openid
fmt	可选	指定OpenAPI的返回格式，可用值为“json”或“xml”。默认为“json”。注意：json、xml为小写，否则将不识别。
method	可选	指定OpenAPI调用请求的发起方式，可用值为“GET”或“POST”。根据配置，默认发送数据为“POST”，获取数据为“GET”。

返回值说明：
每个OpenAPI调用时均指定了一个Request对象，开发者可根据OpenAPI请求完成情况指定不同的处理函数。
每次QC.api调用的异步响应都会返回一个Response对象，用于接收OpenAPI的返回值，包括返回格式、返回数据、OpenAPI请求错误码等。

2. JS SDK的其他公开方法

方法名	参数	返回	描述
QC.Login.signOut	无	无	登出
QC.Login.check	无	Boolean	检查是否已经登录
QC.Login.getMe	Function	无	回调函数 function(openId, accessToken) openId：用户身份的唯一标识。建议保存在本地，以便用户下次登录时可对应到其之前的身份信息，不需要重新授权。 accessToken：表示当前用户在此网站/应用的登录状态与授权信息，建议保存在本地。注意： getMe方法只能在用户登录授权后调用，建议总是在使用check方法并返回true的条件下，调用getMe方法
QC.Login.showPopup	Object	无	直接打开窗口，参数 { appId:"", redirectURI:"" }

2.1. 直接打开QQ登录弹窗

QC.Login.showPopup(oOpts)

参数说明：
oOpts：需要指定appId，回调地址redirect_URI。
参数示例如下：

oOpts：{
      appId:"222222",
      redirectURI:"http://yousite.com/qc_back.html"
}

返回值说明：
返回浏览器弹窗对象。
函数使用示例：

QC.Login.showPopup({
   appId:"222222",
   redirectURI:"http://yousite.com/qc_back.html"
});

注意：

oOpts参数不需必传，不传此参数时，登录成功后会跳回登录按钮所在页面。
如果已使用QC.Login方法，则不需再使用此方法。

2.2. 注销当前登录用户

QC.Login.signOut()

2.3. 检测当前登录状态

QC.Login.check()

返回值说明：
true：说明登录成功。
false：说明登录失败。

2.4. 获取当前登录用户的Access Token以及OpenID

QC.Login.getMe(function(openId, accessToken){})

参数说明：
这里的参数为回调函数，通过回调函数获取openId和accessToken。
openId：用户身份的唯一标识。建议保存在本地，以便用户下次登录时可对应到其之前的身份信息，不需要重新授权。
accessToken：表示当前用户在此网站/应用的登录状态与授权信息，建议保存在本地。
注意：
getMe方法只能在用户登录授权后调用，建议总是在使用check方法并返回true的条件下，调用getMe方法。

3. 自定义登录按钮

开发者可以根据自己的需要，自定义登录按钮，示例如下：

<span id="qqLoginBtn"></span>
<script type="text/javascript">
   //调用QC.Login方法，指定btnId参数将按钮绑定在容器节点中
   QC.Login({
       //btnId：插入按钮的节点id，必选
       btnId:"qqLoginBtn",
       //用户需要确认的scope授权项，可选，默认all
       scope:"all",
       //按钮尺寸，可用值[A_XL| A_L| A_M| A_S|  B_M| B_S| C_S]，可选，默认B_S
       size: "A_XL"
   }, function(reqData, opts){//登录成功
       //根据返回数据，更换按钮显示状态方法
       var dom = document.getElementById(opts['btnId']),
       _logoutTemplate=[
            //头像
            '<span><img src="{figureurl}" class="{size_key}"/></span>',
            //昵称
            '<span>{nickname}</span>',
            //退出
            '<span><a href="javascript:QC.Login.signOut();">退出</a></span>'
       ].join("");
       dom && (dom.innerHTML = QC.String.format(_logoutTemplate, {
           nickname : QC.String.escHTML(reqData.nickname), //做xss过滤
           figureurl : reqData.figureurl
       }));
   }, function(opts){//注销成功
         alert('QQ登录 注销成功');
   }
);
</script>

开发者也可以使用下列函数作为登录成功的回调接收函数：
① 登录成功的回调函数，登录成功后被调用：

cbLoginFun(oInfo, oOpts)

参数说明：
oInfo：当前登录用户的基本信息，即OpenAPI中get_user_info返回的数据。
参数示例如下：

oInfo：{
    "ret":0,
    "msg":"",
    "nickname":"遲來の垨堠",
    "figureurl":"http://qzapp.qlogo.cn/qzapp/100229030/ECCC463F76A2E3C1D9217BBC30418164/30",
    "figureurl_1":"http://qzapp.qlogo.cn/qzapp/100229030/ECCC463F76A2E3C1D9217BBC30418164/50",
    "figureurl_2":"http://qzapp.qlogo.cn/qzapp/100229030/ECCC463F76A2E3C1D9217BBC30418164/100",
    "gender":"男",
    "vip":"1",
    "level":"7"
}

oOpts：回传初始化参数，多个按钮时可用来区分来源，用来区分一个页面多个登录按钮的情况。
参数示例如下：

oOpts：{
   btnId:"qqLoginBtn"
}

回调函数使用示例如下：

var cbLoginFun = function(oInfo, oOpts){
    alert(oInfo.nickname); // 昵称
    alert(oOpts.btnId);    // 点击登录的按钮Id
};
QC.Login({btnId:"qqLoginBtn"}, cbLoginFun);

② 注销成功的回调函数，注销后被调用：

var cbLogoutFun(){
    alert("注销成功!");
};
QC.Login({btnId:"qqLoginBtn"}, cbLoginFun, cbLogoutFun);

4. Request与Response内置对象说明

4.1 Request

JS SDK在初始化时会根据浏览器环境创建不同的请求代理，QC.api的每次调用都是一个Request对象。

Request对象的公开方法如下：
success(resp): 请求完成并且返回码为0的回调。
error(resp): 请求完成并且返回码不为0的回调。
complete(resp): 请求完成后的回调。

调用时序为success/error -> complete，每个方法都可以调用多次，每次调用返回Request本身，支持链式调用。
resp参数为回调函数，回调函数参数为Response对象。

4.2. Response

Response为Request对象绑定的回调函数的返回参数，每次QC.api调用的异步响应都会返回一个Response对象，该对象在Request对象的success/error -> complete调用流程中传递。

Response的公开方法如下：
stringifyData：返回该Response对象包含的数据体的文本串。

Response的公开属性如下：
status：响应状态，-1：代表未知；404：响应错误；200：响应成功。
fmt：响应数据格式，json/xml。
code/ret：响应返回码，0为成功，其他为失败。
data：响应数据实体，json对象/xml对象。
seq：响应序号，从1000开始编号。

OAuth2.0开发指引

OAuth2.0升级指引