更新记录

1.0.1（2025-11-05）

移除无用的参数

1.0.0（2025-11-05）

支持 Android、iOS授权登录

平台兼容性

uni-app(4.76)

uni-app x(4.76)

tt-google-signin

🚀 Google 授权登录插件，为 uni-app x & uni-app 提供完整的 Google Sign-In 集成解决方案

📖 目录

• SDK版本信息
• 环境配置
• 快速开始
• 功能介绍
  • Google 授权登录
  • Google 退出登录
• 错误处理
• 常见问题

SDK版本信息

功能支持矩阵

📚 推荐阅读:

• Google Sign-In iOS 集成文档
• Google Sign-In Android 集成文档

🚨 重要提示

⚠️ 必须使用自定义基座运行，否则无法找到插件方法
⚠️ Android: 确保设备已安装 Google Play 服务（GMS），否则登录可能失败
⚠️ Android: 确保应用签名与 Google Cloud Console 配置的签名一致
⚠️ iOS: 确保在 Google Cloud Console 正确配置了 iOS 客户端 ID 和 URL Scheme
⚠️ 编译报错排查：本插件会定期更新至最新版SDK，某些情况下编译报错可能不是插件不可用，而是本地环境问题或与官方插件冲突，遇到此类情况可通过IM联系我协助解决

环境配置

前置条件

1. 在 Google Cloud Console 创建项目
2. 启用 Google Sign-In API
3. 创建 OAuth 2.0 客户端 ID：
   • Android: 配置应用包名和 SHA-1 证书指纹
   • iOS: 配置 Bundle ID 和 URL Scheme

iOS平台配置

1. 配置 Info.plist

编辑插件内的 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</string>
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>YOUR_DOT_REVERSED_IOS_CLIENT_ID</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

配置说明：

• YOUR_IOS_CLIENT_ID: 替换为您的 iOS OAuth 客户端 ID（格式：***-abcdefg.apps.googleusercontent.com）
• YOUR_DOT_REVERSED_IOS_CLIENT_ID: 替换为反向的客户端 ID（格式：com.googleusercontent.apps.123456789-abcdefg）
  • 反向客户端 ID：将客户端 ID 中的点（.）分隔的字段按相反顺序排列
  • 例如：***-abcdefg.apps.googleusercontent.com → com.googleusercontent.apps.123456789-abcdefg
  • 在 Google Cloud Console 的 iOS OAuth 客户端详情页面可以找到 "iOS URL Scheme"

Android平台配置

Android平台会自动完成相关配置，确保在 Google Cloud Console 正确配置应用包名和 SHA-1 证书指纹即可。

重要提示：

• 确保在 Google Cloud Console 创建了 Android OAuth 客户端 ID
• 配置正确的应用包名
• 配置正确的 SHA-1 证书指纹（用于签名验证）
• 使用自定义基座时，确保使用正确的签名证书

快速开始

1. 导入插件

uni-app x 版本

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

export default {
    data() {
        return {
            googleSDK: null as googleSignin.TTGoogleSign | null,
        }
    },
    onLoad() {
        // 初始化Google Sign SDK实例
        this.googleSDK = googleSignin.getTTGoogleSign()
    },
    onUnload() {
        // 页面销毁释放实例
        this.googleSDK = null
    },
    methods: {
        // 使用SDK功能
    }
}

uni-app 版本

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

export default {
    data() {
        return {
            googleSDK: null,
        }
    },
    onLoad() {
        // 初始化Google Sign SDK实例
        this.googleSDK = googleSignin.getTTGoogleSign()
    },
    onUnload() {
        // 页面销毁释放实例
        this.googleSDK = null
    },
    methods: {
        // 使用SDK功能
    }
}

功能介绍

Google 授权登录

💡 Google 登录使用 OAuth 2.0 协议，登录成功后会返回 ID Token 和 Access Token，可用于验证用户身份和访问 Google API

参数说明

TTGoogleLoginOptions

返回值 TTGoogleLoginSuccess

行为说明

• 登录成功必然返回 idToken（用于验证用户身份）
• accessToken 在 iOS 平台通常可用，Android 平台可能为 null（取决于 Credential Manager 实现）
• 用户信息字段（userID/name/pictureURL/email）在权限允许且平台可获取时返回
• 建议使用 idToken 在后端验证用户身份，而不是依赖 accessToken

