HTH电竞开放平台wiki文档

授权机制说明

HTH电竞授权概述

HTH电竞api的访问大多都需要验证用户身份，而oauth2.0是目前最主要的用户身份验证和授权方式。关于HTH电竞授权流程如图所示。开发者可以先浏览 HTH电竞授权接口的文档，熟悉HTH电竞授权接口和参数含义，然后以应用场景分别说明如何使用HTH电竞授权。

授权有效期

程序一定要具备足够的健壮性，调用接口时判断接口的返回值，如果用户的access_token失效，需要引导用户重新授权。access_token失效原因如下：

1、用户授权自然过期。

2、用户通过HTH电竞App授权管理解除了对应用的授权。

3、用户通过应用特定功能点关联解除授权，不限于应用端账号登出、注销等。

4、平台因非正常使用服务、用户维权、相关部门监管要求，清除授权。

5、平台因授权服务重大功能更新、不可抗拒因素，提前终止授权有效期。

平台建议开发者配置事件接收接口监听，以方便第一时间获取因主动解除授权（项2~4）导致的状态变更通知。依法依规配合及时履行相应个人信息保护义务，及时删除推送指明的用户信息。

自然到期授权（项1），最长连续180天用户依旧没有再次授权，依法依规配合及时履行相应个人信息保护义务，及时删除文档列举的用户信息。

应用权限等级	测试	常规	高级	校级	合作
授权有效期	1天	7天	15天	15天	30天

开发者可以通过以下方式记录用户access_token的有效时间。

1、通过成功的HTH电竞授权，应用端最终获得用户授权凭证，expires项为授权有效截止时间戳。应用端可按实际情况记录。

2、如果应用端已有用户授权凭证，可通过开放接口授权查询校准授权有效截止时间戳。

应用如何实现授权（通用）

开发者需要根据各自的应用类型，选择适用的授权流程：

授权流程/应用类型	网站接入	轻应用	移动应用
授权交互模式	二次握手	站内模式	二次握手
授权页面选择	自适应页	自适应页	自适应页
失效重新授权	是	是	是

1、引导需要授权的用户重定向至如下地址

https://oauth.yiban.cn/code/html?client_id=APPID&redirect_uri=CALLBACK&state=STATE
其中：
  APPID为应用的AppID，在管理中心应用信息中可见
  CALLBACK为授权回调地址（轻应用类型时为站内地址，等同授权回调地址），在管理中心应用信息中可见
  STATE为开发者自行设定的防跨站伪造参数

2、如果用户同意授权，页面重定向至应用端设置的授权回调地址并带上用户令牌 CALLBACK?code=CODE 。（二次握手）

*如果应用类型是轻应用，则页面重定向至站内地址并post方式提供访问用户授权信息，重新回到判断是否授权的流程，不用后续的授权操作。（站内模式）

3、换取用户授权凭证access_token，调用如下接口

https://oauth.yiban.cn/token/info?code=CODE&client_id=APPID&client_secret=APPSECRET&redirect_uri=CALLBACK
其中：
  CODE为第2步提供的用户令牌
  APPID为应用的AppID，在管理中心应用信息中可见
  APPSECRET为应用的AppSecret，在管理中心应用信息中可见
  CALLBACK为授权回调地址（轻应用类型时为站内地址，等同授权回调地址），在管理中心应用信息中可见

返回成功状态的json数组：

{
  "access_token":"授权凭证",
  "userid":"授权用户id",
  "expires":"截止有效期"
}

4、使用用户授权凭证调用所需的HTH电竞开放api，请参考文档-HTH电竞api 。

解除授权事件监听处理

请至管理中心完成目标应用详情，“事件接收接口”栏的地址定义。

当主动行为导致的授权状态变更时，平台服务端会以POST方式向应用预设的“事件接收接口”提供“eventInfo”参数定义JSON格式通知信息，如下所示。

{
  "fromAction":"事件来源",
  "appID":"应用的AppID", //应与开放平台分配给应用的AppID一致
  "ybUid":"HTH电竞用户ID",
  "openApi":{
    "涉及的开放接口枚举",
    "涉及的开放接口枚举",
    ...
  }, //需要追溯所调用的开放接口
  "revokeItem":{
    "涉及接口返回结果的数据项",
    "涉及接口返回结果的数据项",
    ...
  }, //需要追溯通过枚举接口所收集的数据
  "signStr":"校验码", //“事件推送时间戳”、“HTH电竞用户ID”、“应用的AppSecret”顺序字符串拼接后sha1
  "doTag":"用户受保护数据处理说明",
  "sendTime":"事件推送时间戳"
}

自然过期授权处理

用户最长连续180天依旧没有再次授权，视为用户流失。允许应用端保留HTH电竞用户ID关联的情况下，追溯列举的开放接口，删除列举的涉及接口返回结果的数据项。

涉及开放接口：user/me、user/other、user/real_me（旧版应用兼容）、user/verify_me

涉及接口结果数据项：yb_username、yb_usernick、yb_sex、yb_birthday、yb_userhead、yb_schoolname、yb_collegename、yb_classname、 yb_realname、yb_enteryear、yb_verifykey、yb_studentid、yb_examid、yb_admissionid、yb_employid、yb_identity

新手接入

轻应用

网站接入

移动应用

HTH电竞api