Setup di Facebook Login

Introduzione

In questo manuale, imparerai a configurare l'accesso Facebook con Capgo Social Login. Avrai bisogno dei seguenti elementi:

• Un account di sviluppatore Facebook
• Nome pacchetto/app ID del tuo'app
• Accesso a una finestra di comando per generare hash chiave (Android)

Configurazione Generale

Se non hai già creato un'app Facebook, segui questi passaggi:

1. Creare un'app Facebook

   Seguire il tutorial per Creare un'app

2. Aggiungi Facebook Login all'applicazione

   Nel tuo dashboard del sviluppatore Facebook, aggiungi il prodotto Facebook Login all'applicazione

3. Prima di poter rilasciare l'applicazione al pubblico, segui questo tutorial per pubblicarla

Informazioni importanti

Ecco dove trovare le informazioni chiave che ti serviranno per l'integrazione:

1. CLIENT_TOKEN:

   

2. APP_ID:

   

3. APP_NAME:

   

Configurazione per Android

1. Aggiungi la permessione di rete al tuo AndroidManifest.xml

   Sicurati che questa riga sia presente:

   <uses-permission android:name="android.permission.INTERNET"/>

2. Genera la tua chiave hash Android

   Questo è un passaggio di sicurezza cruciale richiesto da Facebook. Apri il tuo terminale e esegui:

   keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64 -A

   When richiesto di una password, utilizza: android

   Nota

   Per le versioni di rilascio, avrai bisogno del tuo keystore di rilascio:

   keytool -exportcert -alias your-key-name -keystore your-keystore-path | openssl sha1 -binary | openssl base64 -A

3. Aggiungi la chiave hash al tuo app Facebook

   1. Vai alla dashboard del tuo app su Facebook Developers
   2. Naviga a Impostazioni > Base
   3. Scorri verso il basso nella sezione “Android”
   4. Clicca su “Aggiungi piattaforma” se Android non è stato aggiunto ancora e riempisci i dettagli
   5. Aggiungi la chiave hash che hai generato
   6. Per la produzione, aggiungi sia la chiave hash di debug che quella di rilascio

4. Aggiorna il tuo AndroidManifest.xml per includere:

   <application>
       ...
       <activity android:name="com.facebook.FacebookActivity"
           android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation"
           android:label="@string/app_name" />
   
       <activity
           android:name="com.facebook.CustomTabActivity"
           android:exported="true">
           <intent-filter>
               <action android:name="android.intent.action.VIEW" />
               <category android:name="android.intent.category.DEFAULT" />
               <category android:name="android.intent.category.BROWSABLE" />
               <data android:scheme="FB[APP_ID]" />
           </intent-filter>
       </activity>
   </application>

   Attenzione

   Assicurati di sostituire [APP_ID] con l'ID del tuo app Facebook reale nella android:scheme attributo

Configurazione iOS

1. Aggiungi la piattaforma iOS nel Console dello Sviluppatore Facebook

   1. Vai alla dashboard del tuo app su Facebook Developers
   2. Naviga a Impostazioni > Base
   3. Scendi fino in fondo alla pagina e clicca su “Aggiungi piattaforma”
   4. Seleziona iOS e riempisci i dettagli richiesti

2. Apri il tuo progetto Xcode e naviga a Info.plist

3. Aggiungi le seguenti voci al tuo Info.plist:

   <key>FacebookAppID</key>
   <string>[APP-ID]</string>
   <key>FacebookClientToken</key>
   <string>[CLIENT-TOKEN]</string>
   <key>FacebookDisplayName</key>
   <string>[APP-NAME]</string>
   <key>LSApplicationQueriesSchemes</key>
   <array>
       <string>fbapi</string>
       <string>fb-messenger-share-api</string>
   </array>
   <key>CFBundleURLTypes</key>
   <array>
       <dict>
           <key>CFBundleURLSchemes</key>
           <array>
               <string>fb[APP-ID]</string>
           </array>
       </dict>
   </array>

   Attenzione

   Sostituisci i seguenti valori:

   • [APP-ID] con l'ID dell'app di Facebook
   • [CLIENT-TOKEN] con il tuo token di client
   • [APP-NAME] con il nome dell'app

