Facebook 登录设置

简介

In this guide, you will learn how to setup Facebook Login with Capgo Social Login. You will need the following:

• Facebook开发者帐户
• 您的应用程序的包名/捆绑ID
• 访问终端以生成密钥哈希（Android）

通用设置

创建Facebook应用

1. 遵循教程

   创建应用 Create a Facebook App

2. 为您的应用程序添加 Facebook 登录

   在您的 Facebook 开发者控制台中，添加 Facebook 登录产品到您的应用程序

3. 在发布您的应用程序到公众之前，遵循以下 教程 发布它

重要信息

以下是您需要的整合所需的关键信息的位置：

1. CLIENT_TOKEN:

   

2. APP_ID:

   

3. APP_NAME:

   

Android 配置

1. 在您的 AndroidManifest.xml

   确保以下行存在：

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

2. 生成您的 Android 密钥哈希

   这是 Facebook 需要的关键安全步骤。打开您的终端并运行：

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

   当提示输入密码时，请使用： android

   注意

   对于发布版本，您需要使用您的发布 keystore：

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

3. 将密钥哈希添加到您的Facebook应用

   1. 转到Facebook开发者平台上的您的应用的控制台
   2. 导航到设置 > 基本
   3. 滚动到“Android”部分
   4. 如果Android尚未添加，请点击“添加平台”，并填写详细信息
   5. 添加您生成的密钥哈希
   6. 对于生产环境，添加两种密钥哈希（debug和release）

4. 更新您的 AndroidManifest.xml 以包含：

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

   注意

   请确保替换 [APP_ID] 为您的实际Facebook应用ID android:scheme 属性

iOS设置

1. 前往您的Facebook开发者应用程序的控制台

   1. 导航到设置 > 基本
   2. 滚动到页面底部并点击“添加平台”
   3. 选择iOS并填写所需详细信息
   4. __CAPGO_KEEP_0__

2. 打开您的 Xcode 项目并导航到 Info.plist

3. 在 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>

   注意

   替换以下值：

   • [APP-ID] 使用您的 Facebook 应用 ID
   • [CLIENT-TOKEN] 使用您的客户端令牌
   • [APP-NAME] 使用您的应用名称

4. 修改 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)
           }
       }
   }

在您的应用中使用 Facebook 登录

注意

开始之前:请记住，新的 Facebook SDK 将令牌类型取决于用户的 App 跟踪选择，而不是您的 code 配置。始终在后端实现访问令牌和 JWT 令牌处理，以确保所有用户的身份验证都能正常工作。

1. 在应用中初始化 Facebook 登录

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

2. 实现登录功能

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

   注意

   受限登录（仅限 iOS）: 设置 limitedLogin 如果您想使用Facebook的有限登录功能，请将其设置为true。该功能仅适用于iOS，提供了更好的隐私保护，通过限制登录期间共享的数据。

   重要限制：

   • iOS Only: 有限登录仅影响iOS设备，对Android无影响
   • ATT Override: 即使您设置了 limitedLogin: false, Facebook也会自动将其强制设置为 true 如果用户尚未授予App跟踪透明度（ATT）权限
   • 始终处理两种情况: 应用程序应始终准备好处理有限和完整登录场景

   检查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'

   如果优先使用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);
     }
   }

   有限登录的发生过程：

   • 数据访问减少:某些用户数据可能不可用
   • 不同类型的令牌:访问令牌可能具有不同的能力
   • 隐私合规:帮助遵守iOS隐私要求

   :始终测试您的应用程序以有限和完整登录场景，以确保您的应用程序在两种情况下都能正常工作。您可以了解更多关于有限登录的信息您可以了解更多关于Limited Login here.

3. 获取用户资料

   登录成功后，您可以获取更多的资料信息：

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

   提示

   可用资料字段:您可以请求Facebook的图形API中可用的任何字段，常见字段包括： id, name, email, first_name, last_name, picture, birthday, gender, location, hometown注意：某些字段可能需要额外的权限。

   令牌类型限制:该 getProfile 调用仅在您有令牌时才有效 访问令牌 (标准登录允许跟踪). 如果用户拒绝跟踪或您正在使用有限登录（仅限 JWT 令牌），则此调用将失败。 在这种情况下，请使用初始登录响应中提供的配置文件数据。

⚠️ Critical: 后端令牌处理

危险

CRITICAL iOS 行为: iOS 仅限的 Limited Login 和 App Tracking Transparency（ATT）功能 iOS-ONLY Android 上始终会收到访问令牌，无论设置如何。 limitedLogin iOS 令牌行为

access token:

• limitedLogin: true → 只有 iOS 设备才会使用 JWT token
• limitedLogin: false + 用户允许跟踪 → 访问令牌
• limitedLogin: false + 用户拒绝跟踪 → iOS 设备会自动覆盖您的设置，使用 JWT token

Android 设备行为: 总是使用访问令牌， limitedLogin 设置会被忽略。

