oauth
OAuth模块管理客户端的用户登录授权验证功能,允许应用访问第三方平台的资源。
方法:
- getServices: 获取登录授权认证服务列表
对象:
- AuthService: 登录授权认证服务对象
- AuthOptions: JSON对象,授权认证参数选项
- AuthInfo: 登录授权认证信息
- UserInfo: 登录授权用户信息
回调方法:
- ServicesSuccessCallback: 获取登录授权认证服务成功回调
- AuthLogoutSuccessCallback: 注销登录授权认证操作成功回调函数
- AuthSuccessCallback: 登录授权认证服务操作成功回调函数
- AuthErrorCallback: 登录授权认证服务操作失败回调函数
权限:
permissions
{ // ... "permissions":{ // ... "OAuth": { "description": "登录鉴权" } } }
AuthService
登录授权认证服务对象
interface plus.oauth.AuthService { // Attributes attribute String id; attribute String description; attribute AuthInfo authResult; attribute UserInfo userInfo; attribute JSON extra; // Methods function void login( successCallback, errorCallback, options ); function void logout( successCallback, errorCallback ); function void getUserInfo( successCallback, errorCallback ); function void addPhoneNumber( successCallback, errorCallback ); }
说明:
AuthService对象用于表示登录授权认证服务,在JS中为对象,用于向系统进行登录授权认证操作。
属性:
- id: 登录授权认证服务标识
- description: 登录授权认证服务描述
- authResult: 授权认证结果数据
- userInfo: 登录授权认证用户信息
- extra: 登录授权认证扩展信息
方法:
- login: 请求登录授权认证操作
- logout: 注销登录授权认证
- getUserInfo: 获取登录授权用户信息
- addPhoneNumber: 添加用户手机号信息
AuthOptions
JSON对象,授权认证参数选项
interface plus.oauth.AuthOptions { attribute String scope; attribute String state; attribute String appid; attribute String appkey; attribute String appsecret; attribute String redirect_uri; }
说明:
此对象支持的属性值由登录授权认证服务定义。 例如“微信”,则可配置以下参数: scope - 应用授权作用域; state - 用于保持请求和回调的状态参数。
属性:
- scope: (String
类型
)申请的权限作用范围
如果存在多个权限,则以","符号分割。
- state: (String
类型
)客户端的当前状态,可以指定任意值,登录认证后原封不动的返回保存到AuthService对象的extra中
- appid: (String
类型
)登录授权认证服务平台申请的appid
动态设置登录授权服务中需要使用的appid,仅需要此参数的登录授权服务(如“微信登录”、“QQ登录”)支持。 如果未设置则使用运行环境中内置的appid值(如在HBuilder中可在manifest.json的SDK配置项中进行设置)。
- appkey: (String
类型
)登录授权认证服务平台申请的appkey
动态设置登录授权服务中需要使用的appkey,仅需要此参数的登录授权服务(如“新浪微博登录”、“360登录”)支持。 如果未设置则使用运行环境中内置的appkey值(如在HBuilder中可在manifest.json的SDK配置项中进行设置)。
- appsecret: (String
类型
)登录授权认证服务平台申请的appsecret
动态设置登录授权服务中需要使用的appsecret,仅需要此参数的登录授权服务(如“微信登录”、“新浪微博登录”)支持。 如果未设置则使用运行环境中内置的appkey值(如在HBuilder中可在manifest.json的SDK配置项中进行设置);当开放平台申请的appsecret值涉及到安全问题时,可在应用运行时从服务器获取,然后通过此api动态设置。
- redirect_url: (String
类型
)登录授权认证服务平台申请的redirect_url
动态设置登录授权服务中需要使用的redirect_url,仅需要此参数的登录授权服务(如“新浪微博登录”)支持。 如果未设置则使用运行环境中内置的redirect_url值(如在HBuilder中可在manifest.json的SDK配置项中进行设置)。
AuthInfo
登录授权认证信息
interface plus.oauth.AuthInfo { attribute String openid; attribute String access_token; attribute String expires_in: attribute String refresh_token; attribute String scope; }
说明:
此对象仅定义标准属性,登录授权认证服务可扩展定义。 例如“微信”登录授权服务,则包括以下数据: unionid - 用户统一标识,针对一个微信开放平台帐号下的应用,同一用户的unionid是唯一的。
属性:
- access_token: (String
类型
)登录授权的访问令牌
如果登录授权服务不支持此属性,则返回"undefined"。
- openid: (String
类型
)登录授权用户的唯一标识
如果登录授权服务不支持此属性,则返回"undefined"。
- expires_in: (String
类型
)登录授权访问令牌过期时间
单位为秒,如果登录授权服务不支持此属性,则返回"undefined"。
- refresh_token: (String
类型
)登录授权的更新令牌
用来获取下一次的访问令牌,如果登录授权服务不支持此属性,则返回"undefined"。
- scope: (String
类型
)登录授权的权限范围
如果存在多个权限,则以","符号分割。
UserInfo
登录授权用户信息
interface plus.oauth.UserInfo { attribute String openid; attribute String headimgurl: attribute String nickname; }
说明:
用于保存登录授权用户的信息。 此对象仅定义标准属性,登录授权认证服务可扩展定义。 例如“微信”登录授权服务,则包括以下数据: sex - 普通用户性别,1为男性,2为女性; province - 普通用户个人资料填写的省份; city - 普通用户个人资料填写的城市; country - 国家,如中国为CN; privilege - 用户特权信息,json数组,如微信沃卡用户为(chinaunicom); unionid - 用户统一标识,针对一个微信开放平台帐号下的应用,同一用户的unionid是唯一的。
属性:
- openid: (String
类型
)登录授权用户的唯一标识
如果登录授权服务不支持此属性,则返回"undefined"。
- headimgurl: (String
类型
)登录授权用户的头像图片地址
要求为"http://"或"https://"开头的地址,如果登录授权服务不支持此属性,则返回"undefined"。
- nickname: (String
类型
)登录授权用户的昵称
如果登录授权服务不支持此属性,则返回"undefined"。
ServicesSuccessCallback
获取登录授权认证服务成功回调
void ServicesSuccessCallback( services ) { // Get oauth services success code }
说明:
当获取登录授权认证服务列表成功时触发,并通过services参数返回运行环境支持的登录授权认证服务列表。
参数:
- services:
(
Array[
AuthService
]
)
必选 运行环境支持的登录授权认证服务列表
运行环境支持的登录授权认证服务列表数组,可通过services.length获取服务列表的数目。 如果当前运行环境没有支持的登录授权认证服务,则返回空数组。
返回值:
void : 无AuthLogoutSuccessCallback
注销登录授权认证操作成功回调函数
void AuthLogoutSuccessCallback( event ) { // logout code }
说明:
注销登录授权认证成功时触发,并返回操作结果。
参数:
- event:
(
JSON
)
必选 注销登录授权认证操作回调事件参数
包括以下参数: event.target - 表示登录授权认证服务对象; 其它属性可保存注销登录授权的扩展数据。
返回值:
void : 无AuthSuccessCallback
登录授权认证服务操作成功回调函数
void AuthSuccessCallback( event ) { // auth code }
说明:
登录授权认证服务操作如请求登录授权认证、获取登录授权用户信息成功时触发,并返回操作结果。
参数:
- event:
(
JSON
)
必选 登录授权认证服务操作回调事件参数
包括以下参数: event.target - 表示登录授权认证服务对象,可以通过此对象的authResult、userInfo属性来获取操作结果信息。
返回值:
void : 无AuthErrorCallback
登录授权认证服务操作失败回调函数
void AuthErrorCallback(error){ // Error code }
说明:
登录授权认证服务操作如请求登录授权认证、注销登录授权认证、获取登录授权用户信息失败时触发,并返回错误信息。
参数:
- error:
(
Exception
)
必选 操作失败错误信息
包括以下参数: error.code - 表示错误代码; error.message - 错误描述信息;