更新记录

1.0.0（2026-03-15）

首次发布

• 发布 uni-app / uni-app x Google 登录插件。
• 支持 Android、iOS App 侧登录、恢复登录、退出登录与缓存读取。
• classic uni-app iOS 支持通过 handleRedirectURL() 手动转发 URL 回调。
• uni-app x iOS 支持通过 UTSiOSHookProxy 自动处理 URL 回调。
• Harmony / Web 当前为 stub 实现。

提供的接口

• signIn()：发起 Google 登录
• restoreSignIn()：恢复历史登录状态
• signOut()：退出登录并清理缓存
• getCachedUser()：同步获取缓存用户
• hasCachedUser()：同步判断是否存在缓存用户
• handleRedirectURL()：处理 iOS URL 回调

实现说明

• Android 基于 Credential Manager 与 Google Identity
• Android 无需 google-services.json
• iOS 基于 GoogleSignIn SDK

错误码

平台兼容性

uni-app(5.03)

uni-app x(5.03)

hans-google-auth

uni-app / uni-app x Google 登录插件。

安装

通过 HBuilderX 插件市场搜索 hans-google-auth 并导入到项目。

使用前准备

1. 在 Google Cloud Console 中创建 Android OAuth Client ID 和 iOS OAuth Client ID。
2. 额外创建一个 Web application 类型的 Client ID。
3. 插件里的 serverClientId 必须传这个 Web application Client ID。

iOS 配置

iOS 需要在应用侧 Info.plist 中配置：

<key>GIDClientID</key>
<string>YOUR_IOS_CLIENT_ID</string>
<key>GIDServerClientID</key>
<string>YOUR_SERVER_CLIENT_ID</string>
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>YOUR_REVERSED_CLIENT_ID</string>
    </array>
  </dict>
</array>

说明：

• GIDClientID 必填。
• GIDServerClientID 选填；如果配置，必须和运行时传入的 serverClientId 一致。
• YOUR_REVERSED_CLIENT_ID 一般形如 com.googleusercontent.apps.xxx。
• 当前仓库里的 utssdk/app-ios/Info.plist 是 playground 示例值，发布前应替换。

classic uni-app iOS 回调

classic uni-app 的 iOS 工程需要在 App.vue 中转发 URL 回调：

<script>
// #ifdef APP-PLUS
import { handleRedirectURL } from '@/uni_modules/hans-google-auth'
// #endif

export default {
  onLaunch() {
    // #ifdef APP-PLUS && APP-IOS
    plus.runtime.addEventListener('openURL', (e) => {
      const url = e.url || e.uri || e.argument
      if (url) {
        handleRedirectURL({
          url,
          complete: () => {}
        })
      }
    })

    const args = plus.runtime.arguments
    if (args) {
      handleRedirectURL({
        url: args,
        complete: () => {}
      })
    }
    // #endif
  }
}
</script>

快速使用

uni-app x

<script lang="uts">
import {
  signIn,
  signOut,
  restoreSignIn,
  getCachedUser,
  type GoogleUser,
  type GoogleAuthResult,
  type GoogleAuthFail,
  type GoogleSignInOptions,
  type GoogleRestoreSignInOptions,
  type GoogleSignOutOptions
} from '@/uni_modules/hans-google-auth'

export default {
  data() {
    return {
      currentUser: null as GoogleUser | null,
      lastError: null as GoogleAuthFail | null
    }
  },
  onLoad() {
    this.currentUser = getCachedUser()

    const restoreOptions: GoogleRestoreSignInOptions = {
      serverClientId: 'YOUR_SERVER_CLIENT_ID',
      success: (res: GoogleAuthResult) => {
        this.currentUser = res.user
      },
      fail: (err: GoogleAuthFail) => {
        this.lastError = err
      }
    }

    restoreSignIn(restoreOptions)
  },
  methods: {
    handleSignIn() {
      const signInOptions: GoogleSignInOptions = {
        serverClientId: 'YOUR_SERVER_CLIENT_ID',
        success: (res: GoogleAuthResult) => {
          this.currentUser = res.user
        },
        fail: (err: GoogleAuthFail) => {
          this.lastError = err
        }
      }

      signIn(signInOptions)
    },
    handleSignOut() {
      const signOutOptions: GoogleSignOutOptions = {
        success: () => {
          this.currentUser = null
        }
      }

      signOut(signOutOptions)
    }
  }
}
</script>

