Configurazione di accesso Facebook

Introduzione

In questo guide, imparerai a configurare il Facebook Login con Capgo Social Login. Avrai bisogno dei seguenti:

• Un account Facebook per sviluppatori
• Nome del pacchetto dell'app/ID del bundle
• Accesso a un terminale 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. Aggiungere Facebook Login all'app

   In dashboard dei sviluppatori Facebook, aggiungi il prodotto Facebook Login all'app

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

Informazioni importanti

Ecco dove trovare le informazioni chiave che avrai bisogno per l'integrazione:

1. CLIENT_TOKEN:

   

2. APP_ID:

   

3. APP_NAME:

   

Login di Business Facebook

Questo plugin supporta Facebook Business Login per funzionalità e autorizzazioni relative ai business. Gli account aziendali possono richiedere autorizzazioni aggiuntive oltre a quelle standard per il login dei consumatori, compreso l'accesso a Instagram e la gestione delle pagine.

Le autorizzazioni aziendali supportate includono:

• instagram_basic - Accesso a Instagram Basic Display API
• instagram_manage_insights - Accesso alle informazioni di Instagram
• pages_show_list - Elenco delle pagine gestite dalla persona
• pages_read_engagement - Leggere i dati di engagement dalle pagine
• pages_manage_posts - Gestire i post sulle pagine
• business_management - Gestire gli asset aziendali

- Vedi il - Riferimento alle autorizzazioni di Facebook - per la lista completa delle autorizzazioni.

- Requisiti di configurazione:

1. - Il tuo app Facebook deve essere configurato come un'app aziendale nel Facebook Developer Console.
2. - Le autorizzazioni aziendali possono richiedere una revisione dell'app Facebook prima dell'uso in produzione.
3. - Il tuo app deve rispettare le politiche di utilizzo aziendale di Facebook.

Accesso base 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'],
  },
});

Amministrazione 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 le autorizzazioni aziendali con gli utenti di test e le app di sviluppo prima della revisione dell'app.
• Most business permissions require Facebook App Review before production use.
• Gli API aziendali hanno limiti di tasso diversi. Consultate la documentazione attuale di Facebook prima del lancio.
• Segui il Guida all'integrazione aziendale di Facebook quando si configura l'app.

Configurazione Android

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

   Assicurati che questa riga sia presente:

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

2. Genera il tuo hash di chiave Android

   E' un passaggio di sicurezza cruciale richiesto da Facebook. Apri il terminale e esegui:

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

   Quando viene richiesto un password, utilizzare: android

   Nota

   Per edizioni rilasciate, avrai bisogno di utilizzare il 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 al pannello di controllo del tuo app su Facebook Developers
   2. Naviga a Impostazioni > Fondamentali
   3. Scorri verso il basso nella sezione "Android"
   4. Clicca su "Aggiungi piattaforma" se Android non è ancora aggiunto e riempisci i dettagli
   5. Aggiungi la chiave hash che hai generato
   6. Aggiungi entrambe le chiavi di hash debug e release per la produzione

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 reale del tuo'app Facebook nell' android:scheme attributo

Impostazione iOS

1. Aggiungi la piattaforma iOS nel Console dei sviluppatori Facebook

   1. Accedi al pannello di controllo del tuo'app su Facebook Developers
   2. Naviga a Impostazioni > Fondamentali
   3. Scorri fino in fondo alla pagina e clicca su “Aggiungi piattaforma”
   4. Scegli iOS e completa i dettagli richiesti

2. Apre il tuo progetto Xcode e naviga 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>

   Attento

   Sostituisci i seguenti valori:

   • [APP-ID] con l'ID del tuo app Facebook
   • [CLIENT-TOKEN] con il tuo token client
   • [APP-NAME] con il nome del tuo 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)
           }
       }
   }

Utilizzare Facebook Login nel tuo App

Avvertenza

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. Esegui 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 per iOS): Imposta limitedLogin a true se desideri utilizzare il feature di accesso limitato di Facebook. Questo è un feature disponibile solo su iOS che fornisce maggiore privacy limitando i dati condivisi durante l'accesso.

   Importanti Limitazioni:

   • Solo per iOS: L'accesso limitato influisce solo sui dispositivi iOS e non ha alcun impatto sugli Android
   • Override di 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 pronta a gestire sia scenari di login limitati che completi

   Verifica lo stato di 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);
     }
   }

   Implementazione consigliata se si preferisce l'access_token:

   • Cosa Succede in Login Limitato:Qualche dato utente potrebbe non essere disponibile
   • Tipi di Token diversiGli access token possono avere capacità diverse
   • Conformità alla privacyAiuta a rispettare le norme sulla privacy di iOS

   Importante: Sii sempre sicuri di testare la tua app con entrambi i casi di login limitato e completo per assicurarti che la tua app funzioni correttamente in entrambi i casi. Puoi imparare di più sui casi di login limitato qui. qui.

3. Ottenere i dati del profilo dell'utente

   Dopo un login 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);
       }
     }
   }

   Tip

   Campi di 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: La getProfile questa chiamata funziona solo se hai un token di accesso token di accesso (login standard con tracciamento consentito). Se l'utente ha negato il tracciamento o stai utilizzando il login limitato (token JWT solo), questa chiamata fallirà. In quel caso, utilizza i dati del profilo forniti nella risposta di login iniziale.

