登录授权

最近更新时间:2020-05-12 15:25:32

app.auth()

接口描述

返回 Auth 对象。
签名:auth({ persistence: string }): Auth

输入参数

字段 类型 必填 说明
persistence string 身份认证状态如何持久保留,有三个选项 localsessionnone,默认为 session
  • local:在显式退出登录之前的 30 天内保留身份验证状态。
  • session:在窗口关闭时清除身份验证状态。
  • none:在页面重新加载时清除身份验证状态。

示例代码

const tcb = require("tcb-js-sdk");

const app = tcb.init({
  env: "xxxx-yyy"
});

let auth = app.auth({
  persistence: "local" //用户显式退出或更改密码之前的30天一直有效
});

Auth

Auth.getLoginState()

接口描述

返回当前登录状态 LoginState,如果未登录,则返回 null。
签名:getLoginState(): Promise<LoginState | null>

注意:

此接口将会在下个主版本废弃,推荐使用非异步Auth.hasLoginState()

示例代码

const app = tcb.init({
  env: "xxxx-yyy"
});

const loginState = app
  .auth()
  .getLoginState()
  .then(loginState => {
    if (loginState) {
      // 登录态有效
    } else {
      // 没有登录态,或者登录态已经失效
    }
  });

Auth.hasLoginState()

说明:

该方法自JavaScript SDK 1.5.0 版本起可以使用。

接口描述

返回当前登录状态 LoginState,如果未登录,则返回 null。
签名:getLoginState(): LoginState | null

示例代码

const app = tcb.init({
  env: "xxxx-yyy"
});

const loginState = app.auth().hasLoginState();

if (loginState) {
  // 登录态有效
} else {
  // 没有登录态,或者登录态已经失效
}

Auth.weixinAuthProvider()

接口描述

获取用于微信登录的 WeixinAuthProvider
签名:weixinAuthProvider({ appid: string, scope: string }): WeixinAuthProvider

字段 类型 必填 说明
appid string 微信公众平台(或开放平台)应用的 AppId。
scope string 网页授权类型,可选值为 snsapi_base(公众平台,只获取用户的 openid)、snsapi_userinfo(公众平台,获取用户的基本信息)和 snsapi_login(开放平台网页授权)。

示例代码

const app = tcb.init({
  env: "xxxx-yyy"
});

app
  .auth({
    persistence: "session"
  })
  .weixinAuthProvider({
    appid: "wx73932328juof23",
    scope: "snsapi_base"
  })
  .signIn()
  .then(() => {
    // 登录成功
  })
  .catch(err => {
    // 登录失败
  });

Auth.customAuthProvider()

说明:

该方法自 JavaScript SDK 1.5.0 版本起可以使用。

接口描述

获取用于自定义登录的 CustomAuthProvider
签名:customAuthProvider(): CustomAuthProvider

示例代码

const app = tcb.init({
  env: "xxxx-yyy"
});

// 获取自定义登录 ticket
const ticket = await fetch("...");

app
  .auth({
    persistence: "session"
  })
  .customAuthProvider()
  .signIn(ticket)
  .then(() => {
    // 登录成功
  })
  .catch(err => {
    // 登录失败
  });

Auth.anonymousAuthProvider()

说明:

该方法自 JavaScript SDK 1.5.0 版本起可以使用。

接口描述

获取用于自定义登录的 AnonymousAuthProvider
签名:anonymousAuthProvider(): AnonymousAuthProvider

示例代码

const app = tcb.init({
  env: "xxxx-yyy"
});

app
  .auth({
    persistence: "session"
  })
  .anonymousAuthProvider()
  .signIn()
  .then(() => {
    // 登录成功
  })
  .catch(err => {
    // 登录失败
  });

Auth.signInWithTicket()

接口描述

使用自定义登录凭据 ticket 登录云开发。
签名:signInWithTicket(ticket: string): Promise<void>

注意:

此接口将会在下个主版本废弃,推荐使用 CustomAuthProvider.signIn()

示例代码

const app = tcb.init({
  env: "xxxx-yyy"
});

// 获取自定义登录 ticket
const ticket = await fetch("...");

app
  .auth({
    persistence: "session"
  })
  .signInWithTicket(ticket)
  .then(() => {
    // 登录成功
  })
  .catch(err => {
    // 登录失败
  });

