auth-web-cloudbase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overview

概述

Prerequisites: CloudBase environment ID (

env

) Prerequisites: CloudBase environment Region (

region

)

前提条件：CloudBase 环境 ID（

env

） 前提条件：CloudBase 环境区域（

region

）

Core Capabilities

核心能力

Use Case: Web frontend projects using

@cloudbase/js-sdk@2.24.0+

for user authentication
Key Benefits: Compatible with

supabase-js

API, supports phone, email, anonymous, username/password, and third-party login methods @cloudbase/js-sdk
cdn source:

https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js

适用场景：使用

@cloudbase/js-sdk@2.24.0+

进行用户认证的 Web 前端项目
核心优势：兼容

supabase-js

API，支持手机、邮箱、匿名、用户名/密码及第三方登录方式 @cloudbase/js-sdk
CDN 源：

https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js

Prerequisites

前提条件

Automatically use
```
auth-tool-cloudbase
```
to get
```
publishable key
```
and configure login methods.

auth-tool-cloudbase

failed, let user go to

https://tcb.cloud.tencent.com/dev?envId={env}#/env/apikey

to get

publishable key

and

https://tcb.cloud.tencent.com/dev?envId={env}#/identity/login-manage

to set up login methods

自动使用
```
auth-tool-cloudbase
```
获取
```
publishable key
```
并配置登录方式。

如果

auth-tool-cloudbase

调用失败，用户可前往

https://tcb.cloud.tencent.com/dev?envId={env}#/env/apikey

获取

publishable key

，并前往

https://tcb.cloud.tencent.com/dev?envId={env}#/identity/login-manage

设置登录方式

Quick Start

快速开始

import cloudbase from '@cloudbase/js-sdk'

const app = cloudbase.init({
  env: `env`, // CloudBase environment ID
  region: `region`,  // CloudBase environment Region, default 'ap-shanghai'
  accessKey: 'publishable key', // required, get from auth-tool-cloudbase
  auth: { detectSessionInUrl: true }, // required
})

const auth = app.auth
``

---

import cloudbase from '@cloudbase/js-sdk'

const app = cloudbase.init({
  env: `env`, // CloudBase environment ID
  region: `region`,  // CloudBase environment Region, default 'ap-shanghai'
  accessKey: 'publishable key', // required, get from auth-tool-cloudbase
  auth: { detectSessionInUrl: true }, // required
})

const auth = app.auth
``

---

Login Methods

登录方式

1. Phone OTP (Recommended)

Automatically use
```
auth-tool-cloudbase
```
turn on
```
SMS Login
```

const { data, error } = await auth.signInWithOtp({ phone: '13800138000' })
const { data: loginData, error: loginError } = await data.verifyOtp({ token:'123456' })

2. Email OTP

Automatically use
```
auth-tool-cloudbase
```
turn on
```
Email Login
```

const { data, error } = await auth.signInWithOtp({ email: 'user@example.com' })
const { data: loginData, error: loginError } = await data.verifyOtp({ token: '654321' })

3. Password

const { data, error } = await auth.signInWithPassword({ username: 'test_user', password: 'pass123' })
const { data, error } = await auth.signInWithPassword({ email: 'user@example.com', password: 'pass123' })
const { data, error } = await auth.signInWithPassword({ phone: '13800138000', password: 'pass123' })

4. Registration (Smart: auto-login if exists)

Only support email and phone otp registration
Automatically use
```
auth-tool-cloudbase
```
turn on
```
Email Login
```
or
```
SMS Login
```

// Email Otp
const { data, error } = await auth.signUp({ email: 'new@example.com', nickname: 'User' })
const { data: loginData, error: loginError } = await data.verifyOtp({ token: '123456' })

// Phone Otp
const { data, error } = await auth.signUp({ phone: '13800138000', nickname: 'User' })
const { data: loginData, error: loginError } = await data.verifyOtp({ token: '123456' })

5. Anonymous

Automatically use
```
auth-tool-cloudbase
```
turn on
```
Anonymous Login
```

const { data, error } = await auth.signInAnonymously()

6. OAuth (Google/WeChat)

Automatically use

auth-tool-cloudbase

turn on

Google Login

WeChat Login

const { data, error } = await auth.signInWithOAuth({ provider: 'google' })
window.location.href = data.url // Auto-complete after callback

7. Custom Ticket

await auth.signInWithCustomTicket(async () => {
  const res = await fetch('/api/ticket')
  return (await res.json()).ticket
})

8. Upgrade Anonymous

const { data, error } = await auth.getSession()
const { data: signUpData, error: signUpError} = await auth.signUp({
  phone: '13800000000',
  anonymous_token: data.session.access_token,
})
await signUpData.verifyOtp({ token: '123456' })

1. 手机验证码登录（推荐）

