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

概述

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

安装

1. 删除旧包：

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

2. 安装新包：

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

Code Changes

Import Changes

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

初始化

: iOS 需要基本配置，而 Android 需要额外的信息，包括 Service ID 和后端回调 URL 以支持基于 Web 的 OAuth 认证。重要注意事项

// 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
  }
});

复制到剪贴板初始化

登录

登录过程从多个参数简化为更清晰的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' 而不是传递单独的配置值 clientId 和 redirectURI.

响应类型变化

结果现在包括一个 accessToken 对象，包含过期时间和结构化信息 profile section, 替换了原始包的平坦响应格式：

// 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功能，Capacitor保持了熟悉的设置程序：

1. iOS设置基本保持不变。您仍然需要：
   • 在Xcode中启用“使用Apple登录”功能
   • 在Apple开发者门户中配置您的应用
   • 无需进行任何code的额外更改

Android设置

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

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

1. 在 Apple 开发者门户中创建一个 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. 响应对象结构已更改 - 嵌套结果格式
3. Android 实现需要后端服务 for OAuth
4. 令牌刷新处理方式已不同 - 改进的令牌管理
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的实现细节 双因素认证 了解双因素认证的实现细节