Apple Sign-In의 @capgo/social-login 마이그레이션

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

개요

이 가이드는 레거시 @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 변경 사항

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에서는 웹 기반 OAuth 인증을 위해 Service ID와 백엔드 callback 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' 및 선택적 scope를 사용하며, 다음과 같은 개별 설정값을 전달하지 않습니다: clientId 및 redirectURI.

Response Type 변경 사항

이제 결과에는 다음이 포함됩니다: 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 capabilities를 통해 기존과 동일한 설정 절차를 유지합니다:

iOS 설정은 거의 동일합니다. 다음 작업을 수행해야 합니다:
- Xcode에서 “Sign In with Apple” capability 활성화
- Apple Developer Portal에서 앱 설정
- iOS를 위한 추가적인 code 변경 사항은 없습니다

Android 설정

Android 이제 웹 기반 OAuth 인증을 통해 네이티브 지원을 제공합니다:

새 플러그인은 Android를 즉시 지원하지만, 추가 설정이 필요합니다:

Apple Developer Portal에서 Services ID 생성
웹 인증 엔드포인트 구성
OAuth 흐름을 처리하도록 Android 앱 설정
백엔드 서비스 구성이 필요합니다

자세한 Android 설정 방법은 다음을 참조하세요: Android 설정 가이드.

주요 장점

새로운 패키지는 다음을 제공합니다:

통합 API 다양한 소셜 프로바이더(Google, Facebook, Apple) 지원
개선된 TypeScript 타이핑 더 나은 타입 정의와 함께
활발한 커뮤니티 유지보수 기존 지원 종료 버전 대비
Android 기본 지원 웹 기반 인증을 통한 지원
지속적인 로그인 상태 관리
향상된 에러 핸들링 일관된 에러 타입 제공

주요 변경 사항

이제 명시적 초기화가 필요합니다 - 기본 설정 없음
Response 객체 구조가 변경되었습니다 - 중첩된 result 형식
Android 구현에는 백엔드 서비스가 필요합니다 OAuth용
Token refresh 처리 방식이 달라졌습니다 - 토큰 관리 개선
에러 핸들링 및 에러 타입이 변경되었습니다 - 더 상세한 에러

더 자세한 설정 방법은 다음을 참고하세요: 공식 문서.

사용 중이라면 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의 구현 세부 사항은, 2단계 인증 2단계 인증의 구현 세부 사항에 대해서는