Auth.signInAnonymously()

接口描述

匿名登录云开发。
签名:signInAnonymously(): Promise<void>

注意:

此接口将会在下个主版本废弃,推荐使用 AnonymousAuthProvider.signIn()

示例代码

const app = tcb.init({
  env: "xxxx-yyy"
});

app
  .auth({
    persistence: "session"
  })
  .signInAnonymously()
  .then(() => {
    // 登录成功
  })
  .catch(err => {
    // 登录失败
  });

Auth.linkAndRetrieveDataWithTicket()

接口描述

将匿名用户转化为自定义登录用户。
签名:linkAndRetrieveDataWithTicket(ticket: string): Promise<void>

字段 类型 必填 说明
ticket string 自定义登录凭证 ticket

示例代码

const app = tcb.init({
  env: "xxxx-yyy"
});

const auth = app.auth();

// 调用此API之前需先请求接口获取到ticket
auth
  .linkAndRetrieveDataWithTicket(ticket)
  .then(res => {
    // 转正成功
  })
  .catch(err => {
    // 转正失败会抛出错误
  });

Auth.signOut()

接口描述

登出云开发。
签名:signOut(): Promise<void>

示例代码

const app = tcb.init({
  env: "xxxx-yyy"
});

const auth = app.auth();

auth.signOut();

Auth.getAuthHeader()

说明:

该方法自JavaScript SDK 1.5.0 版本起可以使用。

接口描述

获取 HTTP 鉴权头部,可用于云接入 HTTP 访问云函数时的鉴权。如果未登录,则返回 null
签名:getAuthHeader(): { "x-cloudbase-credentials": string } | null

示例代码

const app = tcb.init({
  env: "xxxx-yyy"
});

const auth = app.auth();

auth.getAuthHeader();
//=> { "x-cloudbase-credentials": "......" }

Auth.shouldRefreshAccessToken()

接口描述

接收一个回调函数,并且会在刷新短期访问令牌前调用此回调函数,根据返回值决定是否要刷新短期访问令牌。
对于两种登录态并存(Cloudbase、自身业务登录态)的 Web 应用,可以在回调函数内判断自身业务登录态是否失效,从而决定是否续期 Cloudbase 的短期访问令牌。
签名:shouldRefreshAccessToken(callback: () => boolean): void

示例代码

auth.shouldRefreshAccessToken(() => {
  if (/* 自身业务登录态还有效 */) {
    return true;
  } else {
    return false;
  }
});

Auth.onLoginStateChanged()

说明:

该方法自 JavaScript SDK 1.5.0 版本起可以使用。

接口描述

接收一个回调函数,并且会在登录状态改变时,调用此回调函数。
签名:onLoginStateChanged(callback: (loginState: LoginState) => any): void

示例代码

auth.onLoginStateChanged(loginState => {
  if (loginState) {
    // 有登录状态
  } else {
    // 没有登录
  }
});

Auth.onLoginStateExpired()

说明:

该方法自 JavaScript SDK 1.5.0 版本起可以使用。

接口描述

接收一个回调函数,并且会在登录状态过期,调用此回调函数。
签名:onLoginStateExpired(callback: Function): void

示例代码

auth.onLoginStateExpired(() => {
  // 此时登录状态过期,需要重新登录
});

Auth.onAccessTokenRefreshed()

说明:

该方法自 JavaScript SDK 1.5.0 版本起可以使用。

接口描述

接收一个回调函数,并且会在短期访问令牌刷新后,调用此回调函数。
签名:onAccessTokenRefreshed(callback: Function): void

示例代码

auth.onAccessTokenRefreshed(() => {
  // 此时短期访问令牌已经被刷新
});

Auth.onAnonymousConverted()

说明:

该方法自 JavaScript SDK 1.5.0 版本起可以使用。

接口描述

接收一个回调函数,并且会在匿名登录状态被转换后,调用此回调函数。
签名:onAnonymousConverted(callback: Function): void

示例代码

auth.onAnonymousConverted(() => {
  // 此时匿名登录状态已经被转换
});

Auth.onLoginTypeChanged()

说明:

