跳转到正文

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

GitHub

本指南介绍从旧版 @capacitor-community/apple-sign-in 插件迁移到现代 @capgo/capacitor-social-login package。新插件为多种社交登录提供商提供统一接口,改进了 TypeScript 支持,并保持活跃维护。

  1. 移除旧 package:

    终端窗口
    npm uninstall @capacitor-community/apple-sign-in
  2. 安装新包:

    终端窗口
    npm install @capgo/capacitor-social-login
    npx cap sync
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 则需要更多细节,包括用于 Web OAuth 认证的 Service ID 和后端回调 URL。

登录流程从多个参数简化为更简洁的 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' 以及可选的 scopes,而不是传递单独的配置值,例如 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 通过 Xcode 的能力,保持了熟悉的配置流程:

  1. iOS 的配置基本保持不变。你仍需:
    • 在 Xcode 中启用 “Sign In with Apple” capability
    • 在 Apple Developer Portal 中配置你的 App
    • iOS 无需额外的 code 变更

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. 响应对象结构已变更 - 嵌套的 result 格式
  3. Android 端实现需要后端服务 用于 OAuth
  4. Token 刷新处理方式已变更 - 改进了 token 管理
  5. 错误处理机制及错误类型已变更 - 更详细的错误信息

如需更详细的配置说明,请参阅 官方文档.

从 Apple Sign-In 迁移继续到 @capgo/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 中的实现细节, 双因素认证 有关双重身份验证的实现细节。