跳到主要内容

登录认证

警告

新版 JavaScript SDK 已更名 @cloudbase/js-sdk ，旧版本 tcb-js-sdk 未来不再更新，点击查看迁移指南。

app.auth()​

接口描述​

返回 Auth 对象

签名：auth({ persistence: string }): Auth

输入参数​

字段类型必填说明
persistencestring否身份认证状态如何持久保留，有三个选项 local、session 和 none，默认为 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.currentUser​

提示

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

接口描述​

返回表示当前用户的 User 实例

示例代码​

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

// 执行某种登录之后...
const user = app.auth.currentUser;
console.log(user.nickName);

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

字段类型必填说明
appidstring是微信公众平台（或开放平台）应用的 appid。
scopestring是网页授权类型，可选值为 snsapi_base（公众平台，只获取用户的 openid）、snsapi_userinfo（公众平台，获取用户的基本信息）和 snsapi_login（开放平台网页授权）。

示例代码​

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

app
  .auth({
    persistence: "session"
  })
  .weixinAuthProvider({
    appid: "...",
    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>

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

示例代码​

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

const auth = app.auth();

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

Auth.signUpWithEmailAndPassword()​

提示

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

接口描述​

使用邮箱和密码注册一个云开发账户，调用后，会自动向注册邮箱发送邮箱验证邮件。

签名：signUpWithEmailAndPassword(email: string, password: string): Promise<void>

示例代码​

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

const auth = app.auth();

const email = "foo@bar.com";
const password = "your_awesome_password";
auth.signUpWithEmailAndPassword(email, password).then(() => {
  // 发送验证邮件成功
});

Auth.signInWithEmailAndPassword()​

提示

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

接口描述​

使用邮箱和密码登录云开发。

签名：signInWithEmailAndPassword(email: string, password: string): Promise<LoginState>

示例代码​

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

const auth = app.auth();

const email = "foo@bar.com";
const password = "your_awesome_password";
auth.signInWithEmailAndPassword(email, password).then((loginState) => {
  // 邮箱密码登录成功
});

Auth.sendPasswordResetEmail()​

提示

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

接口描述​

发送重置密码的邮件。

签名：sendPasswordResetEmail(email: string): Promise<void>

示例代码​

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

const auth = app.auth();

const email = "foo@bar.com";
auth.sendPasswordResetEmail(email).then(() => {
  // 发送重置密码邮件成功
});

Auth.signInWithUsernameAndPassword()​

提示

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

接口描述​

使用用户名密码登录云开发。

签名：signInWithUsernameAndPassword(username: string, password: string): Promise<LoginState>

示例代码​

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

const auth = app.auth();

const username = "your_awesome_username";
const password = "your_awesome_password";
auth.signInWithUsernameAndPassword(username, password).then((loginState) => {
  // 用户名密码登录成功
});

Auth.isUsernameRegistered()​

提示

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

接口描述​

检查用户名是否被绑定过。

签名：isUsernameRegistered(username: string): Promise<boolean>

示例代码​

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

const auth = app.auth();

const username = "your_awesome_username";
auth.isUsernameRegistered(username).then((registered) => {
  //
});

Auth.signOut()​

接口描述​

登出云开发

签名：signOut(): Promise<void>

示例代码​

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

const auth = app.auth();

auth.signOut().then(() => {
  // 登出成功
});

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", () => {
  // 此时登录态已经失效
});

LoginState​

提示

该对象自 JavaScript SDK 1.7.0 版本起可以使用

LoginState 对象是对用户当前的登录态的抽象

LoginState.loginType​

类型：string

表示当前的登录类型

取值含义
"ANONYMOUS"匿名登录
"WECHAT"微信登录
"CUSTOM"自定义登录

LoginState.user​

类型：User | null

表示当前用户，具体请参考 User

如果没有登录，则为 null

LoginState.isAnonymousAuth​

类型：boolean

表示当前是否为匿名登录

LoginState.isCustomAuth​

类型：boolean

表示当前是否为自定义登录

LoginState.isWeixinAuth​

类型：boolean

表示当前是否为微信登录

User​

提示

该对象自 JavaScript SDK 1.7.0 版本起可以使用

User 对象是对云开发用户的抽象表示

User.uid​

类型：string

云开发用户的全局唯一 ID

User.loginType​

类型：string

表示当前的登录类型

取值含义
"ANONYMOUS"匿名登录
"WECHAT"微信登录
"CUSTOM"自定义登录

User.openid​

类型：string

表示此用户绑定的微信 openid

User.unionId​

类型：string

表示此用户绑定的微信 unionId

User.wxOpenId​

表示此用户绑定的微信 openid

User.wxPublicId​

表示此用户绑定的微信开放平台 openid

User.customUserId​

表示此用户绑定的自定义登录 customUserId

User.qqMiniOpenId​

类型：string

表示此用户对应的 QQ 小程序 openid

User.nickName​

类型：string

用户昵称

User.gender​

类型：string

用户性别，取值仅限于："MALE"、"FEMALE、"UNKNOWN"

User.avatarUrl​

类型：string

用户头像 URL

User.location​

类型: { country: string; province: string; city: string }

用户地理位置

User.username​

类型：string

用户名

User.update()​

接口描述​

更新用户信息

签名：update(userInfo): Promise<void>

示例代码​

const user = auth.currentUser;

