从 @capacitor-community/apple-sign-in 迁移到 @capgo/capacitor-social-login 的指南

概述

本指南概述了从传统的 @capacitor-community/apple-sign-in 插件过渡到现代的 @capgo/capacitor-social-login 包。新插件通过改进的 TypeScript 支持和积极维护为多个社交身份验证提供商提供统一接口。

安装

删除旧包：

npm uninstall @capacitor-community/apple-sign-in

安装新包：

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

代码更改

导入更改

import { SignInWithApple } from '@capacitor-community/apple-sign-in';
import { SocialLogin } from '@capgo/capacitor-social-login';

初始化

关键更改：新插件需要以前不需要的初始化步骤。

// 旧包中不需要初始化
// 对于 iOS：基本配置
await SocialLogin.initialize({
  apple: {} // 基本 iOS 配置
});

// 对于 Android：需要额外配置
await SocialLogin.initialize({
  apple: {
    clientId: 'YOUR_SERVICE_ID', // 来自 Apple Developer Portal 的 Service ID
    redirectUrl: 'https://your-backend.com/callback' // 您的后端回调 URL
  }
});

重要提示：对于 iOS，您提供基本配置，而 Android 需要额外的详细信息，包括 Service ID 和用于基于 Web 的 OAuth 身份验证的后端回调 URL。

const result = await SignInWithApple.authorize({
  clientId: 'com.your.app',
  redirectURI: 'https://your-app.com/callback',
  scopes: 'email name',
  state: '12345',
  nonce: 'nonce'
});

const result = await SocialLogin.login({
  provider: 'apple',
  options: {
    // 可选：如果需要添加范围
    scopes: ['email', 'name'],
    nonce: 'nonce'
  }
});

新插件使用带有 provider: 'apple' 和可选范围的 login()，而不是传递像 clientId 和 redirectURI 这样的单独配置值。

响应类型更改

结果现在包括一个带有过期详细信息的 accessToken 对象和一个结构化的 profile 部分，替换了原始包的扁平响应格式：

// 旧响应类型
interface AppleSignInResponse {
  response: {
    user: string;
    email: string | null;
    givenName: string | null;
    familyName: string | null;
    identityToken: string | null;
    authorizationCode: string | null;
  };
}

// 新响应类型
interface SocialLoginResponse {
  provider: 'apple';
  result: {
    accessToken: {
      token: string;
      expiresIn?: number;
      refreshToken?: string;
    } | null;
    idToken: string | null;
    profile: {
      user: string;
      email: string | null;
      givenName: string | null;
      familyName: string | null;
    };
  };
}

新功能

更新的插件引入了前身中不可用的功能：

检查登录状态

// 旧包中不可用
const status = await SocialLogin.isLoggedIn({
  provider: 'apple'
});

退出登录功能

// 旧包中不可用
await SocialLogin.logout({
  provider: 'apple'
});

这些方法提供 isLoggedIn() 来验证身份验证状态和 logout() 功能。

平台特定更改

iOS 设置

iOS 通过 Xcode 功能维护熟悉的设置过程：

iOS 设置基本保持不变。您仍然需要：
- 在 Xcode 中启用 “Sign In with Apple” 功能
- 在 Apple Developer Portal 中配置您的应用
- iOS 不需要额外的代码更改

Android 设置

Android 现在通过基于 Web 的 OAuth 身份验证获得原生支持：

新插件提供开箱即用的 Android 支持，但需要额外设置：

在 Apple Developer Portal 中创建 Services ID
配置 Web 身份验证端点
设置您的 Android 应用以处理 OAuth 流程
需要后端服务配置

有关详细的 Android 设置说明，请参阅 Android 设置指南。

关键优势

现代化的包提供：

多个社交提供商（Google、Facebook、Apple）的统一 API
具有更好类型定义的改进 TypeScript 类型
与已弃用版本相比的积极社区维护
通过基于 Web 的身份验证的内置 Android 支持
持久登录状态管理
具有一致错误类型的更好的错误处理

重大更改

现在需要显式初始化 - 没有默认配置
响应对象结构已更改 - 嵌套结果格式
Android 实现需要后端服务用于 OAuth
令牌刷新处理不同 - 改进的令牌管理
错误处理和错误类型已更改 - 更详细的错误

有关更详细的设置说明，请参阅官方文档。