4. Modifica il AppDelegate.swift

   import FBSDKCoreKit
   @UIApplicationMain
   class AppDelegate: UIResponder, UIApplicationDelegate {
         func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
           // Override point for customization after application launch.
   
           // Initialize Facebook SDK
           FBSDKCoreKit.ApplicationDelegate.shared.application(
               application,
               didFinishLaunchingWithOptions: launchOptions
           )
   
           return true
       }
   
       func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
           // Called when the app was launched with a url. Feel free to add additional processing here,
           // but if you want the App API to support tracking app url opens, make sure to keep this call
   
           if (FBSDKCoreKit.ApplicationDelegate.shared.application(
               app,
               open: url,
               sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String,
               annotation: options[UIApplication.OpenURLOptionsKey.annotation]
           )) {
               return true;
           } else {
               return ApplicationDelegateProxy.shared.application(app, open: url, options: options)
           }
       }
   }

Utilizza Facebook Login nel tuo App

Attenzione

Prima di iniziare: Ricorda che con il nuovo Facebook SDK, il tipo di token che ricevi dipende interamente dalla scelta dell'utente per l'App Tracking, non dalla tua code configurazione. Implementa sempre il trattamento sia del token di accesso che del token JWT nel tuo backend per garantire che l'autenticazione funzioni per tutti gli utenti.

1. Inizializza il login Facebook nell'app

   import { SocialLogin } from '@capgo/capacitor-social-login';
   
   // Initialize during app startup
   await SocialLogin.initialize({
     facebook: {
       appId: 'APP_ID',
       clientToken: 'CLIENT_TOKEN',
     }
   })

2. Implementa la funzione di login

   async function loginWithFacebook() {
     try {
       const result = await SocialLogin.login({
         provider: 'facebook',
        options: {
          permissions: ['email', 'public_profile'],
          limitedLogin: false // See Limited Login section below for important details
        }
       });
       console.log('Facebook login result:', result);
       // Handle successful login
     } catch (error) {
       console.error('Facebook login error:', error);
       // Handle error
     }
   }

   Nota

   Login limitato (Solo iOS): Imposta limitedLogin per impostare l'uso della funzione di accesso limitato di Facebook. Questa è una funzione disponibile solo su iOS che fornisce maggiore privacy limitando i dati condivisi durante l'accesso.

   Limitazioni importanti:

   • Solo per iOS: La funzione di accesso limitato di Facebook ha effetto solo sui dispositivi iOS e non ha alcun impatto sugli Android
   • Override ATT: Anche se imposti limitedLogin: false, Facebook forzerà automaticamente a true se l'utente non ha concesso il permesso di trasparenza dell'app (ATT)
   • Sempre gestisci entrambi i casi: La tua app dovrebbe sempre essere preparata a gestire sia i casi di accesso limitato che di accesso completo

   Verifica stato ATT:

   // Check if user has granted tracking permission
   const trackingStatus = await SocialLogin.providerSpecificCall({
     call: 'facebook#requestTracking',
     options: {}
   });
   console.log('Tracking status:', trackingStatus.status); // 'authorized', 'denied', 'notDetermined', or 'restricted'

   Implementazione consigliata se access_token è preferito:

   async function loginWithFacebook() {
     try {
       // Check ATT status first
       const trackingStatus = await SocialLogin.providerSpecificCall({
         call: 'facebook#requestTracking',
         options: {}
       });
   
       const result = await SocialLogin.login({
         provider: 'facebook',
         options: {
           permissions: ['email', 'public_profile'],
           limitedLogin: trackingStatus.status === 'denied' // Auto-adjust based on ATT
         }
       });
   
       // Handle different response types based on limited login
       if (result.result.accessToken) {
         // Your app logic should work with both limited and full login
         console.log('Login successful:', result);
       }
     } catch (error) {
       console.error('Facebook login error:', error);
     }
   }

   Cosa Succede in Login Limitato:

   • Accesso Ridotto ai Dati: Alcuni dati degli utenti potrebbero non essere disponibili
   • Tipi di Token diversi: I token di accesso potrebbero avere diverse capacità
   • Conformità alla Privacy: Aiuta a conformarsi alle richieste di conformità alla privacy di iOS

   Importante: Assicurati di testare sempre il tuo app con entrambi i casi di login limitato e pieno per assicurarti che il tuo app funzioni correttamente in entrambi i casi. Puoi imparare di più su Limited Login qui.

