# 移动端小程序获取用户身份态
上架到腾讯微卡的小程序应用拥有多个入口，分别是从服务大厅扫码进入、从电子卡卡面进入以及直接进入小程序。为了打通小程序应用与腾讯微卡的身份态，腾讯微卡提供了接口以及小程序插件。其中插件中包含两个组件，分别是选择学校/企业组件和关联腾讯微卡身份态组件。
在用户首次进入小程序时，应该主动调用小程序插件中的选择学校/企业组件，小程序应该记住用户选择的学校/企业。选择完学校/企业之后小程序调用腾讯微卡提供的接口，通过学校/企业代码以及用户在小程序中的Openid，换取用户在腾讯微卡的身份。如果接口返回找不到用户，小程序需要调用小程序插件中的关联腾讯微卡身份态组件，关联用户在小程序以及腾讯微卡中的身份体系，后续调用接口就能获取用户在腾讯微卡的身份。
# 引入腾讯微卡小程序插件
# 申请插件
小程序开发者可以在"小程序管理后台-设置-第三方服务-插件管理"中查找wx1549b963bbae9931（腾讯微卡应用登陆）插件，并进行申请。在发起申请24小时内，腾讯微卡会根据应用的资质进行审核。
# 引入插件
- 在app.json中声明需要使用的插件
{
"plugins": {
"myPlugin": {
"version": "3.0.6",
"provider": "wx1549b963bbae9931"
}
}
}
plugins字段可以定义多个插件声明，myPlugin字段由开发者自行定义，无需与腾讯微卡保持一致，需指明腾讯微卡身份态插件的version（当前版本号：3.0.6）和provider（插件提供方：wx1549b963bbae9931）
- 在使用的页面的json文件（如index.json）中引用自定义组件
{
"usingComponents": {
"login": "plugin://myPlugin/login",
"chooseSchool": "plugin://myPlugin/chooseSchool"
}
}
usingCompoents表示需要使用插件，"login"表示在页面中使用登录组件的标签，"plugin://myPlugin/login"表示引用的myPlugin插件的登录组件，"chooseSchool"表示在页面中使用选择学校/企业组件的标签，"plugin://myPlugin/chooseSchool"表示引用myPlugin插件中的选择学校/企业组件
# 通过腾讯微卡小程序插件选择学校/企业
若小程序提供给多给学校/企业使用，在用户首次进行入小程序时，小程序应该主动拉起小程序插件中的选择学校/企业组件，在用户选择完学校/企业后，应当记录用户的选择，避免让用户重复选择
# 使用组件
<chooseSchool
wx:if="{{showParmars}}"
appKey="{{appKey}}"
bindschoolChooseGetInfo="callback"
bindschoolChooseCancel="callback"
bindschoolChooseErrofInfo="callback"
/>
| 参数 | type | 必填 | 说明 |
|---|---|---|---|
| appKey | String | 是 | 应用AppKey |
| bindschoolChooseGetInfo | fun(e) | 是 | 选择成功回调，结果e.detail |
| bindschoolChooseCancel | fun(e) | 是 | 点击取消按钮回调 |
| bindschoolChooseErrofInfo | fun(e) | 否 | 网络请求错误 |
# 回调事件
应用调起小程序插件的选择学校/企业组件，用户进行选择学校/企业或者取消操作后，会触发对应事件，交由小程序端的事件处理函数来进行处理，处理完成后应当主动隐藏选择学校/企业组件
//成功回调 (bindschoolChooseGetInfo)
callback: function(e) {
var detail = e.detail;
var schoolCode = detail.schoolCode;
var schoolName = detail.schoolName;
}
| 参数 | 说明 |
|---|---|
| e.detail.schoolCode | 学校/企业代号 |
| e.detail.schoolName | 学校/企业名称 |
# 通过用户在小程序中的openid获取腾讯微卡身份态
# 字段申请地址：
发送需要申请的字段到johanzheng@tencent.com进行申请(邮件同时也抄送至hongfuhuang@tencent.com，ronniewan@tencent.com，marshalyang@tencent.com)，申请时需要注明应用APPKEY、应用名称、及应用使用场景。默认会给电子卡号，姓名，腾讯微卡用户id，身份类型字段
# 请求方法：
POST(application/json)
# 请求地址：
https://weixiao.qq.com/apps/wxmnp/plugin/student-before-plugin
# 参数说明：
{
"openid": "用户在小程序中的openid",
"school_code": "学校/企业代码",
"app_key": "应用分配的app_key",
"timestamp":"当前unix时间戳（秒)",
"nonce": "随机字符串",
"signature": "签名"
}
| 参数 | 必填 | 说明 |
|---|---|---|
| openid | 是 | 用户在小程序中的openid |
| school_code | 是 | 学校/企业代码 |
| app_key | 是 | 应用app_key |
| timestamp | 是 | 当前unix时间戳（秒) |
| nonce | 是 | 随机字符串 |
| signature | 是 | 签名 |
# 响应说明：
{
"code": 0,
"message": "OK",
"student": {
"card_number": "1604030126", // 电子卡号
"name": "evan1", // 姓名
"identity_type": "1", // 身份类型，1为其他，2为学生，3为教职工，4为校友
"grade": "2016", // 年级（需申请）
"college": "人居环境工程学院", // 学院（需申请）
"profession": " 工程造价", // 专业（需申请）
"class": "1班", // 班级（需申请）
"identity_title": "经理/总监/部长/本科生...", // 身份职称（需申请）
"gender": 1, // 性别（需申请）
"organization": [
2,
222,
496
], // 组织架构（需申请）
"campus": "东校区", // 校区（需申请）
"dorm_number": "至善园", // 宿舍号（需申请）
"physical_chip_number": "", // 物理芯片号（需申请）
"physical_card_number": "", // 物理卡号（需申请）
"nation": "汉族", // 民族（需申请）
"birthday": "20020319", // 生日（需申请）
"origin_place": "深圳市", // 生源地（需申请）
"graduated_school": "小碧中学", // 毕业学校（需申请）
"address": "广东省深圳市XXX", // 家庭住址（需申请）
"contact_person": "", // 联系人（需申请）
"contact_phone": "", // 联系人手机号（需申请）
"email": "xxxxx@qq.com", // 邮箱（需申请）
"id_card": "440XXXXXXXXXXXXXXX", // 身份证（需申请）
"telephone": "137XXXXXXXX", // 手机号（需申请）
"expire_at": "2019-12-31 12:00:00", // 有效期结束时间（需申请）
"start_at":"2019-12-31 11:50:00" // 有效期开始时间（需申请）
}
}
| 参数 | 说明 |
|---|---|
| code | 状态码（0：成功找到该成员，7002：未找到该成员） |
| message | 状态信息 |
| student | 用户信息 |
| card_number | 电子卡号 |
| name | 姓名 |
| identity_type | 身份类型，1为其他，2为学生，3为教职工，4为校友 |
| grade | 年级（需申请） |
| college | 学院（需申请） |
| profession | 专业（需申请） |
| class | 班级（需申请） |
| identity_title | 身份职称（需申请） |
| gender | 性别（需申请） |
| organization | 组织架构（需申请） |
| campus | 校区（需申请） |
| dorm_number | 宿舍号（需申请） |
| physical_chip_number | 物理芯片号（需申请） |
| physical_card_number | 物理卡号（需申请） |
| nation | 民族（需申请） |
| birthday | 生日（需申请） |
| origin_place | 生源地（需申请） |
| graduated_school | 毕业学校（需申请） |
| address | 家庭住址（需申请） |
| contact_person | 联系人（需申请） |
| contact_phone | 联系人手机号（需申请） |
| 邮箱（需申请） | |
| id_card | 身份证（需申请） |
| telephone | 手机号（需申请） |
| expire_at | 有效期（需申请） |
| qq号（需申请） |
# 通过腾讯微卡小程序插件获取腾讯微卡身份态
若调用openid获取信息接口返回没有找到相关记录，则证明用户未使用过该小程序或者未授权过腾讯微卡插件 此时需要拉起小程序插件中的获取身份态组件，关联用户在小程序身份态(openid)和腾讯微卡身份态
# 使用插件
<login
schoolCode="schoolCode"
openId="openid"
bindverifyStudent="verifyStudent"
bindloginCancel="loginCalcel"
appId="appId"
appKey="appKey"
bindcardChooseGetInfo="callback"
bindcardChooseCancel="callback"
bindcardChooseErrofInfo="callback"
/>
| 参数 | 必填 | 说明 |
|---|---|---|
| openid | 是 | 用户在小程序中的openid |
| school_code | 是 | 学校/企业代码 |
| bindverifyStudent | 是 | 绑定回调事件 |
| bindloginCancel | 是 | 绑定用户取消授权事件 |
| appId | 是 | 小程序appId |
| appKey | 是 | 腾讯微卡应用APP KEY |
| bindcardChooseGetInfo | 是 | 卡信息页面获取卡信息 |
| bindcardChooseCancel | 是 | 卡信息页面取消 |
| bindcardChooseErrofInfo | 是 | 卡信息页面获取报错 |
# 回调事件
应用调起小程序插件的获取身份态组件，用户完成授权与关联之后，会触发bindverifyStudent事件，交由小程序段的事件处理函数来进行处理，处理完成后颖主动隐藏获取身份态组件
verifyStudent: function(e) {
var detail = e.detail;
var code = detail.code;
var message = detial.message;
if (code == 0) {
var student = detail.student;
var cardNumber = student.card_number; // 电子卡号
var name = student.name; // 姓名
var identityType = student.identity_type;// 身份类型，1为其他，2为学生，3为教职工，4为校友
var grade = student.grade;// 年级（需申请）
var college = student.college;// 学院（需申请）
var profession = student.profession;// 专业（需申请）
var class = student.class;// 班级（需申请）
var identityTitle = student.identity_class;// 身份职称（需申请）
var gender = student.gender;// 性别（需申请）
var organization = student.organization;// 组织架构（需申请）
var campus = student.campus;// 校区（需申请）
var dormNumber = student.dorm_number;// 宿舍号（需申请）
var physicalChipNumber = student.physical_chip_number;// 物理芯片号（需申请）
var physicalCardNumber = student.physical_card_number;// 物理卡号（需申请）
var nation = student.nation;// 民族（需申请）
var birthday = student.birthday;// 生日（需申请）
var originPlace = student.origin_place;// 生源地（需申请）
var graduatedSchool = student.graduated_school;// 毕业学校（需申请）
var address = student.address;// 家庭住址（需申请）
var contactPerson = student.contact_person;// 联系人（需申请）
var contactPhone = student.contact_phone;// 联系人手机号（需申请）
var email = student.email;// 邮箱（需申请）
var idCard = student.email;// 身份证（需申请）
var telephone = student.telephone;// 手机号（需申请）
var expire_at = student.expire_at;//有效期结束时间（需申请）
var start_at = student.start_at;//有效期开始时间(需申请)
}
}
| 参数 | 说明 |
|---|---|
| e.detail.code | 0、40003、7002、-1 |
| e.detail.message | 绑定成功、session已过期、学校/企业不存在该用户、network error |
| e.detail.student | 用户信息，仅当code等于0时拥有 |
若使用获取身份态组件进行身份态关联时，组件返回找不到用户信息，则该用户未在腾讯微卡领取过学校/企业的学校/企业卡，需要引导用户进行领卡，参考如下
# 引导用户绑定
组件返回找不到信息，会自动拉起小程序所关联学校/企业卡信息，用户界面操作上有取消和选择所对应的卡信息操作
<login
......
bindcardChooseGetInfo="getCardInfo" //点击卡片触发小程序中的getCardInfo
bindcardChooseCancel="cancelCardChoose" //取消操作触发小程序中的cancelCardChoose
bindcardChooseErrofInfo="errorCardChoose" //卡片信息获取失败操作触发小程序中的errorCardChoose
/>
# 用户点击对应的卡片
verifyStudent: function(e) {
var detail = e.detail;
var cardName = detail.cardName;
var cardId = detail.cardId;
}
| 参数 | 说明 |
|---|---|
| e.detail.cardId | 卡片id，通过卡片id，拉起卡片操作进行绑定，参考微信文档 |
| e.detail.cardName | 卡片名称 |
# 签名算法
请求接口中所涉及的签名算法以腾讯微卡应用通用签名算法为准。
# 更新日志
| 日期 | 变更说明 |
| 2019-10-18 | 移动端小程序获取用户身份接口 响应返回新增 start_time 有效起始时间字段，将 expire_time的有效期解释更改为 有效结束时间 |