Apple Sign-In 迁移至 @capgo/social-login

概览

本指南概述了从旧版 @capacitor-community/apple-sign-in 插件向现代 @capgo/capacitor-social-login package 的迁移过程。新插件为多种社交身份验证提供商提供了统一的接口，并增强了 TypeScript 支持，且处于活跃维护状态。

安装

1. 移除旧 package：

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

2. 安装新 package：

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

Code 变更

导入变更

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

初始化

核心变更：新插件需要执行以前不需要的初始化步骤。

// No initialization needed in old package
// For iOS: Basic configuration
await SocialLogin.initialize({
  apple: {} // Basic iOS configuration
});

// For Android: Additional configuration required
await SocialLogin.initialize({
  apple: {
    clientId: 'YOUR_SERVICE_ID', // Service ID from Apple Developer Portal
    redirectUrl: 'https://your-backend.com/callback' // Your backend callback URL
  }
});

重要提示对于 iOS，你只需提供基础配置；而 Android 则需要更多细节，包括用于 Web OAuth 认证的 Service ID 和后端回调 URL。

登录

登录流程已从多个参数简化为更简洁的 API：

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: {
    // Optional: Add scopes if needed
    scopes: ['email', 'name'],
    nonce: 'nonce'
  }
});

新插件使用 login() 带 provider: 'apple' 以及可选的 scopes，而不是像之前那样传递单个配置值，例如 clientId 和 redirectURI.

Response Type 变更

结果现在包含一个 accessToken 包含过期详情及结构化 profile 部分的 object，取代了原软件包中扁平的响应格式：

// Old response type
interface AppleSignInResponse {
  response: {
    user: string;
    email: string | null;
    givenName: string | null;
    familyName: string | null;
    identityToken: string | null;
    authorizationCode: string | null;
  };
}

// New response type
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;
    };
  };
}

新功能

更新后的插件引入了前代版本中不具备的功能：

检查登录状态

// Not available in old package
const status = await SocialLogin.isLoggedIn({
  provider: 'apple'
});

登出功能

// Not available in old package
await SocialLogin.logout({
  provider: 'apple'
});

这些方法提供了 isLoggedIn() 用于验证身份状态并 logout() 功能。

平台相关变更

iOS 配置

iOS 通过 Xcode 的能力保持熟悉的配置流程：

1. iOS 的配置基本保持不变。你仍需：
   • 在 Xcode 中启用 “Sign In with Apple” capability
   • 在 Apple Developer Portal 中配置你的 App
   • iOS 无需额外的 code 变更

Android 配置

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

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

1. 在 Apple Developer Portal 中创建 Services ID
2. 配置 Web 认证端点
3. 设置 Android 应用以处理 OAuth 流程
4. 需要配置后端服务

详细的 Android 设置说明，请参阅 Android 设置指南.

核心优势

新版软件包提供：

1. 统一的 API 支持多种社交平台 (Google, Facebook, Apple)
2. 更完善的 TypeScript 类型支持 提供更精准的类型定义
3. 活跃的社区维护 优于已弃用的旧版本
4. 内置 Android 支持 通过 Web 端身份验证实现
5. 持久化的登录状态管理
6. 更佳的错误处理 提供一致的错误类型

破坏性变更

1. 现在需要显式初始化 - 不再提供默认配置
2. Response 对象结构已变更 - 采用嵌套的 result 格式
3. Android 端实现需要后端服务 用于 OAuth
4. Token 刷新处理方式已变更 - 优化了 Token 管理
5. 错误处理及错误类型已变更 - 提供更详细的错误信息

如需更详细的配置说明，请参阅 官方文档.

从 Apple Sign-In 迁移继续前往 @capgo/social-login

如果你正在使用 Apple Sign-In 迁移至 @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 中的实现细节，以及 双重身份验证 了解双因素认证中的实现细节。