自动使用
```
auth-tool-cloudbase
```
开启「短信登录」

const { data, error } = await auth.signInWithOtp({ phone: '13800138000' })
const { data: loginData, error: loginError } = await data.verifyOtp({ token:'123456' })

2. 邮箱验证码登录

自动使用
```
auth-tool-cloudbase
```
开启「邮箱登录」

const { data, error } = await auth.signInWithOtp({ email: 'user@example.com' })
const { data: loginData, error: loginError } = await data.verifyOtp({ token: '654321' })

3. 密码登录

const { data, error } = await auth.signInWithPassword({ username: 'test_user', password: 'pass123' })
const { data, error } = await auth.signInWithPassword({ email: 'user@example.com', password: 'pass123' })
const { data, error } = await auth.signInWithPassword({ phone: '13800138000', password: 'pass123' })

4. 用户注册（智能：若已存在则自动登录）

仅支持邮箱和手机验证码注册
自动使用
```
auth-tool-cloudbase
```
开启「邮箱登录」或「短信登录」

// Email Otp
const { data, error } = await auth.signUp({ email: 'new@example.com', nickname: 'User' })
const { data: loginData, error: loginError } = await data.verifyOtp({ token: '123456' })

// Phone Otp
const { data, error } = await auth.signUp({ phone: '13800138000', nickname: 'User' })
const { data: loginData, error: loginError } = await data.verifyOtp({ token: '123456' })

5. 匿名登录

自动使用
```
auth-tool-cloudbase
```
开启「匿名登录」

const { data, error } = await auth.signInAnonymously()

6. 第三方授权登录（Google/微信）

自动使用
```
auth-tool-cloudbase
```
开启「Google登录」或「微信登录」

const { data, error } = await auth.signInWithOAuth({ provider: 'google' })
window.location.href = data.url // Auto-complete after callback

7. 自定义票据登录

await auth.signInWithCustomTicket(async () => {
  const res = await fetch('/api/ticket')
  return (await res.json()).ticket
})

8. 匿名账号升级

const { data, error } = await auth.getSession()
const { data: signUpData, error: signUpError} = await auth.signUp({
  phone: '13800000000',
  anonymous_token: data.session.access_token,
})
await signUpData.verifyOtp({ token: '123456' })

User Management

用户管理

// Sign out
const { data, error } = await auth.signOut()

// Get user
const { data, error } = await auth.getUser()
console.log(data.user.email, data.user.phone, data.user.user_metadata?.nickName)

// Update user (except email, phone)
const { data, error } = await auth.updateUser({ nickname: 'New Name', gender: 'MALE', avatar_url: 'url' })

// Update user (email or phone)
const { data, error } = await auth.updateUser({ email: 'new@example.com' })
const { data, error } = await data.verifyOtp({ email: "new@example.com", token: "123456" });

// Change password (logged in)
const { data, error } = await auth.resetPasswordForOld({ old_password: 'old', new_password: 'new' })

// Reset password (forgot)
const { data, error } = await auth.reauthenticate()
const { data, error } = await data.updateUser({ nonce: '123456', password: 'new' })

// Link third-party
const { data, error } = await auth.linkIdentity({ provider: 'google' })

// View/Unlink identities
const { data, error } = await auth.getUserIdentities()
const { data, error } = await auth.unlinkIdentity({ provider: data.identities[0].id })

// Delete account
const { data, error } = await auth.deleteMe({ password: 'current' })

// Listen to state changes
const { data, error } = auth.onAuthStateChange((event, session, info) => {
  // INITIAL_SESSION, SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED, PASSWORD_RECOVERY, BIND_IDENTITY
})

// Get access token
const { data, error } = const { data, error } = await auth.getSession()
fetch('/api/protected', { headers: { Authorization: `Bearer ${data.session?.access_token}` } })

// Refresh user
const { data, error } = await auth.refreshUser()

// Sign out
const { data, error } = await auth.signOut()

// Get user
const { data, error } = await auth.getUser()
console.log(data.user.email, data.user.phone, data.user.user_metadata?.nickName)

// Update user (except email, phone)
const { data, error } = await auth.updateUser({ nickname: 'New Name', gender: 'MALE', avatar_url: 'url' })

// Update user (email or phone)
const { data, error } = await auth.updateUser({ email: 'new@example.com' })
const { data, error } = await data.verifyOtp({ email: "new@example.com", token: "123456" });

// Change password (logged in)
const { data, error } = await auth.resetPasswordForOld({ old_password: 'old', new_password: 'new' })

// Reset password (forgot)
const { data, error } = await auth.reauthenticate()
const { data, error } = await data.updateUser({ nonce: '123456', password: 'new' })

// Link third-party
const { data, error } = await auth.linkIdentity({ provider: 'google' })