示例代码

uni-app x 版本

// Google 授权登录
handleGoogleLogin() {
    this.googleSDK?.login({
        serverClientId: "YOUR_SERVER_CLIENT_ID.apps.googleusercontent.com", // 必填：Google Web 客户端 ID
        success: (result) => {
            console.log("✅ Google登录成功");
            console.log("ID Token:", result.idToken.substring(0, 50) + "...");
            if (result.accessToken != null) {
                console.log("Access Token:", result.accessToken.substring(0, 50) + "...");
            }
            if (result.userID != null) {
                console.log("用户ID:", result.userID);
            }
            if (result.name != null) {
                console.log("用户名:", result.name);
            }
            if (result.email != null) {
                console.log("邮箱:", result.email);
            }

            // 将 ID Token 发送到后端服务器进行验证
            this.sendIdTokenToServer(result.idToken)
        },
        fail: (error) => {
            console.error("❌ Google登录失败:", error);
            uni.showToast({
                title: error.errMsg || '登录失败',
                icon: 'error'
            })
        },
        complete: (res) => {
            console.log("登录完成", res);
        }
    } as googleSignin.TTGoogleLoginOptions)
}

// 发送 ID Token 到后端服务器
sendIdTokenToServer(idToken: string) {
    uni.request({
        url: 'https://your-server.com/api/google/login',
        method: 'POST',
        data: { idToken },
        success: (res) => {
            // 处理登录成功逻辑
            console.log('登录成功:', res.data)
        },
        fail: (err) => {
            console.error('登录请求失败:', err)
        }
    })
}

uni-app 版本

// Google 授权登录
handleGoogleLogin() {
    this.googleSDK.login({
        serverClientId: "YOUR_SERVER_CLIENT_ID.apps.googleusercontent.com", // 必填：Google Web 客户端 ID
        success: (result) => {
            console.log("✅ Google登录成功");
            console.log("ID Token:", result.idToken.substring(0, 50) + "...");

            // 将 ID Token 发送到后端服务器进行验证
            this.sendIdTokenToServer(result.idToken)
        },
        fail: (error) => {
            console.error("❌ Google登录失败:", error);
            uni.showToast({
                title: error.errMsg || '登录失败',
                icon: 'error'
            })
        },
        complete: (res) => {
            console.log("登录完成", res);
        }
    })
}

// 发送 ID Token 到后端服务器
sendIdTokenToServer(idToken) {
    uni.request({
        url: 'https://your-server.com/api/google/login',
        method: 'POST',
        data: { idToken },
        success: (res) => {
            console.log('登录成功:', res.data)
        },
        fail: (err) => {
            console.error('登录请求失败:', err)
        }
    })
}

Google 退出登录

💡 退出当前 Google 账户登录状态

参数说明

TTGoogleLogoutOptions

返回值 TTGoogleLogoutSuccess

空对象，表示退出登录成功

示例代码

uni-app x 版本

// Google 退出登录
handleGoogleLogout() {
    this.googleSDK?.logout({
        success: (result) => {
            console.log("✅ Google退出登录成功");
            uni.showToast({
                title: '退出登录成功',
                icon: 'success'
            })
        },
        fail: (error) => {
            console.error("❌ Google退出登录失败:", error);
            uni.showToast({
                title: error.errMsg || '退出登录失败',
                icon: 'error'
            })
        },
        complete: (res) => {
            console.log("退出登录完成", res);
        }
    } as googleSignin.TTGoogleLogoutOptions)
}

uni-app 版本

// Google 退出登录
handleGoogleLogout() {
    this.googleSDK.logout({
        success: (result) => {
            console.log("✅ Google退出登录成功");
            uni.showToast({
                title: '退出登录成功',
                icon: 'success'
            })
        },
        fail: (error) => {
            console.error("❌ Google退出登录失败:", error);
            uni.showToast({
                title: error.errMsg || '退出登录失败',
                icon: 'error'
            })
        },
        complete: (res) => {
            console.log("退出登录完成", res);
        }
    })
}

错误处理

错误码说明

错误处理示例

