Configurazione di Facebook Login

Introduzione

In questa guida imparerai come configurare il Facebook Login con Capgo Social Login. Avrai bisogno di quanto segue:

• Un account Facebook Developer
• Il package name/bundle ID della tua app
• Accesso a un terminale per generare i key hash (Android)

Configurazione generale

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

1. Crea un'app Facebook

   Segui il tutorial per Creare un'app

2. Aggiungere Facebook Login alla tua app

   Nel tuo Facebook Developer Dashboard, aggiungi il prodotto Facebook Login alla tua app

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

Informazioni Importanti

Ecco dove trovare le informazioni chiave necessarie per l'integrazione:

1. CLIENT_TOKEN:

   

2. APP_ID:

   

3. APP_NAME:

   

Facebook Business Login

Questo plugin supporta Facebook Business Login per funzionalità e permessi aziendali. Gli account Business possono richiedere permessi aggiuntivi rispetto al login consumer standard, inclusa la gestione di Instagram e delle Pagine.

I permessi business supportati includono:

• instagram_basic - Accesso a Instagram Basic Display API
• instagram_manage_insights - Accesso a Instagram Insights
• pages_show_list - Elenco delle Pagine gestite dall'utente
• pages_read_engagement - Lettura dei dati di engagement delle Pagine
• pages_manage_posts - Gestione dei post sulle Pagine
• business_management - Gestisci gli asset aziendali

Guarda il Riferimento permessi Facebook per l'elenco completo dei permessi.

Requisiti di configurazione:

1. La tua app Facebook deve essere configurata come app Business nella Facebook Developer Console.
2. I permessi Business potrebbero richiedere l'App Review di Facebook prima dell'uso in produzione.
3. La tua app deve rispettare le policy di Facebook relative ai Business Use Case.

Accesso di base a Instagram

await SocialLogin.initialize({
  facebook: {
    appId: 'your-business-app-id',
    clientToken: 'your-client-token',
  },
});

const res = await SocialLogin.login({
  provider: 'facebook',
  options: {
    permissions: [
      'email',
      'public_profile',
      'instagram_basic',
      'pages_show_list',
      'pages_read_engagement',
    ],
  },
});

const profile = await SocialLogin.providerSpecificCall({
  call: 'facebook#getProfile',
  options: {
    fields: ['id', 'name', 'email', 'instagram_business_account'],
  },
});

Gestione delle Pagine

const res = await SocialLogin.login({
  provider: 'facebook',
  options: {
    permissions: [
      'email',
      'pages_show_list',
      'pages_manage_posts',
      'pages_read_engagement',
    ],
  },
});

const profile = await SocialLogin.providerSpecificCall({
  call: 'facebook#getProfile',
  options: {
    fields: ['id', 'name', 'accounts{id,name,instagram_business_account}'],
  },
});

Note importanti:

• Puoi testare i permessi business con utenti di test e app di sviluppo prima dell'App Review.
• La maggior parte dei permessi aziendali richiede la Facebook App Review prima dell'uso in produzione.
• Le Business API hanno limiti di velocità differenti. Consulta la documentazione ufficiale di Facebook prima del lancio.
• Segui lo standard Guida all'integrazione di Facebook Business durante la configurazione dell'app.

Configurazione Android

1. Aggiungi il permesso internet alla tua AndroidManifest.xml

   Assicurati che questa riga sia presente:

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

2. Genera l'hash della chiave Android

   Questo è un passaggio di sicurezza fondamentale richiesto da Facebook. Apri il terminale ed esegui:

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

   Quando ti viene chiesta la password, usa: android

   Nota

   Per le build di release, dovrai usare il tuo keystore di release:

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

3. Aggiungi il key hash alla tua app Facebook

   1. Vai alla dashboard della tua app su Facebook Developers
   2. Vai su Settings > Basic
   3. Scorri fino alla sezione “Android”
   4. Clicca su “Add Platform” se Android non è ancora presente e inserisci i dettagli
   5. Aggiungi il key hash che hai generato
   6. Per la produzione, aggiungi sia il debug che il release key hash

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 il tuo ID app Facebook effettivo nell' android:scheme attributo

