Configuration de connexion Facebook

Introduction

Dans ce guide, vous apprendrez à configurer l'authentification Facebook avec Capgo Social Login. Vous aurez besoin des éléments suivants :

• Un compte développeur Facebook
• Le nom de votre package / ID de votre ensemble
• Accès à un terminal pour la génération des hachages de clé (Android)

Paramètres Généraux

Si vous n'avez pas encore créé une application Facebook, suivez ces étapes :

1. Créer une Application Facebook

   Suivez le tutoriel pour Créer une Application

2. Ajouter l'authentification Facebook à votre application

   Dans votre tableau de bord du développeur Facebook, ajoutez le produit d'authentification Facebook à votre application

3. Avant de pouvoir rendre votre application publique, suivez ce tutoriel pour la publication

Information importante

Voici où trouver les informations clés nécessaires à l'intégration :

1. CLIENT_TOKEN:

   

2. APP_ID:

   

3. APP_NAME:

   

Connexion Facebook Entreprise

Cette extension prend en charge la connexion Facebook Entreprise pour les fonctionnalités et les autorisations liées aux entreprises. Les comptes d'entreprise peuvent demander des autorisations supplémentaires au-delà des autorisations standard de connexion de consommateur, notamment la gestion d'Instagram et de Pages.

Les autorisations commerciales prises en charge incluent :

• instagram_basic - Accès à Instagram Basic Display API
• instagram_manage_insights - Accès aux informations d'Instagram
• pages_show_list - Liste des pages gérées par la personne
• pages_read_engagement - Lire les données d'engagement des Pages
• pages_manage_posts - Gestion des publications sur les pages
• business_management - Gestion des actifs commerciaux

Voir les Référence des autorisations Facebook pour la liste complète des autorisations.

Exigences de configuration :

1. Votre application Facebook doit être configurée en tant qu'application commerciale dans le console du développeur Facebook.
2. Business permissions may require Facebook App Review before production use.
3. Votre application doit respecter les politiques de cas d'utilisation commercial de Facebook.

Accès de 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'],
  },
});

Gestion des pages

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

Remarques importantes :

• You can test business permissions with test users and development apps before App Review.
• Most business permissions require Facebook App Review before production use.
• Les API commerciales ont des limites de taux différents. Consultez la documentation actuelle du plateau de Facebook avant le lancement.
• Suivez le Guide d'intégration commerciale Facebook lors de la configuration de l'application.

Configuration Android

1. Ajoutez la permission d'internet à votre AndroidManifest.xml

   Assurez-vous que cette ligne est présente :

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

2. Générez votre hachage de clé Android

   C'est un étape de sécurité cruciale requise par Facebook. Ouvrez votre terminal et exécutez :

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

   Lorsqu'un mot de passe est demandé, utilisez : android

   Note

   Pour les builds de production, vous devrez utiliser votre clé de production :

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

3. Ajoutez l'empreinte de clé à votre application Facebook

   1. Go to your app’s dashboard on Facebook Developers
   2. Naviguez vers Paramètres > Général
   3. Descendez jusqu'à la section « Android »
   4. Cliquez sur « Ajouter une plateforme » si Android n'est pas ajouté encore et renseignez les détails
   5. Ajoutez l'empreinte de clé que vous avez générée
   6. Ajoutez les deux hachages de clé de débogage et de production.

4. Mettez à jour votre AndroidManifest.xml pour y inclure :

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

   Attention

   Vérifiez de remplacer [APP_ID] par votre ID d'application Facebook réel dans le android:scheme attribut

Configuration iOS

1. Ajoutez la plateforme iOS dans le console du développeur Facebook

   1. Allez dans l'interface de votre application sur Facebook Developers
   2. Naviguez dans Paramètres > Général
   3. Descendez jusqu'à la fin de la page et cliquez sur « Ajouter une plateforme »
   4. Choisissez iOS et renseignez les détails requis

2. Ouvrez votre projet Xcode et naviguez jusqu'à Info.plist

3. Ajoutez les entrées suivantes à votre 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>

   Attention

   Remplacez les valeurs suivantes :

   • [APP-ID] par votre ID d'application Facebook
   • [CLIENT-TOKEN] par votre jeton client
   • [APP-NAME] par le nom de votre application

4. Modifiez le 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)
           }
       }
   }

Utilisation de la connexion Facebook dans votre application

Attention

Avant de commencerN'oubliez pas que avec la nouvelle Facebook SDK, le type de jeton que vous recevez dépend entièrement de la choix de suivi de l'application de l'utilisateur, et non de votre code configuration. Assurez-vous toujours de mettre en œuvre la gestion des jetons d'accès et JWT dans votre backend pour que l'authentification fonctionne pour tous les utilisateurs.

