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 的变化

导入更改

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需要额外的细节，包括服务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'
  }
});

新插件使用 login() 和 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更改

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. 响应对象结构已更改 - 嵌套结果格式
3. Android 实现需要一个后端服务 用于 OAuth
4. 令牌刷新处理方式已不同 - 改进令牌管理
5. 错误处理和错误类型已更改 - 更详细的错误

有关详细设置指南，请参阅官方文档 继续从 Apple Sign-In Migration 到 @__CAPGO_KEEP_0__/social-login.

继续从 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 中的实现细节 双因素认证 双因素认证的实现细节。