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

Overview

Esta guía describe la transición desde la versión legada @capacitor-community/apple-sign-in plugin a la modernidad @capgo/capacitor-social-login paquete. El nuevo plugin proporciona una interfaz unificada para múltiples proveedores de autenticación social con mejor soporte para TypeScript y mantenimiento activo.

Installation

1. Título de sección “Instalación”

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

2. Instalar el nuevo paquete:

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

Code Cambios

Importar Cambios

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

Iniciación

Modificación clave: La nueva extensión 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 ImportantePara iOS, proporciona configuración básica, mientras que Android requiere detalles adicionales, incluyendo un ID de Servicio y una URL de llamada de backend para la autenticación de OAuth basada en web.

Iniciar Sesión

El proceso de inicio de sesión se simplifica desde 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() with provider: 'apple' con 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 accessToken objeto con detalles de expiración y una sección estructurada profile reemplazando el formato de respuesta 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 plugin actualizado introduce funcionalidades que no estaban disponibles en el predecesor:

Verificar el estado de inicio 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'
});

Estas funciones proporcionan isLoggedIn() para verificar el estado de autenticación y logout() funcionalidad.

Cambios específicos de plataforma

iOS Setup

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

1. La configuración de iOS sigue siendo básicamente la misma. Todavía necesitas:
   • Habilite la capacidad de inicio de sesión con Apple en Xcode
   • Configure su aplicación en el Portal de Desarrolladores de Apple
   • No se requieren cambios adicionales code para iOS

Configuración de Android

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

El nuevo plugin proporciona soporte para Android de serie, pero requiere una configuración adicional:

1. Cree un ID de Servicios en el Portal de Desarrolladores de Apple
2. Configure un punto de conexión de autenticación web
3. Configure su aplicación de Android para manejar el flujo de OAuth
4. Se requiere configuración del servicio de backend

Para obtener instrucciones detalladas de configuración de Android, por favor consulte el Guía de Configuración de Android.

Ventajas clave

El paquete modernizado proporciona:

1. APIs unificadas en múltiples proveedores sociales (Google, Facebook, Apple)
2. Mejoras en el tipado de TypeScript con definiciones de tipo mejoradas
3. Mantenimiento activo de la comunidad en comparación con la versión descontinuada
4. Soporte integrado para Android a través de autenticación basada en web
5. Gestión de estado de inicio de sesión persistente
6. Mejor manejo de errores con tipos de errores consistentes

Cambios significativos

1. La inicialización explícita es ahora obligatoria - no configuración por defecto
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 refresco de tokens es diferente - mejor gestión de tokens
5. Error handling and error types have changed - errores más detallados

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

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

Si está utilizando la migración de Apple Sign-In a @capgo/social-login para planificar la autenticación y los flujos de cuenta, conecte con Usando @capgo/capacitor-social-login para la capacidad nativa en Usando @capgo/capacitor-social-login, @capgo/capacitor-iniciación-de-sesión-social para el detalle de implementación en @capgo/capacitor-social-login, @capgo/capacitor-passkey para el detalle de implementación en @capgo/capacitor-passkey, @capgo/capacitor-nativo-biometria para el detalle de implementación en @capgo/capacitor-native-biometric, y Autenticación en dos factores para el detalle de implementación en Autenticación en dos factores.