# 登录认证

# 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.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

字段 类型 必填 说明
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", () => {
  // 此时登录态已经失效
});

# 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.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) // 调用之后,网页会被重定向至第三方登录页面

# 接口描述

解绑某个登录方式。

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

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

注意

不能解绑当前登录方式

# 示例代码

const user = auth.currentUser

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

# WeixinAuthProvider

# WeixinAuthProvider.signIn()

# 接口描述

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

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

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

参数名 含义 默认值
createUser 当微信 openid 没有对应的云开发用户时,是否自动创建一个新的云开发用户 true

注意

此接口将会在下个主版本废弃,推荐使用 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({ createUser?: boolean }): Promise<LoginState | null>

参数名 含义 默认值
createUser 当微信 openid 没有对应的云开发用户时,是否自动创建一个新的云开发用户 true

# 示例代码

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

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

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

# WeixinAuthProvider.getLinkRedirectResult()

提示

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

# 接口描述

获取微信重定向绑定结果。如果 withUnionIdtrue,且存在微信 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 => {
    // 登录失败
  });