Migration d'Apple Sign-In vers @capgo/social-login

Aperçu

Ce guide présente la transition depuis l'ancien @capacitor-community/apple-sign-in plugin vers le nouveau @capgo/capacitor-social-login package. Le nouveau plugin offre une interface unifiée pour plusieurs fournisseurs d'authentification sociale, avec un meilleur support TypeScript et une maintenance active.

Installation

1. Supprimez l'ancien package :

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

2. Installez le nouveau package :

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

Changements Code

Modifications des imports

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

Initialisation

Changement clé : Le nouveau plugin nécessite une étape d’initialisation qui n’était pas nécessaire auparavant.

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

Note importante: Pour iOS, vous fournissez une configuration de base, tandis qu'Android exige des détails supplémentaires, dont un Service ID et une URL de callback backend pour l'authentification OAuth web.

Connexion

Le processus de connexion passe de multiples paramètres à un API plus propre :

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

Le nouveau plugin utilise login() par provider: 'apple' et des scopes optionnels plutôt que de passer des valeurs de configuration individuelles comme clientId et redirectURI.

Changements du type de réponse

Les résultats incluent désormais un accessToken objet contenant les détails d'expiration et une section profile structurée, remplaçant le format de réponse plus plat du package d'origine :

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

Nouvelles fonctionnalités

Le plugin mis à jour introduit des fonctionnalités qui n'étaient pas disponibles dans la version précédente :

Vérification du statut de connexion

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

Fonctionnalité de déconnexion

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

Ces méthodes permettent de isLoggedIn() vérifier le statut d'authentification et logout() fonctionnalité.

Changements spécifiques aux plateformes

Configuration iOS

iOS conserve des procédures de configuration habituelles via les capacités Xcode :

1. La configuration iOS reste globalement la même. Vous devez toujours :
   • Activer la capacité « Sign In with Apple » dans Xcode
   • Configurer votre application dans le portail Apple Developer
   • Aucune modification code supplémentaire n'est requise pour iOS

Configuration Android

Android reçoit désormais un support natif via l'authentification OAuth basée sur le web :

Le nouveau plugin offre le support Android immédiatement, mais nécessite une configuration supplémentaire :

1. Créez un Services ID dans le portail Apple Developer
2. Configurez un endpoint d'authentification web
3. Configurez votre application Android pour gérer le flux OAuth
4. La configuration d'un service backend est requise

Pour des instructions détaillées sur la configuration Android, veuillez consulter le Guide de configuration Android.

Avantages clés

Le package modernisé offre :

1. Des API unifiées pour plusieurs fournisseurs sociaux (Google, Facebook, Apple)
2. Un typage TypeScript amélioré avec de meilleures définitions de types
3. Une maintenance communautaire active comparé à la version obsolète
4. Le support Android intégré via l'authentification web
5. La gestion persistante de l'état de connexion
6. Meilleure gestion des erreurs avec des types d'erreurs cohérents

Breaking changes

1. L'initialisation explicite est désormais requise - aucune configuration par défaut
2. La structure de l'objet Response a changé - format de résultat imbriqué
3. L'implémentation Android nécessite un service backend pour l'OAuth
4. La gestion du refresh du token est différente - gestion des tokens améliorée
5. La gestion des erreurs et les types d'erreur ont changé - erreurs plus détaillées

Pour des instructions de configuration plus détaillées, veuillez consulter la documentation officielle.

Continuer vers @capgo/social-login après la migration Apple Sign-In

Si vous utilisez Migration d'Apple Sign-In vers @capgo/social-login pour planifier les flux d'authentification et de compte, le connecter à Utiliser @capgo/capacitor-social-login pour la capacité native dans Utiliser @capgo/capacitor-social-login @capgo/capacitor-social-login pour les détails d'implémentation dans @capgo/capacitor-social-login @capgo/capacitor-passkey pour les détails d'implémentation dans @capgo/capacitor-passkey @capgo/capacitor-native-biometric pour les détails d'implémentation dans @capgo/capacitor-native-biometric, et Authentification à deux facteurs pour les détails d'implémentation de l'authentification à deux facteurs.