oauth

OAuth模块管理客户端的用户授权登录验证功能，允许应用访问第三方平台的资源。

方法：

getServices: 获取授权登录认证服务列表

对象：

AuthService: 授权登录认证服务对象
AuthOptions: JSON对象，授权认证参数选项

回调方法：

ServicesSuccessCallback: 获取授权登录认证服务成功回调
AuthLogoutSuccessCallback: 注销授权登录认证操作成功回调函数
AuthSuccessCallback: 授权登录认证服务操作成功回调函数
AuthErrorCallback: 授权登录认证服务操作失败回调函数

权限：

permissions


"OAuth": {
	"description": "访问授权登录认证插件"
}

getServices

获取授权登录认证服务列表


void plus.oauth.getServices( successCB, errorCB );

说明：

获取终端支持的权登录认证服务列表，可用于提示用户进行登录平台的选择。获取授权登录认证服务成功后通过successCB回调返回支持的所有服务列表，获取服务失败则通过errorCB回调返回失败信息。

参数：

successCB: ( ServicesSuccessCallback ) 必选 获取授权登录认证服务成功回调函数
获取授权登录认证服务列表成功时触发回调，并返回终端支持的授权登录认证服务列表。
errorCB: ( AuthErrorCallback ) 可选 获取授权登录认证服务失败回调函数
获取授权登录认证服务列表失败时触发回调，并返回错误信息。

返回值：

void : 无

平台支持：

Android - 2.2+ (支持)
iOS - 5.0+ (支持)

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>OAuth Example</title>
	<script type="text/javascript">
var auths=null;
// 监听plusready事件  
document.addEventListener( "plusready", function(){
	// 扩展API加载完毕，现在可以正常调用扩展API
	plus.oauth.getServices( function(services){
		auths = services;
	}, function(e){
		alert( "获取分享服务列表失败："+e.message+" - "+e.code );
	} );
}, false );
	</script>
	</head>
	<body>
		获取授权登录认证服务列表
	</body>
</html>

AuthService

授权登录认证服务对象


