将 Google Auth 迁移至 @capgo/social-login

概览

本指南提供了从以下内容迁移的完整步骤： @codetrix-studio/capacitor-google-auth 改为 @capgo/capacitor-social-login，以确保平滑过渡并提升身份验证体验。新插件通过统一的 API，将多个社交身份验证提供商整合在一起。

安装

1. 移除旧包：

   npm uninstall @codetrix-studio/capacitor-google-auth

2. 安装新包：

   npm install @capgo/capacitor-social-login
   npx cap sync

Google Auth 配置的重要变更

Web Client ID 要求

关键变更：更新后的插件要求所有平台都使用 Web Client ID。

你需要：

1. 如果你还没有 Web Client ID，请在 Google Cloud Console 中创建一个（如何获取凭据)
2. 在以下字段中使用此 Web Client ID： webClientId 适用于所有平台
3. 对于 Android，你仍需使用 SHA1 创建一个 Android Client ID，但这仅用于验证——token 不会被使用（Android 配置指南)

Code 变更

导入变更

import { GoogleAuth } from '@codetrix-studio/capacitor-google-auth';
import { SocialLogin } from '@capgo/capacitor-social-login';

初始化

配置流程从简单的 GoogleAuth.initialize() 调用改为更结构化的 SocialLogin.initialize() 并带有嵌套的 Google 配置：

GoogleAuth.initialize({
  clientId: 'CLIENT_ID.apps.googleusercontent.com',
  scopes: ['profile', 'email'],
  grantOfflineAccess: true,
});

await SocialLogin.initialize({
  google: {
    webClientId: 'WEB_CLIENT_ID.apps.googleusercontent.com', // Use Web Client ID for all platforms
    iOSClientId: 'IOS_CLIENT_ID', // for iOS
    mode: 'offline' // replaces grantOfflineAccess
  }
});

登录

登录方式已从 GoogleAuth.signIn() 改为 SocialLogin.login() 改为显式指定 provider：

const user = await GoogleAuth.signIn();
const res = await SocialLogin.login({
  provider: 'google',
  options: {
    scopes: ['email', 'profile'],
    forceRefreshToken: true // if you need refresh token
  }
});

平台特定变更

Android

1. 更新您的 MainActivity.java (Android 完整配置指南):

 import ee.forgr.capacitor.social.login.GoogleProvider;
 import ee.forgr.capacitor.social.login.SocialLoginPlugin;
 import ee.forgr.capacitor.social.login.ModifiedMainActivityForSocialLoginPlugin;
 import com.getcapacitor.PluginHandle;
 import com.getcapacitor.Plugin;
 import android.content.Intent;
 import android.util.Log;

 public class MainActivity extends BridgeActivity {
 public class MainActivity extends BridgeActivity implements ModifiedMainActivityForSocialLoginPlugin {

   @Override
   public void onActivityResult(int requestCode, int resultCode, Intent data) {
     super.onActivityResult(requestCode, resultCode, data);

     if (requestCode >= GoogleProvider.REQUEST_AUTHORIZE_GOOGLE_MIN && requestCode < GoogleProvider.REQUEST_AUTHORIZE_GOOGLE_MAX) {
       PluginHandle pluginHandle = getBridge().getPlugin("SocialLogin");
       if (pluginHandle == null) {
         Log.i("Google Activity Result", "SocialLogin login handle is null");
         return;
       }
       Plugin plugin = pluginHandle.getInstance();
       if (!(plugin instanceof SocialLoginPlugin)) {
         Log.i("Google Activity Result", "SocialLogin plugin instance is not SocialLoginPlugin");
         return;
       }
       ((SocialLoginPlugin) plugin).handleGoogleLoginIntent(requestCode, data);
     }
   }

   public void IHaveModifiedTheMainActivityForTheUseWithSocialLoginPlugin() {}
}

iOS

1. AppDelegate.swift 无需重大更改 (iOS 配置指南)

2. 在以下位置更新您的配置： capacitor.config.json，新插件已不再使用它：

{
  "plugins": {
   "GoogleAuth": {
     "scopes": ["profile", "email"],
     "serverClientId": "xxxxxx-xxxxxxxxxxxxxxxxxx.apps.googleusercontent.com",
     "forceCodeForRefreshToken": true
   }
}

Web

1. 从你的项目中移除 Google Sign-In meta 标签， index.html 如果你之前使用了它们：

<meta name="google-signin-client_id" content="{your client id here}" />
<meta name="google-signin-scope" content="profile email" />

响应类型变更

身份验证响应现在会提供一个结构化对象，其中包含提供商信息、access tokens、ID tokens 以及用户个人资料数据：

interface GoogleLoginResponse {
  provider: 'google';
  result: {
    accessToken: {
      token: string;
      expires: string;
      // ... other token fields
    } | null;
    idToken: string | null;
    profile: {
      email: string | null;
      familyName: string | null;
      givenName: string | null;
      id: string | null;
      name: string | null;
      imageUrl: string | null;
    };
  };
}

响应结构包括：

• provider：用于标识身份验证提供商 ('google')
• result.accessToken: 包含过期时间的 Access token 详情
• result.idToken: 用于身份验证的 ID token
• result.profile: 用户个人资料信息，包括邮箱、姓名和头像 URL

其他功能

新版 package 除了 Google 外，还支持多种社交登录提供商：

• Apple 登录
• Facebook 登录

这种统一的方式提供了：

• 所有提供商之间一致的 API
• 更出色的 TypeScript 支持
• 更完善的错误处理
• 持续的维护与社区支持

查看 主要文档 以获取这些其他提供商的详细配置说明。

从 Google Auth Migration 继续学习 @capgo/social-login

如果你正在使用 将 Google Auth 迁移至 @capgo/social-login 用来规划身份验证和账户流程，并将它与 使用 @capgo/capacitor-social-login 关于使用 @capgo/capacitor-social-login 的原生能力， @capgo/capacitor-social-login 在 @capgo/capacitor-social-login 中查看实现细节， @capgo/capacitor-passkey 有关 @capgo/capacitor-passkey 的实现细节， @capgo/capacitor-native-biometric 以及 @capgo/capacitor-native-biometric 中的实现细节， 双因素认证 有关双重身份验证的实现细节。