更新记录

1.1.5（2026-09-15）

更新 插件信息

1.1.4（2026-08-26）

新增 授权API

1.1.3（2026-06-05）

更新插件信息

平台兼容性

uni-app(4.76)

uni-app x(4.76)

tt-google-signin

🚀 Google 登录与授权插件，为 uni-app x 和 uni-app 提供 Google 身份认证及 Google API scopes 授权能力。

📖 目录

• SDK 版本信息
• 重要提示
• 环境配置
• 快速开始
• 功能介绍
  • Google 登录认证
  • Google API 授权
  • Google 退出登录
• 错误处理
• 安全说明
• 常见问题

SDK 版本信息

功能支持矩阵

📚 推荐阅读：

• Google Sign-In iOS 集成文档
• Credential Manager Sign in with Google
• Google AuthorizationClient

🚨 重要提示

• ⚠️ 必须使用自定义基座运行，标准基座不包含本插件的原生依赖。
• ⚠️ login() 负责身份认证，authorize() 负责申请 Drive、Calendar 等 Google API 权限，请勿混为同一流程。
• ⚠️ 调用 authorize() 前，必须先在当前应用进程中成功调用一次 login()。
• ⚠️ Android 默认使用 Credential Manager；如需兼容旧版，可显式设置 useLegacyLogin: true。
• ⚠️ Legacy 不是无 GMS 或无法访问 Google 网络时的替代方案，新旧实现都依赖 Google 服务。
• ⚠️ ID Token 和授权码应发送到业务服务端处理，不应仅在客户端完成身份校验。

环境配置

前置条件

1. 在 Google Cloud Console 创建项目。
2. 配置 OAuth 同意屏幕，并启用业务所需的 Google API。
3. 创建 OAuth 2.0 客户端：
   • Web 客户端 ID：Android 获取 ID Token、server auth code 时使用。
   • Android 客户端 ID：配置应用包名和签名证书 SHA-1。
   • iOS 客户端 ID：配置 Bundle ID，并获取 iOS URL Scheme。
4. 测试签名与正式签名通常具有不同 SHA-1，必须分别配置。

iOS 平台配置

编辑 uni_modules/tt-google-signin/utssdk/app-ios/Info.plist，替换为实际配置：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>GIDClientID</key>
    <string>YOUR_IOS_CLIENT_ID.apps.googleusercontent.com</string>

    <!-- authorize() 需要 server auth code 时配置 Web 客户端 ID -->
    <key>GIDServerClientID</key>
    <string>YOUR_WEB_CLIENT_ID.apps.googleusercontent.com</string>

    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>YOUR_DOT_REVERSED_IOS_CLIENT_ID</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

配置说明：

• GIDClientID：iOS OAuth 客户端 ID。
• GIDServerClientID：可选；需要 server auth code 时填写 Web OAuth 客户端 ID。
• CFBundleURLSchemes：填写 Google Cloud Console 提供的 iOS URL Scheme。
• iOS 的 serverClientId API 参数不会覆盖 GIDServerClientID，实际配置仍以 Info.plist 为准。

Android 平台配置

Android 原生依赖由插件自动配置。业务侧需要确认：

• Google Cloud Console 中存在与应用包名一致的 Android OAuth 客户端。
• 当前打包证书的 SHA-1 已添加到 Android OAuth 客户端。
• 调用 login() 时传入的是 Web 客户端 ID，不是 Android 客户端 ID。
• 设备已安装可用的 Google Play 服务，并能访问 Google 服务。

快速开始

uni-app x

import * as googleSignin from "@/uni_modules/tt-google-signin";

const googleSDK = googleSignin.getTTGoogleSign();

在 Options API 页面中也可以保存实例：

export default {
    data() {
        return {
            googleSDK: null as googleSignin.TTGoogleSign | null
        }
    },
    onLoad() {
        this.googleSDK = googleSignin.getTTGoogleSign()
    },
    onUnload() {
        this.googleSDK = null
    }
}

uni-app

import * as googleSignin from "@/uni_modules/tt-google-signin";

