更新记录

1.0.1（2026-07-24）

更新插件信息

1.0.0（2026-07-24）

Google、Apple授权登录，支持 Android、iOS

平台兼容性

uni-app(5.15)

uni-app x(5.15)

dd-google-login 配置与调用说明

本文档基于当前插件源码和项目现有接入方式整理，适用于 uni_modules/dd-google-login。

1. 插件结论

• 插件类型：UTS 原生插件
• 支持平台：uni-app / uni-app x 的 App-Android、App-iOS
• 不支持平台：H5、各类小程序、Harmony
• HBuilderX 要求：>= 5.15
• Android 最低版本：minSdkVersion 21
• iOS 最低版本：deploymentTarget 13.0

2. 插件能力

• Android：仅支持 Google 登录
• iOS：支持 Google 登录和 Apple 登录
• 对外导出 3 个方法：
  • login(options)
  • logout(options)
  • checkProviderAvailability(options)

3. 配置要求

3.1 Android Google 登录

• 在 Google Cloud Console 创建项目
• 启用 Google Sign-In API
• 在 Google Cloud Console 配好 Android / iOS / Web 三类 Client ID
• 创建 OAuth 2.0 客户端 ID：
  • Android: 配置应用包名和 SHA-1 证书指纹
  • iOS: 配置 Bundle ID 和 URL Scheme
• 设备必须可用 Google Play 服务，否则会返回 9205107
• login 时必须传 serverClientId，否则会返回 9205103
• serverClientId 应配置为 Google Cloud Console 中的 Web Client ID，通常是 xxxxxx.apps.googleusercontent.com, 而不是 Android Client ID。
• Google Cloud Console 里仍需为 Android 应用配置包名和 SHA-1 / SHA-256

3.2 iOS Google 登录

iOS 端有两类 Google 配置，含义不要混淆。

A. 原生 SDK 配置

插件通过 Bundle.main 读取 GIDClientID，所以必须在 utssdk/app-ios/Info.plist 中配置：

<key>GIDClientID</key>
<string>你的 iOS Client ID</string>
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>你的反转 URL Scheme</string>
    </array>
  </dict>
</array>

• GIDClientID：Google Cloud Console 中的 iOS Client ID,通常是 xxxxxx.apps.googleusercontent.com
• CFBundleURLSchemes：通常是 com.googleusercontent.apps.xxxxxx

B. 运行时 serverClientId

Google登录调用 ddGoogleLogin.login({ provider: 'google' }) 时，还要额外传 serverClientId。

• 这个字段用的 Web Client ID
• iOS端使用Google登录时也需要传入serverClientId，值是 Google Cloud Console 中的 iOS Client ID
• 如果不传，会返回 9205103

3.3 iOS Apple 登录

• 插件已自带 Sign in with Apple capability，见 utssdk/app-ios/UTS.entitlements
• iOS 仅在 13.0+ 可用
• 打正式包前，Apple Developer 后台对应的 App ID 也要启用 Sign in with Apple
• 使用apple登录时——login({ provider: 'apple' }) 不需要 serverClientId
• nonce 可选，服务端如果需要做重放保护，建议由后端生成后下发

4. 调用方式

4.1 导入

import * as ddGoogleLogin from '@/uni_modules/dd-google-login'

建议只在 APP-PLUS 环境使用：

// #ifdef APP-PLUS
// 调用插件
// #endif

4.2 检查 provider 是否可用

ddGoogleLogin.checkProviderAvailability({
  provider: 'google',
  success: (result) => {
    console.log('available:', result.available)
    console.log('platform:', result.platform)
    console.log('reason:', result.reason || '')
  },
  fail: (error) => {
    console.log(error)
  }
})

返回结构：

{
  provider: 'google',
  available: true,
  platform: 'android',
  reason: ''
}

常见结果：

• Android google：检查 Google Play 服务和页面上下文
• Android apple：固定返回不可用
• iOS google：检查页面上下文和 GIDClientID 是否存在
• iOS apple：检查页面上下文和系统版本

4.3 Google 登录