3. Ottenere i dati del profilo dell'utente

   Dopo l'accesso riuscito, puoi recuperare informazioni di profilo aggiuntive:

   async function getFacebookProfile() {
     try {
       const profileResponse = await SocialLogin.providerSpecificCall({
         call: 'facebook#getProfile',
         options: {
           fields: ['id', 'name', 'email', 'first_name', 'last_name', 'picture']
         }
       });
   
       console.log('Facebook profile:', profileResponse.profile);
       return profileResponse.profile;
     } catch (error) {
       console.error('Failed to get Facebook profile:', error);
       return null;
     }
   }
   
   // Example usage after login
   async function loginAndGetProfile() {
     const loginResult = await loginWithFacebook();
     if (loginResult) {
       const profile = await getFacebookProfile();
       if (profile) {
         console.log('User ID:', profile.id);
         console.log('Name:', profile.name);
         console.log('Email:', profile.email);
         console.log('Profile Picture:', profile.picture?.data?.url);
       }
     }
   }

   Suggerimento

   Campi del profilo disponibili: Puoi richiedere qualsiasi campo disponibile nel Graph di Facebook API. I campi comuni includono: id, name, email, first_name, last_name, picture, birthday, gender, location, hometown. Nota che alcuni campi possono richiedere ulteriori autorizzazioni.

   Limitazione del tipo di token: Il getProfile chiamata funziona solo quando hai un token di accesso (accesso standard con tracciamento consentito). Se l'utente ha negato il tracciamento o si sta utilizzando un accesso limitato (solo token JWT), questa chiamata fallirà. In tal caso, utilizzare i dati del profilo forniti nella risposta di accesso iniziale.

⚠️ Critico: Gestione dei Token Backend

Pericolo

CRITICO Comportamento iOS: Accesso limitato e trasparenza dell'app sul tracciamento (ATT) sono iOS-UNICO funzionalità. Su Android, riceverai sempre token di accesso indipendentemente dalla limitedLogin impostazione.

Comportamento dei token iOS:

• limitedLogin: true → Token JWT sempre (solo per iOS)
• limitedLogin: false + L'utente CONSENTI il tracking → Token di accesso
• limitedLogin: false + L'utente RIFIUTA il tracking → Token JWT (iOS sovrascrive automaticamente la tua impostazione)

Comportamento del token per Android: Token di accesso sempre, limitedLogin l'impostazione viene ignorata.

Il tuo backend deve gestire due tipi diversi di token perché gli utenti iOS possono ricevere token di accesso o token JWT a seconda della loro scelta di trasparenza del tracking dell'app, mentre gli utenti Android ricevono sempre token di accesso.

Tipi di token per piattaforma

Piattaforma	Impostazione di accesso limitato	Scelta dell'utente ATT	Tipo di token di risultato
iOS	true	Qualsiasi	Token JWT
iOS	false	Consente il tracking	Token di accesso
iOS	false	Negazione del tracking	Token JWT (override automatico)
Android	Qualsiasi	N/D	Token di accesso (sempre)

Implementazione del backend

1. Detecta il tipo di token e gestiscilo di conseguenza

   async function loginWithFacebook() {
     try {
       const loginResult = await SocialLogin.login({
         provider: 'facebook',
         options: {
           permissions: ['email', 'public_profile'],
           limitedLogin: false // iOS: depends on ATT, Android: ignored
         }
       });
   
       if (loginResult.accessToken) {
         // Access token (Android always, iOS when tracking allowed)
         return handleAccessToken(loginResult.accessToken.token);
       } else if (loginResult.idToken) {
         // JWT token (iOS only when tracking denied or limitedLogin: true)
         return handleJWTToken(loginResult.idToken);
       }
     } catch (error) {
       console.error('Facebook login error:', error);
     }
   }

2. Esempio di integrazione con Firebase

   import { OAuthProvider, FacebookAuthProvider, signInWithCredential } from 'firebase/auth';
   
   async function handleAccessToken(accessToken: string, nonce: string) {
     // For access tokens, use OAuthProvider (new method)
     const fbOAuth = new OAuthProvider("facebook.com");
     const credential = fbOAuth.credential({
       idToken: accessToken,
       rawNonce: nonce
     });
   
     try {
       const userResponse = await signInWithCredential(auth, credential);
       return userResponse;
     } catch (error) {
       console.error('Firebase OAuth error:', error);
       return false;
     }
   }
   
   async function handleJWTToken(jwtToken: string) {
     // For JWT tokens, send to your backend for validation
     try {
       const response = await fetch('/api/auth/facebook-jwt', {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
         },
         body: JSON.stringify({ jwtToken })
       });
   
       const result = await response.json();
       return result;
     } catch (error) {
       console.error('JWT validation error:', error);
       return false;
     }
   }

