从 @codetrix-studio/capacitor-google-auth 迁移到 @capgo/capacitor-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. 在所有平台的 webClientId 字段中使用此 Web Client ID
3. 对于 Android，您仍然需要使用 SHA1 创建 Android Client ID，但这仅用于验证目的 - 不会使用令牌（Android 设置指南）

代码更改

导入更改

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

初始化

设置从简单的 GoogleAuth.initialize() 调用转换为具有嵌套 Google 配置的更结构化的 SocialLogin.initialize()：

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

await SocialLogin.initialize({
  google: {
    webClientId: 'WEB_CLIENT_ID.apps.googleusercontent.com', // 所有平台使用 Web Client ID
    iOSClientId: 'IOS_CLIENT_ID', // 用于 iOS
    mode: 'offline' // 替代 grantOfflineAccess
  }
});

登录

登录方法从 GoogleAuth.signIn() 更改为具有显式提供商规范的 SocialLogin.login()：

const user = await GoogleAuth.signIn();
const res = await SocialLogin.login({
  provider: 'google',
  options: {
    scopes: ['email', 'profile'],
    forceRefreshToken: true // 如果需要刷新令牌
  }
});

平台特定更改

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" />

响应类型更改

身份验证响应现在提供包含提供商信息、访问令牌、ID 令牌和用户配置文件数据的结构化对象：

interface GoogleLoginResponse {
  provider: 'google';
  result: {
    accessToken: {
      token: string;
      expires: string;
      // ... 其他令牌字段
    } | 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：带有过期的访问令牌详细信息
• result.idToken：用于身份验证的 ID 令牌
• result.profile：用户配置文件信息，包括电子邮件、姓名和图像 URL

其他功能

新包支持 Google 以外的多个社交身份验证提供商：

• Apple 登录
• Facebook 登录

这种统一方法提供：

• 所有提供商的一致 API
• 改进的 TypeScript 支持
• 更好的错误处理
• 积极的维护和社区支持

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