user
  .update({
    nickName: "王小黑", // 昵称，不超过 45 个字符
    gender: "MALE", // 性别，取值仅限于 MALE、FEMALE、UNKNOWN
    avatarUrl: "https://...", // 头像地址，不超过 255 个字符
    country: "中国", // 不超过 45 个字符
    province: "广东", // 不超过 45 个字符
    city: "深圳" // 不超过 45 个字符
  })
  .then(() => {
    // 更新用户信息成功
  });

User.refresh()​

接口描述​

刷新本地用户信息。当用户在其他客户端更新用户信息之后，可以调用此接口同步更新之后的信息。

签名：refresh(): Promise<UserInfo>

示例代码​

const user = auth.currentUser;

user.refresh().then(() => {
  // 刷新用户信息成功
});

User.linkWithTicket()​

接口描述​

将当前账户与自定义登录 Ticket 进行绑定，绑定之后便可以通过自定义登录登录当前云开发账户。

签名：linkWithTicket(ticket: string): Promise<void>

示例代码​

const user = auth.currentUser;

// ticket 为获取到的自定义登录 Ticket
user.linkWithTicket(ticket).then(() => {
  // 绑定成功
});

User.linkWithRedirect()​

接口描述​

将当前账户与第三方鉴权提供方，以重定向的形式，进行绑定，绑定之后便可以通过第三方鉴权提供方登录当前的云开发账户。

签名：linkWithRedirect(provider: AuthProvider): void

示例代码​

以绑定微信登录为例：

const user = auth.currentUser;

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

user.linkWithRedirect(provider); // 调用之后，网页会被重定向至第三方登录页面

User.updatePassword()​

提示

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

接口描述​

修改密码。如果用户之前没有设置过密码，那么无需填写 oldPassword。

签名：updatePassword(newPassword: string, oldPassword?: string): Promise<void>

示例代码​

const user = auth.currentUser;
user.updatePassword("new_password", "old_password").then(() => {
  // 更新密码成功
});

User.updateEmail()​

提示

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

更新当前的登录邮箱，调用后会发送验证邮件到新邮箱，用户需要访问验证邮件中的激活链接来完成更新。

接口描述​

修改登录邮箱。

签名：updateEmail(newEmail: string): Promise<void>

示例代码​

const user = auth.currentUser;
user.updateEmail("new_email@foo.com").then(() => {
  // 发送验证邮件
});

User.updateUsername()​

提示

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

接口描述​

修改用户名。

签名：updateUsername(newUsername: string): Promise<void>

示例代码​

const user = auth.currentUser;
user.updateUsername("new_username").then(() => {
  // 修改成功
});

接口描述​

解绑某个登录方式。

签名：unlink(loginType): Promise<void>

loginType 取值含义
WECHAT-OPEN微信开放平台
WECHAT-PUBLIC微信公众平台
WECHAT-UNION微信 UnionID
CUSTOM自定义登录
EMAIL邮箱登录
注意

不能解绑当前登录方式

示例代码​

const user = auth.currentUser;

user.unlink("CUSTOM").then(() => {
  // 解绑自定义登录成功
});

WeixinAuthProvider​

WeixinAuthProvider.signIn()​

接口描述​

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

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

签名： signIn({ createUser?: boolean, syncUserInfo?: boolean }): Promise<LoginState>

参数名含义默认值
createUser当微信 openid 没有对应的云开发用户时，是否自动创建一个新的云开发用户true
syncUserInfo同步微信账号信息作为云开发用户信息false
注意

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

为什么无法同步微信账号信息？

当 syncUserInfo 为 true ，并且网页授权类型为 snsapi_userinfo 或者 snsapi_login 时，才可以同步微信账号信息作为云开发用户信息。

示例代码​

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

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

WeixinAuthProvider.signInWithRedirect()​

提示

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

接口描述​

跳转到微信登录页面。

建议

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

签名：signInWithRedirect(): void

示例代码​

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

WeixinAuthProvider.getRedirectResult()​

提示

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

接口描述​

微信登录页面重定向回来后，使用重定向的返回值登录，并获取登录态。

签名：getRedirectResult({ createUser?: boolean }): Promise<LoginState | null>

参数名含义默认值
createUser当微信 openid 没有对应的云开发用户时，是否自动创建一个新的云开发用户true
syncUserInfo同步微信账号信息作为云开发用户信息false
为什么无法同步微信账号信息？

当 syncUserInfo 为 true ，并且网页授权类型为 snsapi_userinfo 或者 snsapi_login 时，才可以同步微信账号信息作为云开发用户信息。

示例代码​

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

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

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

WeixinAuthProvider.getLinkRedirectResult()​

提示

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

接口描述​

获取微信重定向绑定结果。如果 withUnionId 为 true，且存在微信 UnionID，则会一同绑定微信 UnionID。

签名：getLinkRedirectResult({ withUnionId?: boolean }): Promise<void>

示例代码​

// 用户以任意一种登录方式（除微信登录）登录云开发之后

// 获取 Provider
const auth = app.auth();
const provider = auth.weixinAuthProvider({
  appid: "....",
  scope: "snsapi_base"
});

// 重定向到提供方的页面进行登录
auth.currentUser.linkWithRedirect(provider);

用户在微信的页面登录之后，会被重定向回您的页面。然后，可以在页面加载时通过调用 Provider.getLinkRedirectResult() 来获取关联结果：

provider.getLinkRedirectResult().then((result) => {
  // 关联成功
});

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) => {
    // 登录失败
  });