3. Validazione JWT Backend

   // Backend: Validate JWT token from Facebook
   import jwt from 'jsonwebtoken';
   import { Request, Response } from 'express';
   
   app.post('/api/auth/facebook-jwt', async (req: Request, res: Response) => {
     const { jwtToken } = req.body;
   
     try {
       // Verify JWT token with Facebook's public key
       // See: https://developers.facebook.com/docs/facebook-login/limited-login/token/validating/#standard-claims
       const decoded = jwt.verify(jwtToken, getFacebookPublicKey(), {
         algorithms: ['RS256'],
         audience: process.env.FACEBOOK_APP_ID,
         issuer: 'https://www.facebook.com' // From: https://www.facebook.com/.well-known/openid-configuration/?_rdr
       });
   
       // Extract user info from JWT
       const userInfo = {
         id: decoded.sub,
         email: decoded.email,
         name: decoded.name,
         isJWTAuth: true
       };
   
       // Create your app's session/token
       const sessionToken = createUserSession(userInfo);
   
       res.json({
         success: true,
         token: sessionToken,
         user: userInfo
       });
     } catch (error) {
       console.error('JWT validation failed:', error);
       res.status(401).json({ success: false, error: 'Invalid token' });
     }
   });

4. Manutentore di Token Backend Generico

   // Handle both token types in your backend
   async function authenticateFacebookUser(tokenData: any) {
     if (tokenData.accessToken) {
       // Handle access token - validate with Facebook Graph API
       const response = await fetch(`https://graph.facebook.com/me?access_token=${tokenData.accessToken}&fields=id,name,email`);
       const userInfo = await response.json();
   
       return {
         user: userInfo,
         tokenType: 'access_token',
         expiresIn: tokenData.expiresIn || 3600
       };
     } else if (tokenData.jwtToken) {
       // Handle JWT token - decode and validate
       // See: https://developers.facebook.com/docs/facebook-login/limited-login/token/validating/#standard-claims
       const decoded = jwt.verify(tokenData.jwtToken, getFacebookPublicKey());
   
       return {
         user: {
           id: decoded.sub,
           name: decoded.name,
           email: decoded.email
         },
         tokenType: 'jwt',
         expiresIn: decoded.exp - Math.floor(Date.now() / 1000)
       };
     } else {
       throw new Error('No valid token provided');
     }
   }

Considerazioni Chiave

Pericolo

Critico iOS-Solo Comprensione:

• iOS: La scelta dell'utente per la tracciabilità dell'app determina il tipo di token, NON le tue impostazioni code (anche quando limitedLogin: false)
• Android: Riceve sempre i token di accesso, indipendentemente dal limitedLogin impostazione
• Accesso Limitato è disponibile solo su iOS - Android ignora completamente questa impostazione

Token di Accesso (Accesso Standard):

• ✅ Android: Disponibile sempre (le restrizioni iOS non si applicano)
• ✅ iOS: Solo quando l'utente consente esplicitamente la tracciabilità dell'app
• ✅ Può essere utilizzato per accedere al Graph di Facebook API
• ✅ Tempi di scadenza più lunghi
• ✅ Maggiore disponibilità di dati utente
• ❌ Diventando meno comune su iOS in quanto gli utenti negano sempre più il tracking

Token JWT (Modalità Privacy iOS-Only):

• ❌ Android: Mai si verifica (non supportato)
• ✅ iOS: Quando il tracking è negato o limitedLogin: true
• ✅ Rispetta le preferenze di privacy degli utenti iOS
• ❌ Contiene solo informazioni di base sull'utente
• ❌ Tempi di scadenza più brevi
• ❌ Nesso accesso al Graph di Facebook API
• ⚠️ Ora lo scenario più comune per gli utenti di iOS

Comportamento Specifico per Piattaforma:

• Applicazioni iOS: Deve gestire sia i token di accesso che i token JWT
• Applicazioni Android: Serve solo gestire i token di accesso
• Applicazioni cross-platform: Deve implementare entrambi i metodi di gestione dei token

Suggerimento

Essenziale per iOS: DEVI implementare entrambi i metodi di gestione dei token. Molti sviluppatori di iOS suppongono di ricevere sempre i token di accesso e le loro app si rompono quando gli utenti negano il tracking.

Requisiti di Contesto Sicuro (Web/Capacitor)

Limitazioni di API

La nuova sequenza di accesso Facebook richiede il API Web Crypto per la generazione di nonce, disponibile solo nei contesti sicuri:

// This requires secure context (HTTPS or localhost)
async function sha256(message: string) {
  const msgBuffer = new TextEncoder().encode(message);
  const hashBuffer = await crypto.subtle.digest("SHA-256", msgBuffer); // ❌ Fails in insecure context
  // ...
}