该方法自 JavaScript SDK 1.5.0 版本起可以使用。

接口描述

接收一个回调函数,并且会在登录类型发生变化后,调用此回调函数。
签名:onLoginTypeChanged(callback: Function): void

示例代码

auth.onLoginTypeChanged(() => {
  // 此时登录类型已经发生变化
});

Auth.on()

接口描述

监听 Auth 相关的事件。

注意:

此接口会在下一个大版本废弃,推荐使用对应的事件回调接口。

签名:Auth.on(event: string, callback: Function): void

event 取值如下:

  • "loginStateExpire":登录态过期时触发回调。
  • "refreshAccessToken":刷新短期访问凭证时触发回调。

示例代码

auth.on("loginStateExpire", () => {
  // 此时登录态已经失效
});

WeixinAuthProvider

WeixinAuthProvider.signIn()

接口描述

此接口会首先判断本地是否存在云开发登录态,然后:

  • 如果本地有登录态,那么直接返回本地登录态
  • 如果没有,那么会判断页面 url 中有无微信登录需要的 code 字段:
    • 如果有 code 字段,那么会直接登录云开发,并返回登录态
    • 如果没有 code 字段,那么会自动跳转到微信登录页面

签名: signIn(): Promise<LoginState>

注意:

此接口将会在下个主版本废弃,推荐使用 WeixinAuthProvider.signInWithRedirect()WeixinAuthProvider.getRedirectResult() 的组合来完成跳转登录。

示例代码

const app = tcb.init({
  env: "xxxx-yyy"
});

app
  .auth({
    persistence: "session"
  })
  .weixinAuthProvider({
    appid: "wx73932328juof23",
    scope: "snsapi_base"
  })
  .signIn()
  .then(() => {
    // 登录成功
  })
  .catch(err => {
    // 登录失败
  });

WeixinAuthProvider.signInWithRedirect()

说明:

该方法自 JavaScript SDK 1.5.0 版本起可以使用。

接口描述

跳转到微信登录页面。

说明:

推荐使用此接口搭配 WeixinAuthProvider.getRedirectResult() 完成完整的登录流程。

签名:signInWithRedirect(): void

示例代码

// 直接跳转到微信登录页面
app
  .auth()
  .weixinAuthProvider({
    appid: "wx73932328juof23",
    scope: "snsapi_base"
  })
  .signInWithRedirect();

WeixinAuthProvider.getRedirectResult()

说明:

该方法自 JavaScript SDK 1.5.0 版本起可以使用。

接口描述

微信登录页面重定向回来后,使用重定向的返回值登录,并获取登录态。
签名:getRedirectResult(): Promise<LoginState | null>

示例代码

const provider = app.auth().weixinAuthProvider({
  appid: "wx73932328juof23",
  scope: "snsapi_base"
});

// 假设我们有一个“微信登录”按钮,点击后跳转登录页面
document.getElementById("login").onclick = function() {
  provider.signInWithRedirect();
};

// 如果页面含有微信的登录态,那么回调中会存在 LoginState
provider.getRedirectResult().then(loginState => {
  if (loginState) {
    // 有登录态
  }
});

CustomAuthProvider

说明:

该方法自 JavaScript SDK 1.5.0 版本起可以使用。

CustomAuthProvider.signIn()

接口描述

使用自定义登录凭据 ticket 登录云开发。
签名:signIn(ticket: string): Promise<void>

示例代码

const app = tcb.init({
  env: "xxxx-yyy"
});

// 获取自定义登录 ticket
const ticket = await fetch("...");

app
  .auth({
    persistence: "session"
  })
  .customAuthProvider()
  .signIn(ticket)
  .then(() => {
    // 登录成功
  })
  .catch(err => {
    // 登录失败
  });

AnonymousAuthProvider

说明:

该方法自 JavaScript SDK 1.5.0 版本起可以使用。

AnonymousAuthProvider.signIn()

接口描述

匿名登录云开发。
签名:signIn(): Promise<void>

示例代码

const app = tcb.init({
  env: "xxxx-yyy"
});

app
  .auth({
    persistence: "session"
  })
  .anonymousAuthProvider()
  .signIn()
  .then(() => {
    // 登录成功
  })
  .catch(err => {
    // 登录失败
  });
目录