Apple Sign-In Migration zu @capgo/social-login

Übersicht

Dieser Guide beschreibt den Wechsel vom alten @capacitor-community/apple-sign-in Plugin zum modernen @capgo/capacitor-social-login Package. Das neue Plugin bietet eine einheitliche Schnittstelle für verschiedene Social-Auth-Provider mit besserem TypeScript-Support und aktiver Wartung.

Installation

1. Altes Package entfernen:

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

2. Neues Package installieren:

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

Code Änderungen

Import-Änderungen

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

Initialisierung

Key Change: Das neue Plugin benötigt einen Initialisierungsschritt, der zuvor nicht erforderlich war.

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

Wichtiger HinweisFür iOS reicht eine Basis-Konfiguration aus, während für Android zusätzliche Details wie eine Service ID und eine Backend-Callback-URL für webbasierte OAuth-Authentifizierung benötigt werden.

Anmelden

Der Login-Prozess wurde von mehreren Parametern auf ein saubereres API vereinfacht:

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

Das neue Plugin nutzt login() mit provider: 'apple' und optionale Scopes, anstatt einzelne Konfigurationswerte wie clientId und redirectURI.

Änderungen beim Response Type

Die Ergebnisse enthalten nun einen accessToken Objekt mit Ablaufdetails und einem strukturierten profile Abschnitt, das das flachere Antwortformat des ursprünglichen Pakets ersetzt:

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

Neue Funktionen

Das aktualisierte Plugin führt Funktionen ein, die im Vorgänger nicht verfügbar waren:

Login-Status prüfen

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

Logout-Funktionalität

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

Diese Methoden ermöglichen es, isLoggedIn() den Authentifizierungsstatus zu prüfen und logout() Funktionalität.

Plattformspezifische Änderungen

iOS-Setup

iOS behält die gewohnten Setup-Abläufe über Xcode-Capabilities bei:

1. Das iOS Setup bleibt weitgehend gleich. Du musst weiterhin:
   • Die „Sign In with Apple“-Capability in Xcode aktivieren
   • Deine App im Apple Developer Portal konfigurieren
   • Für iOS sind keine zusätzlichen code-Änderungen erforderlich

Android-Setup

Android erhält nun native Unterstützung über webbasierte OAuth-Authentifizierung:

Das neue Plugin bietet Android-Support out of the box, erfordert jedoch zusätzliches Setup:

1. Erstelle eine Services ID im Apple Developer Portal
2. Konfiguriere einen Web-Authentication-Endpoint
3. Richte deine Android-App für den OAuth-Flow ein
4. Backend-Service-Konfiguration ist erforderlich

Detaillierte Anweisungen zum Android-Setup findest du im Android-Setup-Guide.

Wichtigste Vorteile

Das modernisierte Paket bietet:

1. Einheitliche APIs für verschiedene Social-Provider (Google, Facebook, Apple)
2. Verbessertes TypeScript-Typing mit besseren Type-Definitionen
3. Aktive Community-Pflege im Vergleich zur veralteten Version
4. Integrierte Android-Unterstützung via webbasierter Authentifizierung
5. Persistentes Login-State-Management
6. Besseres Error-Handling mit konsistenten Error-Typen

Breaking Changes

1. Explizite Initialisierung jetzt erforderlich - keine Standardkonfiguration
2. Struktur des Response-Objekts hat sich geändert - verschachteltes Resultat-Format
3. Android-Implementierung benötigt Backend-Service für OAuth
4. Token-Refresh-Handling ist anders - verbessertes Token-Management
5. Error-Handling und Fehlertypen haben sich geändert - detailliertere Fehlermeldungen

Detaillierte Setup-Anleitungen findest du in der offiziellen Dokumentation.

Fahre fort von der Apple Sign-In Migration zu @capgo/social-login

Wenn du es nutzt Apple Sign-In Migration zu @capgo/social-login Um Authentifizierungs- und Account-Flows zu planen, verbinde es mit Mit @capgo/capacitor-social-login für die native Funktionalität in Mit @capgo/capacitor-social-login, @capgo/capacitor-social-login für die Implementierungsdetails in @capgo/capacitor-social-login, @capgo/capacitor-passkey für die Implementierungsdetails in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric für die Implementierungsdetails in @capgo/capacitor-native-biometric, und Zwei-Faktor-Authentifizierung für die Implementierungsdetails zur Zwei-Faktor-Authentifizierung.