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

复制一个包含安装步骤和本插件的完整Markdown指南的设置命令。

概述

本指南概述了从遗留版本的过渡。 @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

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 功能，iOS 配置保持了熟悉的设置流程：

iOS 配置基本保持不变。您仍然需要：
- 在 Xcode 中启用 “Sign In with Apple” 功能
- 在 Apple 开发者门户中配置您的应用
- 无需进行额外的 code 更改

Android 配置

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

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

在Apple Developer Portal中创建一个Services ID
配置一个Web认证端点
配置您的Android应用程序以处理OAuth流程
需要后端服务配置

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

关键优势

现代化的包提供：

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

重大变更

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

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