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

概述

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

安装

1. 移除旧包：

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

2. 安装新包：

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

Code Changes

__CAPGO_KEEP_0__ Changes

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

登录

登录过程从多个参数简化为更清晰的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() with 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功能保持熟悉的设置程序：

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 实现需要一个后端服务 为了 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 中的实现细节 双因素认证 在双因素认证中的实现细节