Setup iOS

1. Aggiungi la piattaforma iOS nella Facebook Developer Console

   1. Vai alla dashboard della tua app su Facebook Developers
   2. Vai su Settings > Basic
   3. Scorri fino in fondo alla pagina e clicca su “Add Platform”
   4. Seleziona iOS e compila i dettagli richiesti

2. Apri il tuo progetto Xcode e vai su 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 il tuo Facebook app ID
   • [CLIENT-TOKEN] con il tuo client token
   • [APP-NAME] con il nome della tua 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)
           }
       }
   }

Usare Facebook Login nella tua app

Attenzione

Prima di iniziare: Ricorda che con il nuovo SDK di Facebook, il tipo di token che ricevi dipende interamente dalla scelta di App Tracking dell’utente, non dalla tua configurazione code. Implementa sempre nel backend la gestione sia dell’access token sia del JWT token, così l’autenticazione funziona per tutti gli utenti.

1. Inizializza il login Facebook nella tua 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

   Limited Login (solo iOS): Imposta limitedLogin a true se vuoi usare la funzione Limited Login di Facebook. È una funzionalità solo iOS che offre maggiore privacy limitando i dati condivisi durante il login.

   Limitazioni importanti:

   • Solo iOS: Il Limited Login influisce solo sui dispositivi iOS e non ha impatto su Android
   • Override ATT: Anche se imposti limitedLogin: false, Facebook lo forzerà automaticamente a true se l'utente non ha concesso il permesso App Tracking Transparency (ATT)
   • Gestisci sempre entrambi i casi: La tua app deve essere sempre pronta a gestire sia il login limitato che quello completo

   Controllo dello 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 preferisci l'access_token:

   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 con il Limited Login:

   • Accesso ai dati ridotto: Some user data may not be available
   • Diversi tipi di token: Gli access token potrebbero avere capacità differenti
   • Conformità alla privacy: Aiuta a rispettare i requisiti di privacy di iOS

   Importante: Testa sempre la tua app sia con il login limitato che con quello completo per assicurarti che funzioni correttamente in entrambi i casi. Puoi saperne di più sul Limited Login qui.

3. Ottieni i dati del profilo utente

   Dopo un login riuscito, puoi recuperare ulteriori informazioni sul profilo:

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

   Tip

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

   Limitazione del tipo di token: Il getProfile la chiamata funziona solo se hai un token di accesso (login standard con tracking consentito). Se l'utente ha negato il tracking o stai usando il limited login (solo token JWT), la chiamata fallirà. In tal caso, usa i dati del profilo forniti nella risposta di login iniziale.

⚠️ Critico: Gestione Token Backend

Pericolo

COMPORTAMENTO CRITICO su iOS: Limited Login e App Tracking Transparency (ATT) sono funzionalità SOLO per iOS. Su Android riceverai sempre gli access token, limitedLogin setting.

Comportamento Token su iOS:

• limitedLogin: true → Sempre token JWT (solo iOS)
• limitedLogin: false + L'utente ACCETTA il tracking → Access token
• limitedLogin: false + L'utente NEGA il tracciamento → JWT token (iOS sovrascrive automaticamente la tua impostazione)

Comportamento token su Android: Sempre access token, limitedLogin l'impostazione viene ignorata.

Il tuo backend deve gestire due diversi tipi di token perché gli utenti iOS possono ricevere access token o JWT token in base alla scelta di App Tracking Transparency, mentre gli utenti Android ricevono sempre access token.

Tipi di token per piattaforma

Piattaforma	Impostazione limitedLogin	Scelta ATT dell'utente	Tipo di token restituito
iOS	true	Qualsiasi	Token JWT
iOS	false	Consente il tracking	Token di accesso
iOS	false	Nega il tracking	Token JWT (override automatico)
Android	Qualsiasi	N/A	Access Token (sempre)

Implementazione Backend

1. Rileva 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 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 lato 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. Gestore generico del token backend

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

Informazioni critiche solo per iOS:

• iOS: La scelta dell'utente su App Tracking determina il tipo di token, NON le tue impostazioni code (anche se limitedLogin: false)
• Android: Riceve sempre access token, indipendentemente dalle limitedLogin impostazioni
• Limited Login è disponibile solo per iOS - Android ignora completamente questa impostazione

Access Token (Login Standard):

• ✅ Android: Sempre disponibile (le restrizioni iOS non si applicano)
• ✅ iOS: Solo se l'utente autorizza esplicitamente il tracking
• ✅ Può essere usato per accedere a Facebook Graph API
• ✅ Tempi di scadenza più lunghi
• ✅ Più dati utente disponibili
• ❌ Sta diventando meno comune su iOS poiché gli utenti negano sempre più il tracking

JWT Token (Modalità privacy solo iOS):

• ❌ Android: Non si verifica mai (non supportato)
• ✅ iOS: Quando il tracciamento è negato o limitedLogin: true
• ✅ Rispetta le preferenze privacy su iOS
• ❌ Contiene solo info utente base
• ❌ Tempi di scadenza più brevi
• ❌ Nessun accesso a Facebook Graph API
• ⚠️ Ora lo scenario più comune per gli utenti iOS

Comportamento specifico per piattaforma:

• App iOS: Deve gestire sia gli access token che i token JWT
• App Android: Deve gestire solo gli access token
• App cross-platform: Deve implementare entrambi i metodi di gestione dei token

Tip

Essenziale per iOS: DEVI implementare entrambi i metodi di gestione dei token. Molti sviluppatori iOS danno per scontato di ricevere sempre access token, ma le loro app si rompono quando gli utenti negano il tracciamento.

Requisiti per il contesto sicuro (Web/Capacitor)

Limitazioni Crypto API

Il flusso di login aggiornato di Facebook richiede Web Crypto API per la generazione del nonce, disponibile solo in 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
  // ...
}

Problemi nell'ambiente di sviluppo

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

Ambiente	Crypto API disponibile	Facebook Login Funziona
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 i test web

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

2. Abilita HTTPS in Ionic

   ionic serve --ssl

3. Test su dispositivi reali

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

4. Generazione 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 sull'integrazione Firebase

La recente documentazione di Firebase richiede token JWT con nonce per l'autenticazione Facebook, indipendentemente dalle impostazioni di login. Questo approccio funziona con entrambi 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 in Sviluppo: Se utilizzi ionic serve su un IP di rete (non localhost), il login di Facebook fallirà a causa delle restrizioni crypto di API. Usa localhost o HTTPS per i test web.

Tip

Sicurezza in Produzione: Le app Capacitor su iOS/Android girano sempre in contesti sicuri, quindi questa limitazione riguarda solo gli ambienti di sviluppo web.

Risoluzione problemi

Problemi comuni e soluzioni

1. Errori del key hash su Android

   • Verifica di aver aggiunto il key hash corretto al dashboard di Facebook
   • Per i build di release, assicurati di aver aggiunto sia il debug che il release key hash
   • Verifica di usare il keystore corretto durante la generazione dell'hash

2. Il tasto di login di Facebook non appare

   • Verifica che tutte le voci nel manifest siano corrette
   • Controlla che il Facebook App ID e il Client Token siano corretti
   • Assicurati di aver inizializzato correttamente SDK

3. Problemi comuni su iOS

   • Assicurati che tutte le voci in Info.plist siano corrette
   • Verifica che gli URL scheme siano configurati correttamente
   • Controlla che il bundle ID corrisponda a quello registrato nel dashboard di Facebook

Test

1. Prima di testare, aggiungi utenti di test nella Facebook Developer Console

   • Vai su Roles > Test Users
   • Crea un utente di test
   • Usa queste credenziali per il testing

2. Testa sia le build di debug che quelle di release

   • Build di debug con debug key hash
   • Build di release con release key hash
   • Testa sia su emulatore che su dispositivi fisici

Ricorda di testare l'intero flusso di login, inclusi:

• Login completato con successo
• Annullamento del login
• Gestione degli errori
• Funzionalità di logout

Continua dalla configurazione di Facebook Login

Se stai usando Configurazione di Facebook 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.