Apple Migración de inicio de sesión a @capgo/social-login

Descripción general

Esta guía describe la transición del complemento @capacitor-community/apple-sign-in heredado al paquete @capgo/capacitor-social-login moderno. El nuevo complemento proporciona una interfaz unificada para múltiples proveedores de autenticación social con soporte TypeScript mejorado y mantenimiento activo.

Instalación

1. Retire el paquete antiguo:

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

2. Instale el nuevo paquete:

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

Cambios de código

Importar cambios

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

Inicialización

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

// 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, usted proporciona la configuración básica, mientras que Android requiere detalles adicionales que incluyen un ID de servicio y una URL de devolución de llamada de backend para la autenticación OAuth basada en web.

Iniciar sesión

El proceso de inicio de sesión se simplifica desde múltiples parámetros hasta 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 complemento utiliza login() con provider: 'apple' y ámbitos 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 objeto accessToken con detalles de vencimiento y una sección estructurada profile, 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 capacidades

El complemento actualizado introduce una funcionalidad que no estaba disponible en el predecesor:

Comprobación del estado de inicio de sesión

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

Funcionalidad de cerrar 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 la funcionalidad logout().

Cambios específicos de la plataforma

iOS Configuración

iOS mantiene procedimientos de configuración familiares a través de las capacidades Xcode:

1. La configuración de iOS sigue siendo prácticamente la misma. Aún necesitas:
   • Habilite la capacidad “Iniciar sesión con Apple” en Xcode
   • Configure su aplicación en el Portal para desarrolladores Apple
   • No se requieren cambios de código adicionales para iOS

Android Configuración

Android ahora recibe soporte nativo a través de la autenticación OAuth basada en web:

El nuevo complemento proporciona soporte Android listo para usar, pero requiere configuración adicional:

1. Cree una ID de servicios en el portal para desarrolladores Apple
2. Configurar un punto final de autenticación web
3. Configure su aplicación Android para manejar el flujo OAuth
4. Se requiere la configuración del servicio backend

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

Ventajas clave

El paquete modernizado proporciona:

1. API unificadas en múltiples proveedores sociales (Google, Facebook, Apple)
2. Escritura TypeScript mejorada con mejores definiciones de tipo
3. Mantenimiento comunitario activo en comparación con la versión obsoleta
4. Soporte Android integrado mediante autenticación basada en web
5. Gestión del estado de inicio de sesión persistente
6. Mejor manejo de errores con tipos de error consistentes

Cambios importantes1. Ahora se requiere una inicialización explícita: no hay configuración predeterminada

2. La estructura del objeto de respuesta ha cambiado - formato de resultado anidado
3. Android la implementación requiere un servicio backend para OAuth
4. El manejo de la actualización de tokens es diferente: administración de tokens mejorada
5. El manejo de errores y los tipos de errores han cambiado: errores más detallados

Para obtener instrucciones de configuración más detalladas, consulte la documentación oficial.