推荐写法：

const GOOGLE_SERVER_CLIENT_ID = '你的 Web Client ID' // ios平台需要使用Google Cloud Console 中的 `iOS Client ID`

function loginWithGoogle() {
  ddGoogleLogin.checkProviderAvailability({
    provider: 'google',
    success: (availability) => {
      if (!availability.available) {
        console.log('google unavailable:', availability.reason)
        return
      }

      ddGoogleLogin.login({
        provider: 'google',
        serverClientId: GOOGLE_SERVER_CLIENT_ID,
        useLegacyGoogle: true,
        success: (result) => {
          console.log('login success:', result)
        },
        fail: (error) => {
          console.log('login fail:', error)
        }
      })
    },
    fail: (error) => {
      console.log('availability fail:', error)
    }
  })
}

参数说明

• provider：传 google
• serverClientId：必填，建议传 Web Client ID，iOS端时传Google Cloud Console 中的 iOS Client ID
• useLegacyGoogle：仅 Android 有意义
  • true：强制走旧版 Google Sign-In
  • false 或不传：默认先走 Credential Manager(此时结果不会返回serverAuthCode,如需serverAuthCode请使用旧版)，部分异常会自动回退旧版 Google Sign-In
• nonce：Android Credential Manager 可传；旧版 Google Sign-In 不使用它

如果你的后端依赖 serverAuthCode，建议 useLegacyGoogle: true

当前插件在 Android 的 Credential Manager 分支里，返回结果主要是：

• idToken
• userId
• displayName
• givenName
• familyName
• avatar

但 serverAuthCode 和 accessToken 在这条分支里没有返回。

如果你的后端依赖 serverAuthCode，更稳妥的做法是继续使用：

useLegacyGoogle: true

4.4 Apple 登录

function loginWithApple(nonce) {
  ddGoogleLogin.login({
    provider: 'apple',
    nonce,
    success: (result) => {
      console.log('apple login success:', result)
    },
    fail: (error) => {
      console.log('apple login fail:', error)
    }
  })
}

说明：

• provider：传 apple
• serverClientId：不需要
• nonce：可选
• Android 不支持 Apple 登录，会直接返回 9205101

4.5 登出

ddGoogleLogin.logout({
  provider: 'google',
  success: (result) => {
    console.log('logout success:', result)
  },
  fail: (error) => {
    console.log('logout fail:', error)
  }
})

说明：

• provider: 'google'：会清理 Google 登录状态
• provider: 'apple'：插件则直接返回成功，不会有额外原生登出动作

5. 登录成功返回结构

{
  provider: 'google',
  idToken: '',
  serverAuthCode: '',
  accessToken: '',
  userId: '',
  email: '',
  displayName: '',
  givenName: '',
  familyName: '',
  avatar: '',
  grantedScopes: []
}

字段说明：

• idToken：最核心字段，通常交给后端做身份校验
• serverAuthCode：Google 某些流程会返回，Apple 也会映射到这个字段
• accessToken：当前主要由 iOS Google 分支返回
• grantedScopes：当前实现里通常为空数组

6. 错误码

7. 推荐接入顺序

1. 在 Google Cloud Console 配好 Android / iOS / Web 三类 Client ID
2. 把 iOS GIDClientID 和反转 URL Scheme 写入 utssdk/app-ios/Info.plist
3. 把运行时 serverClientId 统一改成 Web Client ID
4. Google 登录前先调用 checkProviderAvailability
5. 如果业务依赖 serverAuthCode，Android 建议 useLegacyGoogle: true
6. 登录成功后，把 idToken 或 serverAuthCode 交给后端验证

8. 已知限制

• 这是 App 原生插件，不适用于 H5 和小程序
• Android 不支持 Apple 登录，需要自行根据苹果的网页登录授权文档
• iOS Google 登录除了 serverClientId，还依赖 Info.plist 的 GIDClientID
• 页面上下文不存在时，login / logout / checkProviderAvailability 都可能失败
• Android Credential Manager 分支当前不适合依赖 serverAuthCode 的业务