interface plus.oauth.AuthService {
	// Attributes
	attribute String id;
	attribute String description;
	attribute JSON authResult;
	attribute JSON 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: 添加用户手机号信息

id

授权登录认证服务标识

说明：

String 类型只读属性

用于表示授权登录认证服务标识，如“weixin”表示微信、“qq”表示QQ、“sinaweibo”表示新浪微博、“qihoo”表示360账号登录（仅360手助流应用环境下支持）。

平台支持：

Android - 2.2+ (支持)
iOS - 5.0+ (支持)

description

授权登录认证服务描述

说明：

String 类型只读属性

用于描述授权登录认证服务的信息，如“微信”、“QQ”、“新浪微博”、“360账号”。

平台支持：

Android - 2.2+ (支持)
iOS - 5.0+ (支持)

authResult

授权认证结果数据

说明：

JSON 类型只读属性

用于标识此授权登录认证服务是否已经授权登录认证过，如果已经授权登录过则保存授权登录信息，否则为undefined。例如“微信”，则可能保存以下数据： code - 用户换取access_token的code; lang - 微信客户端当前语言; country - 微信用户当前国家信息; access_token - 接口调用凭证; expires_in - access_token接口调用凭证超时时间，单位（秒）; refresh_token - 用户刷新access_token; openid - 授权用户唯一标识; scope - 用户授权的作用域，使用逗号（,）分隔。

平台支持：

Android - 2.2+ (支持)
iOS - 5.0+ (支持)

userInfo

授权登录认证用户信息

说明：

JSON 类型只读属性

用于标识此授权登录认证服务是否已经获取过用户信息，如果已经通过授权登录并获取用户信息成功则保存用户相关信息，否则为undefined。例如“微信”，则可能保存以下数据： openid - 普通用户的标识，对当前开发者帐号唯一; nickname - 普通用户昵称; sex - 普通用户性别，1为男性，2为女性; province - 普通用户个人资料填写的省份; city - 普通用户个人资料填写的城市; country - 国家，如中国为CN; headimgurl - 用户头像，最后一个数值代表正方形头像大小（有0、46、64、96、132数值可选，0代表640*640正方形头像），用户没有头像时该项为空; privilege - 用户特权信息，json数组，如微信沃卡用户为（chinaunicom）; unionid - 用户统一标识。针对一个微信开放平台帐号下的应用，同一用户的unionid是唯一的。

平台支持：

Android - 2.2+ (支持)
iOS - 5.0+ (支持)

extra

授权登录认证扩展信息

说明：

JSON 类型只读属性可选属性

用于保存授权登录认证服务返回的扩展信息，具体内容由各登录平台决定，如果没有扩展信息则为undefined。例如“微信”，则可保存以下数据： state - 用于保持请求和回调的状态参数。

login

请求授权登录认证操作


						
void obj.login( successCallback, errorCallback, options );

说明：

对指定的授权登录认证服务进行登录认证操作，在登录前可通过对象的authResult属性判断是否已经登录认证过，通常只需要对没有进行过登录认证的服务进行登录认证操作。授权认证操作成功后通过successCB回调函数通知，失败则通过errorCB回调函数通知。

参数：

successCallback: ( AuthSuccessCallback ) 必选 授权登录认证服务登录认证成功回调函数
授权登录认证服务登录认证操作成功时触发，并返回登录认证成功信息。
errorCallback: ( AuthErrorCallback ) 可选 授权登录认证服务登录认证失败回调函数
授权登录认证服务授权认证操作失败时触发，并返回错误信息。
options: ( AuthOptions ) 可选 授权登录认证参数
授权登录认证服务授权认证操作使用的参数。

返回值：

void : 无

平台支持：

Android - 2.2+ (支持)
iOS - 5.0+ (支持)

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>OAuth Example</title>
	<script type="text/javascript">
var auths=null;
// 监听plusready事件  
document.addEventListener( "plusready", function(){
	// 扩展API加载完毕，现在可以正常调用扩展API
	plus.oauth.getServices( function(services){
		auths = services;
	}, function(e){
		alert( "获取分享服务列表失败："+e.message+" - "+e.code );
	} );
}, false );
// 登录操作
function authLogin(){
	var s = auths[0];
	if ( !s.authResult ) {
		s.login( function(e){
			alert( "登录认证成功！" );
		}, function(e){
			alert( "登录认证失败！" );
		} );
	}else{
		alert( "已经登录认证！" );
	}
}
	</script>
	</head>
	<body>
		1.请求授权登录认证操作<br/>
		<button onclick="authLogin()">Login</button>
	</body>
</html>

logout

注销授权登录认证


void obj.logout( successCallback, errorCallback );

说明：

对指定的授权登录认证服务注销登录认证操作，注销授权认证后，再次操作时需重新进行登录认证操作。如果第三方平台不需要注销操作，则情况保存的相关登录认证等信息。

参数：

successCallback: ( AuthLogoutSuccessCallback ) 必选 注销授权登录认证成功回调函数
注销授权登录认证服务登录认证操作成功时触发，并返回注销登录认证成功信息。
errorCallback: ( AuthErrorCallback ) 可选 注销授权登录认证失败回调函数
注销授权登录认证服务授权认证操作失败时触发，并返回错误信息。

返回值：

void : 无

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>OAuth Example</title>
	<script type="text/javascript">
var auths=null;
// 监听plusready事件  
document.addEventListener( "plusready", function(){
	// 扩展API加载完毕，现在可以正常调用扩展API
	plus.oauth.getServices( function(services){
		auths = services;
	}, function(e){
		alert( "获取分享服务列表失败："+e.message+" - "+e.code );
	} );
}, false );
// 登录操作
function authLogin(){
	var s = auths[0];
	if ( !s.authResult ) {
		s.login( function(e){
			alert( "登录认证成功！" );
		}, function(e){
			alert( "登录认证失败！" );
		} );
	}else{
		alert( "已经登录认证！" );
	}
}
// 注销所有授权登录认证服务
function authLogout(){
	for ( var i in auths ) {
		var s = auths[i];
		if ( s.authResult ) {
			s.logout(function(e){
				alert( "注销登录认证成功！" );
			}, function(e){
				alert( "注销登录认证失败！" );
			});
		}
	}
}
	</script>
	</head>
	<body>
		1.请求授权登录认证操作<br/>
		<button onclick="authLogin()">Login</button>
		2.请求授权登录认证操作<br/>
		<button onclick="authLogout()">Logout</button>
	</body>
</html>

getUserInfo

获取授权登录用户信息


void obj.getUserInfo( successCallback, errorCallback );

说明：

获取授权登录认证的用户信息，在获取前可通过对象的userInfo属性判断是否已经获取过，通常只需要对没有获取过用户信息的服务进行操作。获取用户信息操作成功后通过successCallback回调函数通知，失败则通过errorCallback回调函数通知。

参数：

successCallback: ( AuthSuccessCallback ) 必选 获取授权登录用户信息成功回调函数
获取登录认证用户信息操作成功时触发，并返回用户的信息。
errorCallback: ( AuthErrorCallback ) 可选 获取授权登录用户信息失败回调函数
获取登录认证用户信息操作失败时触发，并返回错误信息。

返回值：

void : 无

平台支持：

Android - 2.2+ (支持)
iOS - 5.0+ (支持)

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>OAuth Example</title>
	<script type="text/javascript">
var auths=null;
// 监听plusready事件  
document.addEventListener( "plusready", function(){
	// 扩展API加载完毕，现在可以正常调用扩展API
	plus.oauth.getServices( function(services){
		auths = services;
	}, function(e){
		alert( "获取分享服务列表失败："+e.message+" - "+e.code );
	} );
}, false );
// 登录操作
function authLogin(){
	var s = auths[0];
	if ( !s.authResult ) {
		s.login( function(e){
			alert( "登录认证成功！" );
		}, function(e){
			alert( "登录认证失败！" );
		} );
	}else{
		alert( "已经登录认证！" );
	}
}
// 获取登录用户信息操作
function authUserInfo(){
	var s = auths[0];
	if ( !s.authResult ) {
		alert("未授权登录！");
	} else {
		s.getUserInfo( function(e){
			alert( "获取用户信息成功："+JSON.stringify(s.userInfo) );
		}, function(e){
			alert( "获取用户信息失败："+e.message+" - "+e.code );
		} );
	}
}
	</script>
	</head>
	<body>
		1.请求授权登录认证操作<br/>
		<button onclick="authLogin()">Login</button>
		2. 获取授权登录用户信息<br/>
		<button onclick="authUserInfo()">UserInfo</button>
	</body>
</html>

addPhoneNumber

添加用户手机号信息


void obj.addPhoneNumber( successCallback, errorCallback );

说明：

打开授权登录服务的添加用户手机号界面进行操作，添加用户手机号操作成功后通过successCallback回调函数通知，否则通过errorCallback回调函数通知。

参数：

successCallback: ( AuthSuccessCallback ) 必选 添加用户手机号信息成功回调函数
errorCallback: ( AuthErrorCallback ) 可选 添加用户手机号信息失败回调函数

返回值：

void : 无

平台支持：

Android - ALL (不支持)
iOS - ALL (不支持)
360手助流应用 - 3.5+ (支持)

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>OAuth Example</title>
	<script type="text/javascript">
var auths=null;
// 监听plusready事件  
document.addEventListener( "plusready", function(){
	// 扩展API加载完毕，现在可以正常调用扩展API
	plus.oauth.getServices( function(services){
		auths = services;
	}, function(e){
		alert( "获取分享服务列表失败："+e.message+" - "+e.code );
	} );
}, false );
// 登录操作
function authLogin(){
	var s = auths[0];
	if ( !s.authResult ) {
		s.login( function(e){
			alert( "登录认证成功！" );
		}, function(e){
			alert( "登录认证失败！" );
		} );
	}else{
		alert( "已经登录认证！" );
	}
}
// 添加用户手机号信息
function addPhoneNumber(){
	var s = auths[0];
	if ( !s.authResult ) {
		alert("未授权登录！");
	} else {
		s.addPhoneNumber( function(e){
			alert( "添加用户手机号信息成功！" );
		}, function(e){
			alert( "添加用户手机号信息失败："+e.message+" - "+e.code );
		} );
	}
}
	</script>
	</head>
	<body>
		1.请求授权登录认证操作<br/>
		<button onclick="authLogin()">Login</button>
		2.添加用户手机号信息<br/>
		<button onclick="addPhoneNumber()">AddPhoneNumber</button>
	</body>
</html>

AuthOptions

JSON对象，授权认证参数选项


interface plus.oauth.AuthOptions {
	attribute String scope;
	attribute String state;
	attribute String appkey;
}

说明：

此对象支持的属性值由授权登录认证服务定义。例如“微信”，则可配置以下参数： scope - 应用授权作用域； state - 用于保持请求和回调的状态参数。

属性：

scope: (String 类型 )申请的权限范围
state: (String 类型 )客户端的当前状态，可以指定任意值，登录认证后原封不动的返回保存到AuthService对象的extra中
appkey: (String 类型 )360开放平台申请的生活助手应用appkey标识
平台支持
- Android - 2.2+ (不支持)
- iOS - 5.0+ (不支持)

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>OAuth Example</title>
	<script type="text/javascript">
var auths=null;
// 监听plusready事件  
document.addEventListener( "plusready", function(){
	// 扩展API加载完毕，现在可以正常调用扩展API
	plus.oauth.getServices( function(services){
		auths = services;
	}, function(e){
		alert( "获取分享服务列表失败："+e.message+" - "+e.code );
	} );
}, false );
// 登录操作
function authLogin(){
	var s = auths[0];
	if ( !s.authResult ) {
		s.login( function(e){
			alert( "登录认证成功！" );
		}, function(e){
			alert( "登录认证失败！" );
		}, {appid:"wx0411fa6a39d61297"  // 微信应用的appid
			,scope:"snsapi_userinfo"}   // 授权获取用户信息
		);
	}
}
	</script>
	</head>
	<body>
		请求授权登录认证操作（配置参数）
		<button onclick="authLogin()">Login</button>
	</body>
</html>

ServicesSuccessCallback

获取授权登录认证服务成功回调


void ServicesSuccessCallback( services ) {
	// Get oauth services success code
}

说明：

当获取授权登录认证服务列表成功时触发，并通过services参数返回运行环境支持的授权登录认证服务列表。

参数：

services: ( Array[ AuthService ] ) 必选 运行环境支持的授权登录认证服务列表
运行环境支持的授权登录认证服务列表数组，可通过services.length获取服务列表的数目。如果当前运行环境没有支持的授权登录认证服务，则返回空数组。

返回值：

void : 无

平台支持：

Android - 2.2+ (支持)
iOS - 5.0+ (支持)

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>OAuth Example</title>
	<script type="text/javascript">
var auths=null;
// 监听plusready事件  
document.addEventListener( "plusready", function(){
	// 扩展API加载完毕，现在可以正常调用扩展API
	plus.oauth.getServices( function(services){
		// services.length可获取当前运行环境支持授权登录认证服务数目
		if(services.length>0){
			auths = services;
		}else{
			alert("当前运行环境不支持授权登录认证服务！");
		}
	}, function(e){
		alert( "获取分享服务列表失败："+e.message+" - "+e.code );
	} );
}, false );
	</script>
	</head>
	<body>
		获取授权登录认证服务列表
	</body>
</html>

AuthLogoutSuccessCallback

注销授权登录认证操作成功回调函数


void AuthLogoutSuccessCallback( event ) {
	　　// logout code
}

说明：

注销授权登录认证成功时触发，并返回操作结果。

参数：

event: ( JSON ) 必选 注销授权登录认证操作回调事件参数
包括以下参数： event.target - 表示授权登录认证服务对象；其它属性可保存注销授权登录的扩展数据。

返回值：

void : 无

平台支持：

Android - 2.2+ (支持)
iOS - 5.0+ (支持)

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>OAuth Example</title>
	<script type="text/javascript">
var auths=null;
// 监听plusready事件  
document.addEventListener( "plusready", function(){
	// 扩展API加载完毕，现在可以正常调用扩展API
	plus.oauth.getServices( function(services){
		auths = services;
	}, function(e){
		alert( "获取分享服务列表失败："+e.message+" - "+e.code );
	} );
}, false );
// 注销所有授权登录认证服务
function authLogout(){
	for ( var i in auths ) {
		var s = auths[i];
		if ( s.authResult ) {
			s.logout(function(e){
				alert( "注销登录认证成功！" );
			}, function(e){
				alert( "注销登录认证失败！" );
			});
		}
	}
}
	</script>
	</head>
	<body>
		请求授权登录认证操作
		<br/>
		<button onclick="authLogout()">Logout</button>
	</body>
</html>

AuthSuccessCallback

授权登录认证服务操作成功回调函数


void AuthSuccessCallback( event ) {
	　　// auth code
}

说明：

授权登录认证服务操作如请求授权登录认证、获取授权登录用户信息成功时触发，并返回操作结果。

参数：

event: ( JSON ) 必选 授权登录认证服务操作回调事件参数
包括以下参数： event.target - 表示授权登录认证服务对象，可以通过此对象的authResult、userInfo属性来获取操作结果信息。

返回值：

void : 无

平台支持：

Android - 2.2+ (支持)
iOS - 5.0+ (支持)

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>OAuth Example</title>
	<script type="text/javascript">
var auths=null;
// 监听plusready事件  
document.addEventListener( "plusready", function(){
	// 扩展API加载完毕，现在可以正常调用扩展API
	plus.oauth.getServices( function(services){
		auths = services;
	}, function(e){
		alert( "获取分享服务列表失败："+e.message+" - "+e.code );
	} );
}, false );
// 登录操作
function authLogin(){
	var s = auths[0];
	if ( !s.authResult ) {
		s.login( function(e){
			// 获取登录操作结果
			var result = e.target.authResult;
			alert( "登录认证成功："+JSON.stringify(result) );
		}, function(e){
			alert( "登录认证失败！" );
		}, {} );
	}
}
	</script>
	</head>
	<body>
		请求授权登录认证操作
		<button onclick="authLogin()">Login</button>
	</body>
</html>

AuthErrorCallback

授权登录认证服务操作失败回调函数


void AuthErrorCallback( error ) {
	// Error code
}

说明：

授权登录认证服务操作如请求授权登录认证、注销授权登录认证、获取授权登录用户信息失败时触发，并返回错误信息。

参数：

error: ( Exception ) 必选 操作失败错误信息
包括以下参数： error.code - 表示错误代码； error.message - 错误描述信息；

返回值：

void : 无

平台支持：

Android - 2.2+ (支持)
iOS - 5.0+ (支持)

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>OAuth Example</title>
	<script type="text/javascript">
var auths=null;
// 监听plusready事件  
document.addEventListener( "plusready", function(){
	// 扩展API加载完毕，现在可以正常调用扩展API
	plus.oauth.getServices( function(services){
		auths = services;
	}, function(e){
		alert( "获取分享服务列表失败："+e.message+" - "+e.code );
	} );
}, false );
// 登录操作
function authLogin(){
	var s = auths[0];
	if ( !s.authResult ) {
		s.login( function(e){
			alert( "登录认证成功！" );
		}, function(e){
			alert( "登录认证失败："+e.message+" - "+e.code );
		}, {} );
	}
}
	</script>
	</head>
	<body>
		请求授权登录认证操作
		<button onclick="authLogin()">Login</button>
	</body>
</html>