1. Initialiser la connexion Facebook dans votre application

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

2. Mettre en œuvre la fonction de connexion

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

   Remarque

   Connexion limitée (iOS uniquement): Définir limitedLogin à true si vous souhaitez utiliser la fonctionnalité de connexion limitée de Facebook. Cette fonctionnalité est réservée aux appareils iOS et offre une meilleure protection de la vie privée en limitant les données partagées lors de la connexion.

   Limitations importantes :

   • iOS uniquement: Seul l'accès limité affecte les appareils iOS et n'a aucun impact sur Android
   • Forcer l'ATT: Même si vous définissez limitedLogin: false, Facebook forceront automatiquement à true si l'utilisateur n'a pas accordé la permission d'App Tracking Transparency (ATT)
   • Gérer toujours les deux cas: Votre application doit toujours être prête à gérer les deux scénarios de connexion limitée et complète

   Vérification de l'état d'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'

   Implémentation recommandée si access_token est préféré :

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

   Qu'est-ce qui se passe lors d'un accès limité :

   • Accès réduit aux données: Some user data may not be available
   • Types de jetons différents: Les jetons d'accès peuvent avoir différentes capacités
   • Conformité à la vie privée: Aide à se conformer aux exigences de confidentialité d'iOS

   Important: Toujours testez votre application avec les deux scénarios de connexion limitée et complète pour vous assurer que votre application fonctionne correctement dans les deux cas. Vous pouvez en savoir plus sur la connexion limitée ici.

3. Obtenir les données du profil de l'utilisateur

   Après une connexion réussie, vous pouvez récupérer des informations de profil supplémentaires :

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

   Conseil

   Champs de profil disponiblesVous pouvez demander n'importe quel champ disponible dans le graphique Facebook API. Les champs courants incluent : id, name, email, first_name, last_name, picture, birthday, gender, location, hometown. Notez que certains champs peuvent nécessiter des permissions supplémentaires.

   Limitation du type de jeton: La getProfile se produit uniquement lorsque vous disposez d'un jeton d'accès (standard login with tracking allowed). If the user denied tracking or you’re using limited login (JWT token only), this call will fail. In that case, use the profile data provided in the initial login response.

⚠️ Critique : Gestion des Jetons de Serveur

Danger

CRITIQUE IMPORTANT SUR iOS: Limitations de connexion et de traçabilité des applications (TAT) sont iOS-ONLY accès. Sur Android, vous recevrez toujours des jetons d'accès, quel que soit le limitedLogin configuration.

Comportement du jeton iOS:

• limitedLogin: true → Toujours un jeton JWT (iOS uniquement)
• limitedLogin: false + L'utilisateur autorise le suivi → Jeton d'accès
• limitedLogin: false + L'utilisateur refuse le suivi → Jeton JWT (iOS remplace automatiquement votre configuration)

Comportement du jeton Android: Toujours un jeton d'accès, limitedLogin la configuration est ignorée.

Votre serveur doit gérer deux types de jetons différents puisque les utilisateurs d'iOS peuvent recevoir soit des jetons d'accès, soit des jetons JWT en fonction de leur choix de transparence de l'application, tandis que les utilisateurs Android reçoivent toujours des jetons d'accès.

Types de jetons par plateforme

Plateforme	Paramètre de connexion limitée	Choix de l'utilisateur ATT	Type de jeton résultat
iOS	true	Tout	Jeton JWT
iOS	false	Permet le suivi	Jeton d'accès
iOS	false	Refuse le suivi	Jeton JWT (auto-remplacement)
Android	Tout	N/A	Jeton d'accès (toujours)

Mise en œuvre du serveur

1. Déterminez le type de jeton et traitez-l’en conséquence

   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. Exemple d'intégration 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. Validation JWT côté serveur

   // 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. Gestionnaire de jeton de serveur générique

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

Considérations clés

Danger

Compréhension critique iOS uniquement:

• iOSL'option de suivi de l'application de l'utilisateur détermine le type de jeton, PAS vos paramètres code. limitedLogin: false)
• Android: Toujours reçoit des jetons d'accès, quel que soit limitedLogin paramètre
• Limited Login est RESERVÉ AUX APPAREILS IOS - Android ignore complètement ce paramètre

Jeton d'accès (Connexion standard):