export default {
    data() {
        return {
            googleSDK: null
        }
    },
    onLoad() {
        this.googleSDK = googleSignin.getTTGoogleSign()
    },
    onUnload() {
        this.googleSDK = null
    }
}

功能介绍

Google 登录认证

💡 login() 用于确认用户身份并获取 ID Token，不代表已经获得 Drive、Calendar 等 Google API scopes。

参数说明

TTGoogleLoginOptions

返回值 TTGoogleLoginSuccess

Android 新版登录行为

1. 默认使用 Credential Manager 查询已授权账号。
2. 没有已授权凭据时，再显示全部可用 Google 账号。
3. 用户主动取消时直接返回错误码 106，不会自动切换到 Legacy。
4. 如需 Legacy，必须由业务明确设置 useLegacyLogin: true。

uni-app x 示例

handleGoogleLogin() {
    this.googleSDK?.login({
        serverClientId: "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com",
        // 推荐由业务服务端生成，使用后立即作废
        nonce: null,
        success: (result) => {
            console.log("Google 登录成功");
            console.log("ID Token:", result.idToken);
            this.sendIdTokenToServer(result.idToken);
        },
        fail: (error) => {
            console.error("Google 登录失败:", error.errCode, error.errMsg);
        },
        complete: (_) => {}
    } as googleSignin.TTGoogleLoginOptions)
}

Android Legacy 示例

handleGoogleLegacyLogin() {
    this.googleSDK?.login({
        serverClientId: "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com",
        useLegacyLogin: true,
        success: (result) => {
            console.log("Legacy 登录成功:", result.idToken);
        },
        fail: (error) => {
            console.error("Legacy 登录失败:", error.errMsg);
        },
        complete: (_) => {}
    } as googleSignin.TTGoogleLoginOptions)
}

useLegacyLogin 在 iOS 上不会改变行为，iOS 始终使用 GoogleSignIn SDK。

Google API 授权

💡 authorize() 用于申请 Drive、Calendar 等额外 scopes。它与 login() 分离，必须在登录成功后调用。

参数说明

TTGoogleAuthorizeOptions

返回值 TTGoogleAuthorizeSuccess

普通 scopes 授权

handleGoogleAuthorize() {
    this.googleSDK?.authorize({
        scopes: [
            "https://www.googleapis.com/auth/drive.readonly"
        ],
        requestServerAuthCode: false,
        success: (result) => {
            console.log("已授权 scopes:", result.grantedScopes);
            console.log("Access Token:", result.accessToken);
        },
        fail: (error) => {
            console.error("Google 授权失败:", error.errCode, error.errMsg);
        },
        complete: (_) => {}
    } as googleSignin.TTGoogleAuthorizeOptions)
}

请求 server auth code

handleGoogleAuthorizeForServer() {
    this.googleSDK?.authorize({
        scopes: [
            "https://www.googleapis.com/auth/drive.readonly"
        ],
        requestServerAuthCode: true,
        serverClientId: "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com",
        success: (result) => {
            if (result.serverAuthCode != null) {
                // 立即发送到业务服务端兑换 token
                console.log("Server Auth Code:", result.serverAuthCode);
            }
        },
        fail: (error) => {
            console.error("Google 授权失败:", error.errMsg);
        },
        complete: (_) => {}
    } as googleSignin.TTGoogleAuthorizeOptions)
}

平台差异

• Android：使用 AuthorizationClient；请求授权码时使用传入的 serverClientId。
• iOS：使用当前用户的 addScopes；授权码从 GIDSignInResult.serverAuthCode 获取。
• iOS server auth code：除传入参数外，还必须在 Info.plist 配置正确的 GIDServerClientID。
• accessToken 和 serverAuthCode 都是可选结果，业务代码必须处理 null。

Google 退出登录

💡 logout() 清理插件维护的本地 Google 登录状态，不等同于撤销用户在 Google 账号中授予的全部权限。

参数说明

TTGoogleLogoutOptions

默认退出

