Dingyue

Appearance

用户认证 ​

DingYue WEB SDK 支持多种用户认证方式，包括邮箱密码注册/登录和 OAuth 第三方登录。

用户注册 ​

注册新用户并自动登录。

javascript
try {
  const response = await sdk.register({
    username: 'john_doe',
    email: 'john@example.com',
    password: 'SecurePass123!'
  });
  
  console.log('注册成功，用户 ID:', response.user.userId);
  console.log('Token 过期时间:', new Date(response.token.expiresAt));
  // Token 已自动保存到本地存储
} catch (error) {
  console.error('注册失败:', error.message);
  // error.code: 'INVALID_REQUEST' | 'USER_EXISTS' | 'NETWORK_ERROR'
}

参数说明 ​

参数类型必填说明
usernamestring是用户名
emailstring是邮箱地址
passwordstring是密码

返回值 ​

javascript
{
  user: {
    userId: string;
    email: string;
    username: string;
    createdTime: number;
    updatedTime: number;
    status: 'ACTIVE' | 'INACTIVE' | 'BANNED';
  };
  token: {
    token: string;              // JWT Token 字符串
    userId: string;
    expiresAt: number;          // 过期时间戳（毫秒）
    tokenType: 'Bearer';
  };
}

用户登录 ​

使用邮箱和密码登录。

javascript
try {
  const response = await sdk.login({
    email: 'john@example.com',
    password: 'SecurePass123!'
  });
  
  console.log('登录成功，欢迎', response.user.username);
  // Token 已自动保存，后续请求会自动携带
} catch (error) {
  if (error.code === 'INVALID_CREDENTIALS') {
    console.error('邮箱或密码错误');
  } else if (error.code === 'USER_NOT_FOUND') {
    console.error('用户不存在');
  } else {
    console.error('登录失败:', error.message);
  }
}

参数说明 ​

参数类型必填说明
emailstring是邮箱地址
passwordstring是密码

返回值 ​

同 register() 的返回值。

OAuth 第三方登录 ​

使用第三方 OAuth 提供商登录（Google、Microsoft、Apple）。

Google 登录示例 ​

javascript
async function handleGoogleLogin() {
  try {
    // 1. 使用 Google SDK 获取授权（需要先集成 Google Sign-In）
    const googleResponse = await gapi.auth2.getAuthInstance().signIn();
    const profile = googleResponse.getBasicProfile();
    
    // 2. 调用 DingYue SDK 登录
    const response = await sdk.loginWithOAuth({
      provider: 'google',
      accessToken: googleResponse.getAuthResponse().id_token,
      providerUserInfo: {
        id: profile.getId(),
        email: profile.getEmail(),
        name: profile.getName(),
        picture: profile.getImageUrl()
      }
    });
    
    console.log('Google 登录成功:', response.user);
  } catch (error) {
    console.error('Google 登录失败:', error.message);
  }
}

Microsoft 登录示例 ​

javascript
async function handleMicrosoftLogin() {
  try {
    // 使用 MSAL 获取授权
    const msalResponse = await msalInstance.acquireTokenPopup({
      scopes: ['User.Read']
    });
    const account = msalInstance.getActiveAccount();
    
    const response = await sdk.loginWithOAuth({
      provider: 'microsoft',
      accessToken: msalResponse.accessToken,
      providerUserInfo: {
        id: account.homeAccountId,
        email: account.username,
        name: account.name,
        picture: account.idTokenClaims?.picture
      }
    });
    
    console.log('Microsoft 登录成功:', response.user);
  } catch (error) {
    console.error('Microsoft 登录失败:', error.message);
  }
}

Apple 登录示例 ​

javascript
async function handleAppleLogin() {
  try {
    // 使用 Apple Sign In 获取授权
    const appleResponse = await handleAppleSignIn();
    
    const response = await sdk.loginWithOAuth({
      provider: 'apple',
      accessToken: appleResponse.identityToken,
      providerUserInfo: {
        id: appleResponse.user.sub,
        email: appleResponse.user.email,
        name: `${appleResponse.user.name?.firstName || ''} ${appleResponse.user.name?.lastName || ''}`.trim(),
        picture: null  // Apple 不提供头像
      }
    });
    
    console.log('Apple 登录成功:', response.user);
  } catch (error) {
    console.error('Apple 登录失败:', error.message);
  }
}

OAuth 参数说明 ​

参数类型必填说明
providerstring是提供商：'google' | 'microsoft' | 'apple'
accessTokenstring是OAuth access token
refreshTokenstring否Refresh token
tokenExpirynumber否Token 过期时间戳
providerUserInfoobject是第三方用户信息
providerUserInfo.idstring是第三方用户 ID
providerUserInfo.emailstring是邮箱
providerUserInfo.namestring否用户名
providerUserInfo.picturestring否头像 URL

支持的提供商 ​

提供商provider 值说明
Google'google'需要集成 Google Sign-In SDK
Microsoft'microsoft'需要集成 Azure AD / MSAL SDK
Apple'apple'需要集成 Sign in with Apple

注意事项 ​

  • 注册成功后，Token 会自动保存到 localStorage
  • 登录成功后，Token 会自动保存到 localStorage
  • 页面刷新后，Token 会自动从 localStorage 恢复
  • Token 有效期为 7 天（由服务器决定）
  • 如果邮箱已存在，注册会抛出 USER_EXISTS 错误
  • SDK 会自动添加设备信息（uniqueUser 对象）
  • OAuth 登录时，如果用户不存在，服务器会自动创建新用户

Copyright © 2025 Dingyue