chrome.identity

描述： 使用 chrome.identity API 获取 OAuth2 访问令牌。
可用版本： 从 Chrome 29 开始支持。
权限： "identity"
了解更多： 认证用户

摘要

类型
AccountInfo
方法
getAccounts − chrome.identity.getAccounts(function callback)
getAuthToken − chrome.identity.getAuthToken(object details, function callback)
getProfileUserInfo − chrome.identity.getProfileUserInfo(function callback)
removeCachedAuthToken − chrome.identity.removeCachedAuthToken(object details, function callback)
launchWebAuthFlow − chrome.identity.launchWebAuthFlow(object details, function callback)
getRedirectURL − string chrome.identity.getRedirectURL(string path)
事件
onSignInChanged

类型

AccountInfo

从 Chrome 32 开始支持。

属性
string id

账户的唯一标识符，在账户的生命周期内不会更改。

方法

getAccounts

chrome.identity.getAccounts(function callback)

仅用于 Dev 分支。了解更多内容

获取 AccountInfo 对象列表，描述配置文件中存在的账户。

getAccounts 目前仅在 Dev 分支中支持。

参数
function callback

callback 参数应该是一个如下形式的函数：

function(array of AccountInfo accounts) {...};
array of AccountInfo accounts

getAuthToken

chrome.identity.getAuthToken(object details, function callback)

获取 manifest.json 中 oauth2 部分指定的 OAuth2 访问令牌。

认证 API 会在内存中缓存访问令牌，所以可以在需要令牌的任何时候以非交互方式调用 getAuthToken。令牌缓存的过期问题会自动处理。

为了良好的用户体验，交互式令牌请求应该通过应用中的用户界面发起，并解释认证的原因。如果您没有做到这一点，用户会在没有任何上下文的情况下看到认证请求，如果未登录的话还会显示 Chrome 登录屏幕。特别注意，不要在应用第一次启动时以交互方式调用 getAuthToken。

参数
object （可选）
details

令牌选项。

boolean （可选）
interactive

获取令牌可能需要用户登录到 Chrome 浏览器，或同意应用程序请求的范围。如果交互式标志为 true，getAuthToken 会在必要时提示用户。当该标志为 false 或省略时，需要提示时 getAuthToken 会返回失败。

AccountInfo （可选）
account

从 Chrome 37 开始支持。警告：目前为 Beta 分支。了解更多内容

返回对应令牌的账户标识符，如果未指定，则使用当前配置文件中的主账户。

只有设置“enable-new-profile-management”标志后才支持 account 参数。
array of string （可选）
scopes

从 Chrome 37 开始支持。警告：目前为 Beta 分支。了解更多内容

要请求的 OAuth2 范围列表。

scopes 字段存在时，它会覆盖 manifest.json 中指定的范围列表。
function callback

调用时传递清单文件中指定的 OAuth2 访问令牌，如果发生错误则为 undefined。

callback 参数应该是一个如下形式的函数：

function(string token) {...};
string （可选）
token

getProfileUserInfo

chrome.identity.getProfileUserInfo(function callback)

从 Chrome 37 开始支持。警告：目前为 Beta 分支。了解更多内容

获取当前配置文件中登录用户的电子邮件地址和模糊处理后的 GAIA 标识符。

该 API 与 identity.getAccounts 的区别表现在以下两方面，返回的信息可以在离线状态下获得，并且只适用于当前配置文件的主帐户。

参数
function callback

callback 参数应该是一个如下形式的函数：

function(object userInfo) {...};
object userInfo
string email

当前配置文件中登录用户账户的电子邮件地址，如果用户未登录则为空。

string id

账户的唯一标志符，在账户的整个生命周期内不会更改。如果用户未登录则为空。

removeCachedAuthToken

chrome.identity.removeCachedAuthToken(object details, function callback)

从认证 API 的令牌缓存中移除 OAuth2 访问令牌。

如果发现某个访问令牌无效，应该将它传递给 removeCachedAuthToken 将它从缓存中移除，接着应用可以使用 getAuthToken 获取新的令牌。

参数
object details

Token information.

string token

应该从缓存中移除的某个令牌。

function callback

Called when the token has been removed from the cache.

callback 参数应该是一个如下形式的函数：

function() {...};

launchWebAuthFlow

chrome.identity.launchWebAuthFlow(object details, function callback)

在指定 URL 开始认证流程。

该方法通过打开一个网页视图并导航至提供商认证流程的第一个 URL，可以与非 Google 认证提供商进行认证流程。当提供商重定向至某个匹配 https://<app-id>.chromiumapp.org/* 的 URL 时，窗口会关闭，最终的重定向 URL 会传递给 callback 函数。

为了更好的用户体验，交互式认证流程应该通过应用中的用户界面发起，并解释认证原因。如果您没有这样做，您的用户看到认证请求时没有任何上下文。尤其注意，不要在应用第一次启动时开始交互式认证流程。

参数
object details

WebAuth 流程选项。

string url

开始认证流程的 URL。

boolean （可选）
interactive

是否要以交互模式执行认证流程。

由于某些认证流程可能会立刻重定向至结果 URL，launchWebAuthFlow 会隐藏该网页视图，直到第一次导航重定向至最终的 URL，或者要显示的网页加载完成。

如果交互式标识为 true，网页加载完成后会显示窗口。如果该标识为 false 或省略，launchWebAuthFlow 在第一次导航没有完成认证流程的情况下会返回错误。
function callback

调用时传递重定向回您的应用程序的 URL。

callback 参数应该是一个如下形式的函数：

function(string responseUrl) {...};
string （可选）
responseUrl

getRedirectURL

string chrome.identity.getRedirectURL(string path)

从 Chrome 33 开始支持。

生成重定向 URL，以便在 launchWebAuthFlow 中使用。

生成的 URL 匹配如下表达式 https://<app-id>.chromiumapp.org/*。

参数
string （可选）
path

附加到生成的 URL 末尾的路径。

事件

onSignInChanged

从 Chrome 33 开始支持。

当用户配置文件中某个账户的登录状态更改时产生。

addListener

chrome.identity.onSignInChanged.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function( AccountInfo account, boolean signedIn) {...};
AccountInfo account

从 Chrome 32 开始支持。

boolean signedIn

从 Chrome 32 开始支持。