• ✅ Android: Toujours disponible (les restrictions iOS ne s'appliquent pas)
• ✅ iOS: Only when user explicitly allows app tracking
• ✅ Peut être utilisé pour accéder au graphique de Facebook API
• ✅ Temps d'expiration plus longs
• ✅ Plus d'informations utilisateur disponibles
• ❌ Devenant moins courant sur iOS Les utilisateurs dénient de plus en plus le suivi.

JWT Token (iOS-Only Privacy Mode):

• ❌ Android: Jamais se produit (non pris en charge)
• ✅ iOS: Lorsque le suivi est refusé ou limitedLogin: true
• ✅ Respects iOS user privacy preferences
• ❌ Contient uniquement des informations utilisateur de base
• ❌ Temps d'expiration plus courts
• ❌ Aucun accès au graphique Facebook API
• ⚠️ Now the most common scenario for iOS users

Comportement spécifique au plateforme:

• Applications iOS: Doit gérer à la fois les jetons d'accès ET les jetons JWT
• Applications Android: N'ont besoin que de gérer les jetons d'accès
• Applications cross-plateformes: Doit mettre en œuvre les deux méthodes de gestion des jetons

Conseil

Essentiel pour iOSVous devez mettre en œuvre les deux méthodes de gestion des jetons. Beaucoup de développeurs iOS supposent qu'ils auront toujours accès aux jetons d'accès et leurs applications s'effondrent lorsque les utilisateurs refusent le suivi.

Exigences de Contexte Sécurisé (Web/Capacitor)

Limitations de Crypto API

Le flux de connexion Facebook mis à jour nécessite le Web Crypto API pour la génération de nonce, qui n'est disponible que dans contextes sécurisés:

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

Problèmes de l'environnement de développement

Problème courant: ionic serve avec les URL HTTP brise l'authentification Facebook

Environnement	Crypto API Disponible	Facebook Login fonctionne
http://localhost:3000	✅ Oui	✅ Oui
http://127.0.0.1:3000	✅ Oui	✅ Oui
http://192.168.1.100:3000	❌ Non	❌ Non
https://any-domain.com	✅ Oui	✅ Oui

Solutions pour le développement Capacitor

1. Utilisez localhost pour les tests web

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

2. Activer HTTPS dans Ionic

   ionic serve --ssl

3. Tester sur des appareils réels

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

4. Alternative génération de nonce pour le développement

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

Note d'intégration Firebase

Recentes documents Firebase nécessitent des jetons JWT avec des nonces pour l'authentification Facebook, quel que soit les paramètres de connexion. Cette approche fonctionne avec les deux. limitedLogin: true et 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
     }
   });

Limitation du développement: Si vous utilisez ionic serve sur un réseau IP (pas localhost), l'authentification Facebook échouera en raison des restrictions de crypto API . Utilisez localhost ou HTTPS pour les tests web.

Conseil

Production SécuritéLes applications Capacitor sur iOS/Android fonctionnent toujours dans des contextes sécurisés, ce qui n'affecte donc que les environnements de développement web.

Troubleshooting

Problèmes courants et solutions

1. Erreurs de hachage clé sur Android

   • Vérifiez que vous avez ajouté la bonne clé de hachage au tableau de bord Facebook
   • Pour les builds de production, assurez-vous d'avoir ajouté les clés de hachage de débogage et de production
   • Vérifiez que vous utilisez le bon fichier de clé de stockage lors de la génération du hachage

2. Le bouton de connexion Facebook n'apparaît pas

   • Vérifiez que toutes les entrées de manifest sont correctes
   • Vérifiez que votre ID d'application Facebook et votre jeton client sont corrects
   • Assurez-vous d'avoir correctement initialisé le SDK

3. Problèmes iOS courants

   • Assurez-vous que toutes les entrées de Info.plist sont correctes
   • Vérifiez que les schémas d'URL sont correctement configurés
   • Vérifiez que votre ID de bundle correspond à celui enregistré dans le tableau de bord Facebook

Test

1. Avant de tester, ajoutez des utilisateurs de test dans le Console du Développeur Facebook

   • Allez dans Rôles > Utilisateurs de test
   • Créez un utilisateur de test
   • Utilisez ces informations pour les tests

2. Testez les versions de débogage et de production.

   • Éditeur de débogage avec clé de hachage de débogage
   • Release build with release key hash
   • Testez sur les deux émulateurs et les appareils physiques

N'oubliez pas de tester la connexion complète, notamment :

• Connexion réussie
• Annulation de la connexion
• Gestion des erreurs
• Fonctionnalité de déconnexion

Continuez de la configuration de connexion Facebook

Si vous utilisez Configuration de connexion Facebook pour planifier l'authentification et les flux de compte, connectez-l’avec Utilisation de @capgo/capacitor-social-login pour la capacité native dans Utilisation de @capgo/capacitor-social-login @capgo/capacitor-connexion-social pour le détail d'implémentation dans @capgo/capacitor-social-login @capgo/capacitor-passkey pour le détail d'implémentation dans @capgo/capacitor-passkey @capgo/capacitor-native-biometrique pour le détail d'implémentation dans @capgo/capacitor-native-biometric, et Authentification à deux facteurs pour le détail d'implémentation dans Authentification à deux facteurs.