handleGoogleLogout() {
    this.googleSDK?.logout({
        success: (_) => {
            console.log("Google 退出成功");
        },
        fail: (error) => {
            console.error("Google 退出失败:", error.errMsg);
        },
        complete: (_) => {}
    } as googleSignin.TTGoogleLogoutOptions)
}

Android Legacy 退出

handleGoogleLegacyLogout() {
    this.googleSDK?.logout({
        useLegacyLogout: true,
        serverClientId: "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com",
        success: (_) => {
            console.log("Legacy 退出成功");
        },
        fail: (error) => {
            console.error("Legacy 退出失败:", error.errMsg);
        },
        complete: (_) => {}
    } as googleSignin.TTGoogleLogoutOptions)
}

Legacy 登录应配合 Legacy 退出使用。iOS 会忽略 useLegacyLogout 和 serverClientId。

错误处理

错误码说明

错误处理示例

fail: (error) => {
    switch (error.errCode) {
        case 106:
            console.log("用户取消操作");
            break;
        case 302:
            console.log("操作正在进行，请勿重复点击");
            break;
        case 303:
            console.log("请先完成 Google 登录");
            break;
        default:
            console.error("Google 操作失败:", error.errCode, error.errMsg);
            break;
    }
}

安全说明

• 业务服务端必须验证 ID Token 的签名及 iss、aud、exp、sub。
• 使用 nonce 时，应由业务服务端生成一次性随机值，并在验证 ID Token 时核对。
• 不要信任客户端自行解析出的用户信息完成账号登录。
• server auth code 应立即发送到业务服务端兑换 token，不应记录完整内容或长期保存在客户端。
• Access Token、Refresh Token 和业务会话密钥不得写入公开日志。

常见问题

1. 找不到插件方法？

请确认使用自定义基座或云打包。标准基座不包含插件的原生 SDK。

2. Android 新版登录没有可用账号？

插件会先查询已授权账号，再尝试展示全部 Google 账号。仍失败时请检查：

• 设备是否存在 Google 账号并安装可用的 Google Play 服务。
• 应用包名和当前签名证书 SHA-1 是否正确。
• serverClientId 是否为 Web OAuth 客户端 ID。
• 设备网络是否能访问 Google 服务。

3. 国内设备上新版不好用，Legacy 是否一定可用？

不一定。Legacy 可以兼容部分 Credential Manager 行为差异，但仍依赖 GMS 和 Google 网络。业务应保留其他可用的账号登录方式，不能把 Legacy 当作无 GMS 环境的兜底。

4. iOS 登录或回调无响应？

检查 GIDClientID、Bundle ID、CFBundleURLSchemes 和 Google Cloud Console 中的 iOS OAuth 配置是否一致。

5. 为什么 login().accessToken 是 null？

login() 的稳定职责是返回 ID Token 完成身份认证。需要访问 Google API 时，应在登录后调用 authorize() 并处理其授权结果。

6. 为什么 serverAuthCode 是 null？

• 确认设置了 requestServerAuthCode: true。
• Android 确认传入正确的 Web 客户端 ID。
• iOS 确认 Info.plist 已配置 GIDServerClientID。
• Google SDK 仍可能不返回授权码，业务必须允许该字段为 null。

7. 可以自动从新版切换到 Legacy 吗？

插件不会在用户取消或新版失败后自动切换，以免出现重复弹窗和不可预测的账号选择。需要使用 Legacy 时，应由业务明确调用并设置 useLegacyLogin: true。

8. 如何验证 ID Token？

将 ID Token 发送到业务服务端，使用 Google 官方库验证签名和声明。不要仅调用客户端 JWT 解码后就建立业务会话。

📞 技术支持

遇到问题时请优先提供：

1. 平台、系统版本和设备型号。
2. HBuilderX 版本及自定义基座/云打包方式。
3. 插件错误码和完整 errMsg。
4. Android 包名、签名类型是否匹配；请勿公开私钥或敏感 token。
5. iOS Bundle ID 与 URL Scheme 是否匹配。

当前版本：1.2.0