Migrazione Apple Sign-In a @capgo/social-login

Panoramica

Questa guida illustra la transizione dal legacy @capacitor-community/apple-sign-in plugin al moderno @capgo/capacitor-social-login package. Il nuovo plugin offre un'interfaccia unificata per più provider di autenticazione social, con un supporto TypeScript migliorato e una manutenzione attiva.

Installazione

1. Rimuovi il vecchio pacchetto:

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

2. Installa il nuovo package:

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

Modifiche di Code

Modifiche agli import

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

Inizializzazione

Cambio chiave: Il nuovo plugin richiede un passaggio di inizializzazione che prima non era necessario.

// 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: Per iOS fornisci la configurazione di base, mentre Android richiede dettagli aggiuntivi, tra cui un Service ID e un URL di callback del backend per l'autenticazione OAuth basata su web.

Accedi

Il processo di login passa da più parametri a un API più pulito:

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

Il nuovo plugin utilizza login() con provider: 'apple' e scope opzionali, anziché passare valori di configurazione individuali come clientId e redirectURI.

Modifiche al Response Type

I risultati includono ora un accessToken oggetto con dettagli di scadenza e una struttura profile sezione, che sostituisce il formato di risposta più piatto del pacchetto originale:

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

Nuove funzionalità

Il plugin aggiornato introduce funzionalità non disponibili nella versione precedente:

Verifica dello stato di login

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

Funzionalità di logout

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

Questi metodi forniscono isLoggedIn() per verificare lo stato di autenticazione e logout() funzionalità.

Modifiche specifiche per piattaforma

Setup iOS

iOS mantiene le procedure di configurazione familiari tramite le funzionalità di Xcode:

1. La configurazione per iOS resta in gran parte invariata. È ancora necessario:
   • Abilitare la funzionalità “Sign In with Apple” in Xcode
   • Configurare l'app nel Apple Developer Portal
   • Nessuna modifica aggiuntiva a code richiesta per iOS

Configurazione Android

Android ora riceve supporto nativo tramite autenticazione OAuth basata su web:

Il nuovo plugin fornisce il supporto Android out of the box, ma richiede una configurazione aggiuntiva:

1. Crea un Services ID nel Apple Developer Portal
2. Configura un endpoint di autenticazione web
3. Configura la tua app Android per gestire il flusso OAuth
4. È richiesta la configurazione del backend service

Per istruzioni dettagliate sulla configurazione di Android, consulta la Guida alla configurazione Android.

Vantaggi principali

Il pacchetto modernizzato offre:

1. API unificate per più provider social (Google, Facebook, Apple)
2. Tipizzazione TypeScript migliorata con definizioni di tipo più precise
3. Manutenzione attiva della community rispetto alla versione deprecata
4. Supporto Android integrato tramite autenticazione basata su web
5. Gestione persistente dello stato di login
6. Gestione degli errori migliorata con tipi di errore coerenti

Breaking changes

1. L'inizializzazione esplicita è ora obbligatoria - nessuna configurazione predefinita
2. La struttura dell'oggetto di risposta è cambiata - formato del risultato annidato
3. L'implementazione Android richiede un backend service per OAuth
4. La gestione del refresh del token è diversa - gestione del token migliorata
5. Gestione degli errori e tipi di errore modificati - errori più dettagliati

Per istruzioni di setup più dettagliate, consulta la documentazione ufficiale.

Continua dalla migrazione di Apple Sign-In a @capgo/social-login

Se stai usando Migrazione Apple Sign-In a @capgo/social-login per pianificare i flussi di autenticazione e account, collegandolo a Utilizzo di @capgo/capacitor-social-login per la funzionalità nativa in Utilizzo di @capgo/capacitor-social-login, @capgo/capacitor-social-login per i dettagli di implementazione in @capgo/capacitor-social-login, @capgo/capacitor-passkey per i dettagli di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric per i dettagli di implementazione in @capgo/capacitor-native-biometric, e Autenticazione a due fattori per i dettagli sull'implementazione dell'autenticazione a due fattori.