您的后端必须处理 两个不同的令牌类型 因为 iOS 用户可以根据 App Tracking Transparency 选择接收访问令牌或 JWT 令牌，而 Android 用户总是会接收访问令牌。

各个平台的令牌类型

平台	受限登录设置	用户ATT选择	结果令牌类型
iOS	true	任何	JWT令牌
iOS	false	允许跟踪	访问令牌
iOS	false	拒绝跟踪	__CAPGO_KEEP_0__
Android	任何	N/A	__CAPGO_KEEP_0__ (始终)

后端实现

1. 检测令牌类型并处理

   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. 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. 后端 JWT 验证

   // 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. 通用后端令牌处理器

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

重要考虑因素

危险

严重 iOS-Only 理解:

• iOS: 用户的 App 跟踪选择决定令牌类型，而不是您的 code 设置（即使在 limitedLogin: false)
• Android: 无论设置如何, 都会始终接收访问令牌 limitedLogin 设置
• 仅限 iOS - Android 完全忽略此设置

标准登录访问令牌:

• ✅ Android: iOS 限制不适用, 始终可用
• ✅ iOS: 只有当用户明确允许应用跟踪时
• ✅ 可用于访问 Facebook Graph API
• ✅ 可获得更长的过期时间
• ✅ 可获得更多用户数据
• ❌ 在 iOS 上变得越来越少见 因为用户越来越多地拒绝跟踪

JWT Token (仅限 iOS 私有模式):

• ❌ Android: 从未发生 (不受支持)
• ✅ iOS: 当跟踪被拒绝或 limitedLogin: true
• ✅ 遵守 iOS 用户隐私偏好
• ❌ 只包含基本用户信息
• ❌ 过期时间更短
• ❌ 无法访问 Facebook Graph API
• ⚠️ 现在是 iOS 用户中最常见的场景

平台特定行为:

• iOS应用: 必须处理两种类型的令牌：访问令牌和 JWT 令牌
• Android应用: 只需处理访问令牌
• 跨平台应用: 必须实现两种令牌处理方法

提示

iOS必备：您必须实现两种令牌处理方法。许多iOS开发者假设他们总是会获得访问令牌，但当用户拒绝跟踪时，应用程序会崩溃。安全上下文要求 (Web/__CAPGO_KEEP_0__)

Secure Context Requirements (Web/Capacitor)

Crypto API Limitations

The updated Facebook login flow requires the Web Crypto API for nonce generation, which is only available in secure contexts:

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

Development Environment Issues

Common Problem: ionic serve with HTTP URLs breaks Facebook authentication

环境	Crypto API 可用	Facebook 登录已启用
http://localhost:3000	✅ 是	✅ 是
http://127.0.0.1:3000	✅ 是	✅ 是
http://192.168.1.100:3000	❌ 否	❌ 否
https://any-domain.com	✅ 是	✅ 是

Solutions for Capacitor Development

1. 使用localhost进行web测试

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

2. 在Ionic中启用HTTPS

   ionic serve --ssl

3. 在实际设备上测试

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

4. 开发环境中的替代nonce生成

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

Firebase 集成注意事项

最近的 Firebase 文档要求使用 JWT 令牌和非法令牌（nonce）进行 Facebook 验证，完全不受登录设置的影响。这一方法适用于两种情况 limitedLogin: true 和 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
     }
   });

开发限制: 如果您在使用 ionic serve on a network IP (not localhost), Facebook login will fail due to crypto API restrictions. Use localhost or HTTPS for web testing.

限制而失败。请使用本地主机或 HTTPS 进行 Web 测试。

提示提示：Capacitor iOS/Android 应用程序始终在安全上下文中运行，因此这一限制仅影响 Web 开发环境。

故障排除

常见问题和解决方案

1. Android 上的密钥哈希错误

   • 请确认您已在 Facebook 控制台中添加了正确的密钥哈希
   • 对于发布版本，请确保已添加了 debug 和 release 密钥哈希
   • 生成哈希时，请确认您正在使用正确的 keystore

2. Facebook 登录按钮未显示

   • 请确认所有清单条目都是正确的
   • 请确认您的 Facebook App ID 和 Client Token 是正确的
   • 请确认已正确初始化 SDK

3. 常见iOS问题

   • 确保所有Info.plist条目都是正确的
   • 验证URL方案是否正确配置
   • 检查您的包ID是否与Facebook控制台中注册的包ID匹配

测试

1. 在Facebook开发者控制台中添加测试用户之前进行测试

   • 转到角色>测试用户
   • 创建测试用户
   • 使用这些凭据进行测试

2. 测试两种构建方式：debug和release

   • 使用debug密钥哈希的debug构建
   • 使用发布密钥哈希发布构建
   • 在模拟器和物理设备上测试

请记住测试完整的登录流程，包括：

• 成功登录
• 取消登录
• 错误处理
• 注销功能