Migration Guide from @capacitor-community/apple-sign-in to @capgo/capacitor-social-login

Overview

This guide outlines the transition from the legacy @capacitor-community/apple-sign-in plugin to the modern @capgo/capacitor-social-login package. The new plugin provides a unified interface for multiple social authentication providers with improved TypeScript support and active maintenance.

Installation

1. Remove the old package:

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

2. Install the new package:

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

Code Changes

Import Changes

import { SignInWithApple } from '@capacitor-community/apple-sign-in';
import { SocialLogin } from '@capgo/capacitor-social-login';

Initialization

Key Change: The new plugin requires an initialization step that wasn’t needed before.

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

Important Note: For iOS, you provide basic configuration, while Android requires additional details including a Service ID and backend callback URL for web-based OAuth authentication.

Sign In

The login process simplifies from multiple parameters to a cleaner 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'
  }
});

The new plugin uses login() with provider: 'apple' and optional scopes rather than passing individual configuration values like clientId and redirectURI.

Response Type Changes

Results now include an accessToken object with expiration details and a structured profile section, replacing the flatter response format of the original package:

// 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;
    };
  };
}

New Capabilities

The updated plugin introduces functionality that wasn’t available in the predecessor:

Checking Login Status

// Not available in old package
const status = await SocialLogin.isLoggedIn({
  provider: 'apple'
});

Logout Functionality

// Not available in old package
await SocialLogin.logout({
  provider: 'apple'
});

These methods provide isLoggedIn() to verify authentication status and logout() functionality.

Platform Specific Changes

iOS Setup

iOS maintains familiar setup procedures through Xcode capabilities:

1. The iOS setup remains largely the same. You still need to:
   • Enable “Sign In with Apple” capability in Xcode
   • Configure your app in the Apple Developer Portal
   • No additional code changes required for iOS

Android Setup

Android now receives native support via web-based OAuth authentication:

The new plugin provides Android support out of the box, but requires additional setup:

1. Create a Services ID in the Apple Developer Portal
2. Configure a web authentication endpoint
3. Set up your Android app to handle the OAuth flow
4. Backend service configuration is required

For detailed Android setup instructions, please refer to the Android Setup Guide.

Key Advantages

The modernized package provides:

1. Unified APIs across multiple social providers (Google, Facebook, Apple)
2. Improved TypeScript typing with better type definitions
3. Active community maintenance compared to the deprecated version
4. Built-in Android support through web-based authentication
5. Persistent login state management
6. Better error handling with consistent error types

Breaking Changes

1. Explicit initialization is now required - no default configuration
2. Response object structure has changed - nested result format
3. Android implementation requires a backend service for OAuth
4. Token refresh handling is different - improved token management
5. Error handling and error types have changed - more detailed errors

For more detailed setup instructions, please refer to the official documentation.