classic uni-app

<script>
// #ifdef APP-PLUS
import {
  signIn,
  signOut,
  restoreSignIn,
  getCachedUser
} from '@/uni_modules/hans-google-auth'
// #endif

export default {
  data() {
    return {
      currentUser: null
    }
  },
  onLoad() {
    // #ifdef APP-PLUS
    this.currentUser = getCachedUser()

    restoreSignIn({
      serverClientId: 'YOUR_SERVER_CLIENT_ID',
      success: (res) => {
        this.currentUser = res.user
      }
    })
    // #endif
  },
  methods: {
    handleSignIn() {
      // #ifdef APP-PLUS
      signIn({
        serverClientId: 'YOUR_SERVER_CLIENT_ID',
        success: (res) => {
          this.currentUser = res.user
        }
      })
      // #endif
    },
    handleSignOut() {
      // #ifdef APP-PLUS
      signOut({
        success: () => {
          this.currentUser = null
        }
      })
      // #endif
    }
  }
}
</script>

API

类型

type GoogleUser = {
  email: string
  displayName?: string
  givenName?: string
  familyName?: string
  avatarUrl?: string
}

type GoogleAuthResult = {
  idToken: string
  user: GoogleUser
}

interface GoogleAuthFail extends IUniError {
  errCode: 9010001 | 9010002 | 9010003 | 9010004 | 9010005 | 9010006 | 9010007 | 9010008 | 9010009
}

type GoogleSignInOptions = {
  serverClientId: string
  nonce?: string
  success?: (res: GoogleAuthResult) => void
  fail?: (err: GoogleAuthFail) => void
  complete?: (res: any) => void
}

type GoogleRestoreSignInOptions = GoogleSignInOptions

type GoogleSignOutOptions = {
  success?: () => void
  fail?: (err: GoogleAuthFail) => void
  complete?: () => void
}

signIn(options)

发起 Google 登录。

signIn({
  serverClientId: 'YOUR_SERVER_CLIENT_ID',
  nonce: 'optional-nonce',
  success: (res) => {
    console.log(res.idToken, res.user)
  },
  fail: (err) => {
    console.log(err.errCode, err.errMsg)
  }
})

restoreSignIn(options)

恢复历史登录状态。

restoreSignIn({
  serverClientId: 'YOUR_SERVER_CLIENT_ID',
  success: (res) => {
    console.log(res.user.email)
  }
})

signOut(options?)

退出登录并清理本地缓存。

signOut({
  success: () => {
    console.log('signed out')
  }
})

getCachedUser()

同步获取缓存用户。

const user = getCachedUser()

hasCachedUser()

同步判断是否存在缓存用户。

const hasUser = hasCachedUser()

setDebugEnabled(enabled)

开启或关闭插件内部调试日志。

setDebugEnabled(true)

isDebugEnabled()

获取当前调试日志状态。

const enabled = isDebugEnabled()

handleRedirectURL(options)

处理 iOS URL 回调，主要用于 classic uni-app。

错误码

注意事项

1. 从 @/uni_modules/hans-google-auth 导入，不要直接导入 utssdk 内部文件。
2. classic uni-app 建议把导入语句放在 #ifdef APP-PLUS 条件编译中。
3. serverClientId 必须传 Web application Client ID。
4. getCachedUser() 只返回本地缓存，不会主动向 Google 校验会话有效性。
5. Harmony / Web 当前为 stub 实现。