handleGoogleLogin() {
    this.googleSDK?.login({
        serverClientId: "YOUR_SERVER_CLIENT_ID.apps.googleusercontent.com",
        success: (result) => {
            // 登录成功处理
        },
        fail: (error) => {
            // 根据错误码进行不同处理
            switch(error.errCode) {
                case 101:
                    console.error("系统环境错误，请检查应用状态");
                    break;
                case 104:
                    console.error("无法找到凭据，请检查应用签名和包名配置");
                    break;
                case 105:
                    console.error("登录组件缺失，请确保设备已安装 Google Play 服务");
                    uni.showModal({
                        title: '提示',
                        content: '请先安装 Google Play 服务',
                        showCancel: false
                    });
                    break;
                case 106:
                    console.log("用户取消登录");
                    break;
                case 108:
                    console.error("登录结果为空");
                    break;
                case 109:
                    console.error("用户信息为空");
                    break;
                case 110:
                    console.error("缺少ID Token");
                    break;
                case 202:
                    console.error("用户未登录");
                    break;
                case 999:
                    console.error("未知错误:", error.errMsg);
                    break;
            }
        },
        complete: (res) => {
            console.log("登录完成", res);
        }
    } as googleSignin.TTGoogleLoginOptions)
}

常见问题

1. 找不到插件方法？

解决方案: 确保使用自定义基座运行，标准基座不包含原生插件。

2. iOS平台登录无响应？

解决方案:

• 检查 uni_modules/tt-google-signin/utssdk/app-ios/Info.plist 中的配置：
  • GIDClientID 是否正确配置
  • CFBundleURLSchemes 中的反向客户端 ID 是否正确
• 确认 Google Cloud Console 中的 iOS 客户端配置正确
• 验证 Bundle ID 是否匹配

3. Android平台登录失败？

解决方案:

• 确认设备已安装 Google Play 服务（GMS）
• 确认应用签名与 Google Cloud Console 配置的 SHA-1 证书指纹一致
• 检查包名是否正确
• 验证 serverClientId 参数是否正确（Web 客户端 ID）

4. 提示"无法找到对应的凭据"（错误码 104）？

解决方案:

• Android:
  • 检查应用包名是否与 Google Cloud Console 中配置的一致
  • 检查 SHA-1 证书指纹是否匹配（注意：开发环境和生产环境使用不同签名）
  • 确保在 Google Cloud Console 创建了 Android OAuth 客户端 ID
• 网络问题: 确保设备可以访问 Google 服务

5. 提示"登录组件缺失"（错误码 105）？

解决方案:

• Android: 确保设备已安装 Google Play 服务（GMS）
  • 国内设备可能没有 GMS，需要用户手动安装或使用其他登录方式
  • 可以通过 Google Play Store 检查 GMS 是否可用

6. iOS 提示"配置错误"（错误码 102）？

解决方案:

• 检查 Info.plist 中的 GIDClientID 是否正确
• 检查 CFBundleURLSchemes 中的反向客户端 ID 格式是否正确
• 确保在 Google Cloud Console 创建了 iOS OAuth 客户端 ID
• 验证反向客户端 ID 的计算是否正确（将客户端 ID 的字段按相反顺序排列）

7. accessToken 为 null？

解决方案:

• 这是正常现象，Android 平台的 Credential Manager 可能不返回 accessToken
• 建议使用 idToken 在后端验证用户身份
• 如需访问 Google API，可以在后端使用 idToken 或通过 OAuth 2.0 流程获取 accessToken

8. 如何获取反向客户端 ID？

解决方案:

• 在 Google Cloud Console 的 iOS OAuth 客户端详情页面，可以找到 "iOS URL Scheme"
• 该值即为反向客户端 ID，直接复制使用即可
• 手动计算：将客户端 ID（如 ***-abcdefg.apps.googleusercontent.com）按点分隔，然后反序排列：com.googleusercontent.apps.123456789-abcdefg

9. 如何验证 ID Token？

解决方案:

• 在后端使用 Google 的 Token 验证 API 验证 ID Token
• 验证 ID Token 的签名和有效期
• 提取用户信息（sub、email、name 等）
• 参考：Google ID Token 验证文档

📞 技术支持

如果在使用过程中遇到问题，请：

1. 查阅上方常见问题
2. 参考 Google 官方开发文档
3. 检查配置是否正确
4. 确认 Google Cloud Console 配置

祝您开发愉快！ 🎉