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

概述

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

标题为“安装”的部分

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

更新的插件引入了前辈中不可用的功能:

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__

// 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 设置

现在通过基于 Web 的 OAuth 认证接收原生支持: 新插件提供了 Android 支持，但需要额外的设置:

在 Apple 开发者门户中创建一个服务 ID

1. 配置一个 Web 认证端点
2. 配置您的 Android 应用以处理 OAuth 流程
3. Section titled “Android Setup”
4. 需要配置后端服务

请参阅以下Android设置指南以获取详细的Android设置指南 Android设置指南.

主要优势

现代化的包提供:

1. 统一的API 多个社交提供商（Google、Facebook、Apple）
2. 改进的TypeScript类型 具有更好的类型定义
3. 活跃的社区维护 与过时版本相比
4. 内置 Android 支持 通过基于 Web 的身份验证
5. 持久性登录状态管理
6. 更好的错误处理 一致的错误类型

重大变更

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

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

继续从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, 和 双因素认证 为实现细节在双因素认证。