// View/Unlink identities
const { data, error } = await auth.getUserIdentities()
const { data, error } = await auth.unlinkIdentity({ provider: data.identities[0].id })

// Delete account
const { data, error } = await auth.deleteMe({ password: 'current' })

// Listen to state changes
const { data, error } = auth.onAuthStateChange((event, session, info) => {
  // INITIAL_SESSION, SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED, PASSWORD_RECOVERY, BIND_IDENTITY
})

// Get access token
const { data, error } = await auth.getSession()
fetch('/api/protected', { headers: { Authorization: `Bearer ${data.session?.access_token}` } })

// Refresh user
const { data, error } = await auth.refreshUser()

User Type

用户类型

declare type User = {
  id: any
  aud: string
  role: string[]
  email: any
  email_confirmed_at: string
  phone: any
  phone_confirmed_at: string
  confirmed_at: string
  last_sign_in_at: string
  app_metadata: {
    provider: any
    providers: any[]
  }
  user_metadata: {
    name: any
    picture: any
    username: any
    gender: any
    locale: any
    uid: any
    nickName: any
    avatarUrl: any
    location: any
    hasPassword: any
  }
  identities: any
  created_at: string
  updated_at: string
  is_anonymous: boolean
}

declare type User = {
  id: any
  aud: string
  role: string[]
  email: any
  email_confirmed_at: string
  phone: any
  phone_confirmed_at: string
  confirmed_at: string
  last_sign_in_at: string
  app_metadata: {
    provider: any
    providers: any[]
  }
  user_metadata: {
    name: any
    picture: any
    username: any
    gender: any
    locale: any
    uid: any
    nickName: any
    avatarUrl: any
    location: any
    hasPassword: any
  }
  identities: any
  created_at: string
  updated_at: string
  is_anonymous: boolean
}

Complete Example

完整示例

class PhoneLoginPage {
  async sendCode() {
    const phone = document.getElementById('phone').value
    if (!/^1[3-9]\d{9}$/.test(phone)) return alert('Invalid phone')

    const { data, error } = await auth.signInWithOtp({ phone })
    if (error) return alert('Send failed: ' + error.message)

    this.verifyFunction = data.verify
    document.getElementById('codeSection').style.display = 'block'
    this.startCountdown(60)
  }

  async verifyCode() {
    const code = document.getElementById('code').value
    if (!code) return alert('Enter code')

    const { data, error } = await this.verifyFunction(code)
    if (error) return alert('Verification failed: ' + error.message)

    console.log('Login successful:', data.user)
    window.location.href = '/dashboard'
  }

  startCountdown(seconds) {
    let countdown = seconds
    const btn = document.getElementById('resendBtn')
    btn.disabled = true

    const timer = setInterval(() => {
      countdown--
      btn.innerText = `Resend in ${countdown}s`
      if (countdown <= 0) {
        clearInterval(timer)
        btn.disabled = false
        btn.innerText = 'Resend'
      }
    }, 1000)
  }
}

class PhoneLoginPage {
  async sendCode() {
    const phone = document.getElementById('phone').value
    if (!/^1[3-9]\d{9}$/.test(phone)) return alert('Invalid phone')

    const { data, error } = await auth.signInWithOtp({ phone })
    if (error) return alert('Send failed: ' + error.message)

    this.verifyFunction = data.verify
    document.getElementById('codeSection').style.display = 'block'
    this.startCountdown(60)
  }

  async verifyCode() {
    const code = document.getElementById('code').value
    if (!code) return alert('Enter code')

    const { data, error } = await this.verifyFunction(code)
    if (error) return alert('Verification failed: ' + error.message)

    console.log('Login successful:', data.user)
    window.location.href = '/dashboard'
  }

  startCountdown(seconds) {
    let countdown = seconds
    const btn = document.getElementById('resendBtn')
    btn.disabled = true

    const timer = setInterval(() => {
      countdown--
      btn.innerText = `Resend in ${countdown}s`
      if (countdown <= 0) {
        clearInterval(timer)
        btn.disabled = false
        btn.innerText = 'Resend'
      }
    }, 1000)
  }
}

WeChat Mini Program

微信小程序

// Silent login with OpenID
const { data, error } = await auth.signInWithOpenId() // WeChat Cloud mode (default)
const { data, error } = await auth.signInWithOpenId({ useWxCloud: false }) // HTTP mode

// Phone authorization login
const { data, error } = await auth.signInWithPhoneAuth({ phoneCode: 'xxx' })

// Silent login with OpenID
const { data, error } = await auth.signInWithOpenId() // WeChat Cloud mode (default)
const { data, error } = await auth.signInWithOpenId({ useWxCloud: false }) // HTTP mode

// Phone authorization login
const { data, error } = await auth.signInWithPhoneAuth({ phoneCode: 'xxx' })