Configurazione di Accesso Facebook
Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.
Introduzione
Sezione intitolata “Introduzione”In questo guide, imparerai a configurare Facebook Login con Capgo Social Login. Avrai bisogno dei seguenti:
- Un account di sviluppatore Facebook
- Il nome del pacchetto o l'ID bundle del tuo'app
- Accesso a un terminale per generare hash chiave (Android)
Configurazione Generale
Sezione intitolata “Configurazione Generale”Se non hai già creato un'app Facebook, segui questi passaggi:
-
Crea un'app Facebook
Segui il tutorial per Crea un'app
-
Aggiungi Facebook Login al tuo app
Nel tuo Dashboard del Developer Facebook, aggiungi il prodotto Facebook Login al tuo app
-
Prima di poter rilasciare il tuo app al pubblico, segui questo tutorial per pubblicarlo
Informazioni importanti
Sezione intitolata “Informazioni importanti”Ecco dove trovare le informazioni chiave che avrai bisogno per l'integrazione:
-
CLIENT_TOKEN:
-
APP_ID:
-
APP_NAME:
Accesso a Facebook Business
Sezione intitolata “Accesso a Facebook Business”Questo plugin supporta l'accesso a Facebook Business per funzionalità e autorizzazioni relative ai business. Le aziende possono richiedere autorizzazioni aggiuntive oltre a quelle standard per il login dei consumatori, compreso l'accesso a Instagram e la gestione delle pagine.
I permessi aziendali supportati includono:
instagram_basic- Accesso a Instagram Basic Display APIinstagram_manage_insights- Accesso a Instagram Insightspages_show_list- Elenco delle pagine gestite dall'utentepages_read_engagement- Leggi i dati di engagement dalle paginepages_manage_posts- Gestisci i post sulle paginebusiness_management- Gestisci gli asset aziendali
Vedi il Riferimento alle autorizzazioni di Facebook per l'elenco completo delle autorizzazioni.
Requisiti di configurazione:
- Il tuo app di Facebook deve essere configurato come un'app aziendale nel Console dello sviluppatore di Facebook.
- Le autorizzazioni aziendali possono richiedere una revisione dell'app di Facebook prima dell'uso in produzione.
- Il tuo app deve rispettare le politiche di utilizzo aziendale di Facebook.
Accesso base di Instagram
Sezione intitolata “Accesso base di 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
Sezione intitolata “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}'], },});Nota importante:
- Puoi testare le autorizzazioni aziendali con gli utenti di test e gli app di sviluppo prima della revisione dell'app.
- La maggior parte delle autorizzazioni aziendali richiede la revisione dell'app di Facebook prima dell'uso in produzione.
- Gli API aziendali hanno limiti di rateo diversi. Consulta la documentazione attuale del platform di Facebook prima del lancio.
- Segui il Guida di integrazione aziendale di Facebook quando si configura l'app.
Configurazione Android
Sottosezione intitolata “Configurazione Android”-
Aggiungi la permessione di rete al tuo
AndroidManifest.xmlAssicurati che questa riga sia presente:
<uses-permission android:name="android.permission.INTERNET"/> -
Genera la tua chiave hash Android
Questo è un passaggio di sicurezza cruciale richiesto da Facebook. Apri il tuo terminale e esegui:
Fenestra del terminale keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64 -AWhen richiesto di una password, utilizza:
android -
Aggiungi il valore hash della chiave al tuo app Facebook
- Vai alla dashboard del tuo app su Facebook Developers
- Naviga a Impostazioni > Base
- Scendi fino alla sezione "Android"
- Clicca su "Aggiungi piattaforma" se Android non è stato aggiunto ancora e riempisci i dettagli
- Aggiungi il valore hash della chiave che hai generato
- Per la produzione, aggiungi sia il valore hash di debug che di release
-
Aggiorna il tuo
AndroidManifest.xmlper includere:<application>...<activity android:name="com.facebook.FacebookActivity"android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation"android:label="@string/app_name" /><activityandroid: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>
Configurazione iOS
Sezione intitolata “Configurazione iOS”-
Aggiungi la piattaforma iOS nel Console dello Sviluppatore Facebook
- Vai alla dashboard del tuo'app su Facebook Developers
- Naviga a Impostazioni > Base
- Scendi fino in fondo alla pagina e clicca su “Aggiungi piattaforma”
- Seleziona iOS e inserisci i dettagli richiesti
-
Apri il tuo progetto Xcode e naviga a Info.plist
-
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> -
Modifica il
AppDelegate.swiftimport FBSDKCoreKit@UIApplicationMainclass AppDelegate: UIResponder, UIApplicationDelegate {func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {// Override point for customization after application launch.// Initialize Facebook SDKFBSDKCoreKit.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 callif (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)}}}
Usando Facebook Login nel tuo App
Sezione intitolata “Usando Facebook Login nel tuo App”-
Inizializza il login Facebook nell'app
import { SocialLogin } from '@capgo/capacitor-social-login';// Initialize during app startupawait SocialLogin.initialize({facebook: {appId: 'APP_ID',clientToken: 'CLIENT_TOKEN',}}) -
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}} -
Ottieni i dati del profilo dell'utente
Dopo il 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 loginasync 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);}}}Limitazione del tipo di token: Il
getProfilefunziona solo quando hai un token di accesso (accesso standard con tracciamento consentito). Se l'utente ha negato il tracciamento o stai utilizzando l'accesso limitato (solo token JWT), questa chiamata fallirà. In tal caso, utilizza i dati del profilo forniti nella risposta di accesso iniziale.
⚠️ Critico: Gestione dei Token Backend
Sezione intitolata “⚠️ Critico: Gestione dei Token Backend”Il tuo backend deve gestire due tipi diversi di token perché gli utenti iOS possono ricevere sia token di accesso che token JWT a seconda della loro scelta di trasparenza sulla tracciatura dell'app, mentre gli utenti Android ricevono sempre token di accesso.
Tipi di Token per Piattaforma
Sezione intitolata “Tipi di Token per Piattaforma”| Piattaforma | Impostazione di login limitato | Scelta del token per l'utente | Tipo di token di risultato |
|---|---|---|---|
| iOS | true | Qualsiasi | Token JWT |
| iOS | false | Consente il tracciamento | Token di accesso |
| iOS | false | Rifiuta il tracciamento | Token JWT (override automatico) |
| Android | Qualsiasi | N/D | Token di accesso (sempre) |
Implementazione del backend
Sottosezione intitolata “Implementazione del backend”-
Determina 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);}} -
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 validationtry {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;}} -
Validazione JWT Backend
// Backend: Validate JWT token from Facebookimport 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-claimsconst 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 JWTconst userInfo = {id: decoded.sub,email: decoded.email,name: decoded.name,isJWTAuth: true};// Create your app's session/tokenconst 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' });}}); -
Manutentore di token Backend generico
// Handle both token types in your backendasync function authenticateFacebookUser(tokenData: any) {if (tokenData.accessToken) {// Handle access token - validate with Facebook Graph APIconst 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-claimsconst 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
Sezione intitolata “Considerazioni chiave”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
- ✅ Disponibile maggiori dati utente
- ❌ Becoming meno comune su iOS poiché gli utenti negano sempre più il tracking
Token JWT (Modalità Privacy iOS solo):
- ❌ 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
- ❌ Nessun 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
Requisiti di contesto sicuro (Web/Capacitor)
Sezione intitolata “Requisiti di contesto sicuro (Web/Capacitor)”Limitazioni di API crittografico
Sezione intitolata “Limitazioni di API crittografico”Il nuovo flusso di accesso Facebook richiede l'aggiornamento Web API crittografico per la generazione del 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
Sezione intitolata “Problemi di ambiente di sviluppo”Problema comune: ionic serve con URL HTTP rompe l'autenticazione di Facebook
| Ambiente | Crypto 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 di Capacitor
Soluzioni per lo sviluppo di Capacitor-
Usa localhost per il testing web
Fenestra del terminale # Instead of ionic serve --host=0.0.0.0ionic serve --host=localhost -
Abilita HTTPS in Ionic
Fenestra del terminale ionic serve --ssl -
Testa su dispositivi reali
Fenestra del terminale # Capacitor apps run in secure context on devicesionic cap run iosionic cap run android -
Generazione di nonce alternativa per lo sviluppo
async function generateNonce() {if (typeof crypto !== 'undefined' && crypto.subtle) {// Secure context - use crypto.subtlereturn 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
Sezione intitolata “Nota di integrazione con Firebase”La documentazione Firebase più recente richiede token JWT con nonci per l'autenticazione di Facebook, indipendentemente dalle impostazioni di accesso. Questa approccio funziona sia con "e" sia con "and" limitedLogin: true Copia nel portapenne 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 } });: Se si utilizzasu un indirizzo IP di rete (non localhost), l'accesso a Facebook fallirà a causa delle restrizioni di crittografia __CAPGO_KEEP_0__. Utilizzare localhost o HTTPS per il testing web. ionic serve on a network IP (not localhost), Facebook login will fail due to crypto API restrictions. Use localhost or HTTPS for web testing.
Risoluzione dei Problemi
Scheda intitolata “Risoluzione dei Problemi”Issue comuni e soluzioni
Scheda intitolata “Issue comuni e soluzioni”-
Errori di hash chiave su Android
- Controlla di aver aggiunto la chiave hash corretta al dashboard di Facebook
- Assicurati di aver aggiunto sia la chiave hash di debug che di release
- Verifica di utilizzare il keystore corretto per generare la hash
-
Non compare il pulsante di login Facebook
- Verifica che tutte le voci del manifesto siano corrette
- Assicurati che l'ID App e il Token Client di Facebook siano corretti
- Assicurati di aver inizializzato correttamente il SDK
-
Issue comuni 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
-
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
-
Testa sia le versioni debug che release
- Costruisci debug con hash chiave debug
- Costruisci rilascio con hash chiave rilascio
- Testa su entrambi l'emulatore e i dispositivi fisici
Ricorda di testare l'intero flusso di accesso, compreso:
- Accesso riuscito
- Cancellazione dell'accesso
- Gestione degli errori
- Funzionalità di disconnessione
Continua da Facebook Login Setup
Sottosezione intitolata “Continua da Facebook Login Setup”Se stai utilizzando Configurazione di accesso Facebook per pianificare l'autenticazione e le flussi di account, connettilo con Usando @capgo/capacitor-login sociale per la capacità nativa in Usando @capgo/capacitor-login sociale, @capgo/capacitor-login sociale per la dettaglio di implementazione in @capgo/capacitor-login sociale, @capgo/capacitor-passkey per la dettaglio di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-biometrica nativa per la dettaglio di implementazione in @capgo/capacitor-biometrica nativa, e Autenticazione a due fattori per la dettaglio di implementazione in Autenticazione a due fattori.