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

重要注意事项: For iOS, you provide basic configuration, while Android requires additional details including a Service ID and backend callback URL for web-based OAuth authentication.

登录

登录过程简化，从多个参数变为更清晰的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 现在通过基于 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. 错误处理和错误类型已更改 - 更详细的错误

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