Issue di ambiente di sviluppo

Problema comune: ionic serve con le URL HTTP interrompe l'autenticazione Facebook

Ambiente	Crittografia API Disponibile	Funziona il Login Facebook
http://localhost:3000	✅ Sì	✅ Sì
http://127.0.0.1:3000	✅ Sì	✅ Sì
http://192.168.1.100:3000	❌ No	❌ No
https://any-domain.com	✅ Sì	✅ Sì

Soluzioni per lo Sviluppo Capacitor

1. Usa localhost per il testing web

   # Instead of ionic serve --host=0.0.0.0
   ionic serve --host=localhost

2. Abilita HTTPS in Ionic

   ionic serve --ssl

3. Testa su dispositivi reali

   # Capacitor apps run in secure context on devices
   ionic cap run ios
   ionic cap run android

4. Generazione di nonce alternativa per lo sviluppo

   async function generateNonce() {
     if (typeof crypto !== 'undefined' && crypto.subtle) {
       // Secure context - use crypto.subtle
       return await sha256(Math.random().toString(36).substring(2, 10));
     } else {
       // Fallback for development (not secure for production)
       console.warn('Using fallback nonce - not secure for production');
       return btoa(Math.random().toString(36).substring(2, 10));
     }
   }

Nota di integrazione con Firebase

La documentazione Firebase più recente richiede token JWT con nonces per l'autenticazione Facebook, indipendentemente dalle impostazioni di accesso. Questa approccio funziona sia con il limitedLogin: true e limitedLogin: false:

   // Both modes can return JWT tokens depending on user choice
   const loginResult = await SocialLogin.login({
     provider: 'facebook',
     options: {
       permissions: ['email', 'public_profile'],
       limitedLogin: false, // true = always JWT, false = depends on user tracking choice
       nonce: nonce
     }
   });

Limitazione di sviluppo: Se si utilizza ionic serve su una rete IP (non localhost), l'accesso Facebook fallirà a causa delle restrizioni di crittografia API. Utilizzare localhost o HTTPS per le prove di sviluppo web.

Suggerimento

Sicurezza di produzione: Capacitor app sulle piattaforme iOS/Android eseguono sempre in contesti sicuri, quindi questa limitazione colpisce solo gli ambienti di sviluppo web.

Risoluzione dei Problemi

Problemi comuni e soluzioni

1. Errori di hash chiave su Android

   • Controlla di aver aggiunto la chiave hash corretta al dashboard di Facebook
   • Per le versioni di rilascio, assicurati di aver aggiunto sia la chiave hash di debug che quella di rilascio
   • Verifica di utilizzare il keystore corretto quando si genera la hash

2. Il pulsante di accesso a Facebook non compare

   • Verifica che tutte le voci del manifesto siano corrette
   • Assicurati che il tuo ID App di Facebook e il Token Client siano corretti
   • Assicurati di aver inizializzato correttamente il SDK

3. Problemi iOS comuni

   • Assicurati che tutte le voci di Info.plist siano corrette
   • Verifica che i schemi di URL siano configurati correttamente
   • Controlla che il tuo ID di bundle corrisponda a quanto registrato nel dashboard di Facebook

Test

1. Prima di testare, aggiungi utenti di test nel Console di sviluppatore di Facebook

   • Vai a Ruoli > Utenti di test
   • Crea un utente di test
   • Utilizza questi credenziali per il testing

2. Testa sia le versioni debug che release

   • Versione debug con chiave hash di debug
   • Rilascia il build con la chiave di hash di rilascio
   • Testa su entrambi l'emulatore e i dispositivi fisici

Ricorda di testare l'intero flusso di accesso, compresi:

• Accesso riuscito
• Annullamento dell'accesso
• Gestione degli errori
• Funzionalità di logout

Continua da Facebook Login Setup

Facebook Login Setup per pianificare l'autenticazione e i flussi di account, connettilo con Section titled “Continua da Facebook Login Setup” Usando @capgo/capacitor-login sociale per la capacità nativa in Usando @capgo/capacitor-login sociale, @capgo/capacitor-login sociale per il dettaglio di implementazione in @capgo/capacitor-login sociale, @capgo/capacitor-passkey per il dettaglio di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-biometrica nativa per il dettaglio di implementazione in @capgo/capacitor-biometrica nativa, e Autenticazione a due fattori per il dettaglio di implementazione in Autenticazione a due fattori.