⚠️ Critico: Gestione dei Token Backend

Danger

CRITICO COMPORTAMENTO DI iOS: Il login limitato e l'App Tracking Transparency (ATT) sono iOS-UNICO funzionalità. Su Android, riceverai sempre token di accesso indipendentemente dallo stato del tracciamento. limitedLogin impostazioni.

Il comportamento del token iOS:

• limitedLogin: true → Token JWT sempre (solo per iOS)
• limitedLogin: false + L'utente consente il tracking → Token di accesso
• limitedLogin: false + L'utente nega il tracking → Token JWT (iOS sovrascrive automaticamente le tue impostazioni)

Il comportamento del token Android: Token di accesso sempre, limitedLogin l'impostazione è ignorata.

Devi gestire il tuo backend con due tipi diversi di token in quanto gli utenti di iOS possono ricevere sia token di accesso che token JWT a seconda della loro scelta di trasparenza del tracking degli app, mentre gli utenti di Android ricevono sempre token di accesso.

Tipi di Token per Piattaforma

Piattaforma	Impostazione di Login Limitato	Scelta di ATT dell'Utente	Tipo di Token di Risultato
iOS	true	Qualsiasi	Token JWT
iOS	false	Consente il tracking	Token di Accesso
iOS	false	Negazione del tracciamento	Token JWT (override automatico)
Android	Qualsiasi	N/D	Token di Accesso (sempre)

Implementazione del 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 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 del 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 del 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:

• iOSLa scelta dell'utente per la tracciabilità dell'app determina il tipo di token, NON le impostazioni del tuo code. limitedLogin: false)
• Android: riceve sempre i token di accesso, indipendentemente da limitedLogin impostazione
• Limited Login è disponibile solo su iOS - Android ignora completamente questa impostazione

Access Token (Login Standard):

• ✅ Android: sempre disponibile (le restrizioni iOS non si applicano)
• ✅ iOSSolo quando l'utente consente esplicitamente il tracciamento dell'app
• ✅ Può essere utilizzato per accedere al Graph di Facebook API
• ✅ Tempi di scadenza più lunghi
• ✅ Più dati utente disponibili
• ❌ Diventando meno comune su iOS come gli utenti negano sempre più il tracciamento

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 utente base
• ❌ Tempi di scadenza più brevi
• ❌ Nessuna accesso al Graph di Facebook API
• ⚠️ Ora lo scenario più comune per gli utenti di iOS

Comportamento Specifico della Piattaforma:

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

Tip

Essenziale per iOSDevi implementare entrambe le modalità di gestione dei token. Molti sviluppatori iOS suppongono di ricevere sempre i token di accesso e i loro app si rompono quando gli utenti negano il tracking.

Requisiti di contesto sicuro (Web/Capacitor)

Limitazioni di API Criptografico

Il flusso di login aggiornato di Facebook richiede il Web API Criptografico 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
  // ...
}

Problemi di ambiente di sviluppo

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

Ambiente	Crittografia API Disponibile	Funziona l'accesso di 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 alternativa di nonce 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

L'ultima documentazione di Firebase richiede token JWT con nonces per l'autenticazione di Facebook, indipendentemente dalle impostazioni di accesso. Questo approccio funziona sia con 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 a Facebook fallirà a causa delle restrizioni di crittografia API. Utilizzare localhost o HTTPS per il testing web.

Tip

Produzione Sicura: Capacitor applicazioni su iOS/Android eseguono sempre in contesti sicuri, quindi questa limitazione influisce solo sugli ambienti di sviluppo web.

Risoluzione Problemi

Problemi Comuni e Soluzioni

1. Errori di hash chiave su Android

   • Controlla di nuovo che hai aggiunto la chiave hash corretta al dashboard Facebook
   • Aggiungi entrambe le chiavi di hash debug e release per le versioni di rilascio
   • Verifica di utilizzare il keystore corretto quando generi la hash

2. Non compare il pulsante di login Facebook

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

3. Issue comuni su iOS

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

Test

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

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

2. Testa sia le versioni di debug che di rilascio

   • Versione di debug con chiave di hash di debug
   • Versione di rilascio con 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
• Cancellazione dell'accesso
• Gestione degli errori
• Funzionalità di disconnessione

Continua da Facebook Login Setup

Se stai utilizzando Configurazione di accesso Facebook per pianificare l'autenticazione e le flussi di account, connettilo con Utilizzare @capgo/capacitor-login-social per la capacità nativa in Utilizzare @capgo/capacitor-login-social @capgo/capacitor-login-social per il dettaglio di implementazione in @capgo/capacitor-login-social @capgo/capacitor-chiave di accesso per il dettaglio di implementazione in @capgo/capacitor-passkey @capgo/capacitor-biometric-nativo per il dettaglio di implementazione in @capgo/capacitor-biometric-nativo, e Autenticazione a due fattori per il dettaglio di implementazione in Autenticazione a due fattori.