Migración de Apple Sign-In a @capgo/social-login

Resumen

Esta guía detalla la transición del @capacitor-community/apple-sign-in plugin anterior al nuevo @capgo/capacitor-social-login package. El nuevo plugin ofrece una interfaz unificada para múltiples proveedores de autenticación social, con mejor soporte de TypeScript y mantenimiento activo.

Instalación

1. Elimina el paquete anterior:

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

2. Instala el nuevo package:

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

Cambios en Code

Cambios en los imports

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

Inicialización

Cambio clave: El nuevo plugin requiere un paso de inicialización que antes no era necesario.

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

Nota importante: Para iOS, proporcionas la configuración básica, mientras que Android requiere detalles adicionales, como un Service ID y una URL de callback del backend para la autenticación OAuth basada en web.

Iniciar sesión

El proceso de login se simplifica de múltiples parámetros a un API más limpio:

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

El nuevo plugin utiliza login() con provider: 'apple' y scopes opcionales en lugar de pasar valores de configuración individuales como clientId y redirectURI.

Cambios en el tipo de respuesta

Los resultados ahora incluyen un accessToken objeto con detalles de expiración y una profile sección estructurada, reemplazando el formato de respuesta más plano del paquete original:

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

Nuevas funcionalidades

El plugin actualizado incorpora funcionalidades que no estaban disponibles en la versión anterior:

Comprobando estado de sesión

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

Funcionalidad de cierre de sesión

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

Estos métodos proporcionan isLoggedIn() para verificar el estado de autenticación y logout() funcionalidad.

Cambios específicos por plataforma

iOS Setup

iOS mantiene los procedimientos de configuración habituales mediante las capacidades de Xcode:

1. La configuración de iOS sigue siendo prácticamente la misma. Aún necesitas:
   • Habilitar la capacidad “Sign In with Apple” en Xcode
   • Configurar tu app en el Apple Developer Portal
   • No se requieren cambios adicionales de code para iOS

Configuración de Android

Android ahora recibe soporte nativo mediante autenticación OAuth basada en web:

El nuevo plugin proporciona soporte para Android desde el inicio, pero requiere configuración adicional:

1. Crea un ID de servicio en el Apple Developer Portal
2. Configura un endpoint de autenticación web
3. Configura tu app de Android para manejar el flujo OAuth
4. Se requiere configurar el servicio backend

Para instrucciones detalladas de configuración de Android, consulta la Guía de configuración de Android.

Ventajas clave

El paquete modernizado ofrece:

1. APIs unificadas en múltiples proveedores sociales (Google, Facebook, Apple)
2. Tipado de TypeScript mejorado con mejores definiciones de tipos
3. Mantenimiento activo por la comunidad en comparación con la versión obsoleta
4. Soporte nativo para Android mediante autenticación basada en web
5. Persistent login state management
6. Gestión de errores mejorada con tipos de error consistentes

Cambios importantes

1. Ahora se requiere una inicialización explícita - sin configuración predeterminada
2. La estructura del objeto de respuesta ha cambiado - formato de resultado anidado
3. La implementación de Android requiere un servicio de backend para OAuth
4. El manejo de la renovación de tokens es diferente - mejor gestión de tokens
5. El manejo de errores y los tipos de error han cambiado - errores más detallados

Para instrucciones de configuración detalladas, consulta la documentación oficial.

Continúa desde la migración de Apple Sign-In a @capgo/social-login

Si estás usando Migración de Apple Sign-In a @capgo/social-login para planificar los flujos de autenticación y de cuenta, conéctalo con Uso de @capgo/capacitor-social-login para la capacidad nativa en el uso de @capgo/capacitor-social-login, @capgo/capacitor-social-login para los detalles de implementación en @capgo/capacitor-social-login, @capgo/capacitor-passkey para el detalle de implementación en @capgo/capacitor-passkey, @capgo/capacitor-native-biometric para el detalle de implementación en @capgo/capacitor-native-biometric, y Autenticación de dos factores para el detalle de implementación en la autenticación de dos factores.