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

Overview

This guide outlines the transition from the legacy @capacitor-community/apple-sign-in plugin to the modern @capgo/capacitor-social-login package. The new plugin provides a unified interface for multiple social authentication providers with improved TypeScript support and active maintenance.

Installation

1. 移除旧的包：

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

2. 安装新的包：

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

Code Changes

导入更改

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

初始化

Key Change：新插件需要一个之前没有的初始化步骤。

// 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需要额外的详细信息，包括Service ID和后端回调URL以支持基于Web的OAuth认证。

登录

：登录过程从多个参数简化到一个更干净的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'
  }
});

The new plugin uses login() with provider: 'apple' 和可选的范围而不是传递单独的配置值，如 clientId 和 redirectURI.

响应类型变更

结果现在包括一个 accessToken 包含过期细节和结构化的 profile 部分，取代了原始包的扁平响应格式：

// 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 中启用“使用 Apple 登录”功能
   • 在 Apple 开发者门户中配置您的应用
   • 不需要额外的 code 更改来支持 iOS

Android 设置

Android 现在通过基于 web 的 OAuth 认证接收原生支持：

新插件提供了 Android 支持，但需要额外的设置：

1. 在 Apple 开发者门户中创建一个 Services ID
2. 配置一个 web 认证端点
3. 配置您的 Android 应用来处理 OAuth 流程
4. Backend service configuration is required

For detailed Android setup instructions, please refer to the Android Setup Guide.

Key Advantages

The modernized package provides:

1. Unified APIs across multiple social providers (Google, Facebook, Apple)
2. Improved TypeScript typing with better type definitions
3. Active community maintenance compared to the deprecated version
4. 内置 Android 支持 通过基于 Web 的身份验证
5. 持久登录状态管理
6. 更好的错误处理 具有一致的错误类型

重大更改

1. 现在需要显式初始化 - 没有默认配置
2. 响应对象结构已更改 - 嵌套结果格式
3. Android 实现需要一个后端服务 OAuth
4. Token 刷新处理方式不同 - token 管理改进
5. 错误处理和错误类型已发生变化 - 更详细的错误信息

详细的设置指南，请参阅 官方文档.

从 Apple Sign-In Migration 到 @capgo/social-login

如果您正在使用 Apple Sign-In Migration 到 @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, 和 双因素认证 为实现细节在 双因素认证