flutter_facebook_auth 7.3.2

flutter_facebook_auth: ^7.3.2 copied to clipboard

The complete, production-ready solution to integrate Facebook Login across all Flutter platforms.

📱 Platform Support #

📑 Table of Contents #

• Features
• Installation
• Platform Setup
  • Android Setup
  • iOS Setup
  • Web Setup
  • macOS Setup
  • Windows Setup
• Usage Guide
  • 1. Initialize Desktop & Web
  • 2. Login Request
  • 3. iOS App Tracking Transparency & Limited Login
  • 4. Check Login Status & Active Token
  • 5. Fetch User Profile Data
  • 6. Firebase Auth Integration
  • 7. Android Express Login
  • 8. Log Out
• Common Issues & Solutions
• Example App
• License

✨ Features #

• 🚀 Full Cross-Platform: Android, iOS, Web, macOS, and Windows.
• 🔒 Apple Limited Login & ATT: Full support for iOS 14.5+ App Tracking Transparency and Meta Limited Login OIDC tokens.
• 🔥 Firebase Auth Ready: Direct support for classic tokens and Limited Login JWT with raw nonce.
• ⚡ Express Login: Instant re-authentication on Android without prompts.
• 👤 Graph API & Profile Data: Fetch user email, name, avatar, or customized Graph API fields.
• 🛡️ Session Persistence: Secure multi-platform token storage.

📦 Installation #

Add flutter_facebook_auth to your pubspec.yaml:

dependencies:
  flutter_facebook_auth: ^7.3.2

Or install it via terminal:

flutter pub add flutter_facebook_auth

⚙️ Platform Setup #

import 'package:flutter/foundation.dart' show kIsWeb;
import 'package:flutter_facebook_auth/flutter_facebook_auth.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  if (kIsWeb) {
    await FacebookAuth.i.webAndDesktopInitialize(
      appId: "YOUR_FACEBOOK_APP_ID",
      cookie: true,
      xfbml: true,
      version: "v18.0",
    );
  }
  runApp(const MyApp());
}

🚀 Usage Guide #

1. Initialize Desktop & Web #

You can combine initialization for all Desktop & Web targets in main.dart:

import 'package:flutter/foundation.dart' show defaultTargetPlatform, kIsWeb, TargetPlatform;
import 'package:flutter/material.dart';
import 'package:flutter_facebook_auth/flutter_facebook_auth.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  if (kIsWeb ||
      defaultTargetPlatform == TargetPlatform.macOS ||
      defaultTargetPlatform == TargetPlatform.windows) {
    await FacebookAuth.i.webAndDesktopInitialize(
      appId: "YOUR_FACEBOOK_APP_ID",
      cookie: true,
      xfbml: true,
      version: "v18.0",
    );
  }

  runApp(const MyApp());
}

2. Login Request #

Call FacebookAuth.instance.login() to initiate authentication:

final LoginResult result = await FacebookAuth.instance.login(); // default permissions: ['email', 'public_profile']

if (result.status == LoginStatus.success) {
  final AccessToken accessToken = result.accessToken!;
  print("User Token: ${accessToken.tokenString}");
  print("Expires: ${accessToken.expires}");
} else if (result.status == LoginStatus.cancelled) {
  print("Login cancelled by user");
} else {
  print("Login failed: ${result.message}");
}

Request Custom Permissions

final LoginResult result = await FacebookAuth.instance.login(
  permissions: ['public_profile', 'email', 'user_friends'],
);

3. iOS App Tracking Transparency & Limited Login #

On iOS 14.5+, Meta enforces Limited Login unless the user grants App Tracking Transparency (ATT) permission:

• Limited Login (Default without ATT): Returns an OpenID Connect (OIDC) JWT token (LimitedToken). Graph API queries are restricted by Meta for privacy.
• Classic Login (ATT Granted): Returns a standard OAuth access token (ClassicToken) allowing unrestricted Graph API access.

import 'package:flutter/foundation.dart';
import 'package:flutter_facebook_auth/flutter_facebook_auth.dart';
import 'package:permission_handler/permission_handler.dart';

Future<void> loginWithATTSupport() async {
  if (defaultTargetPlatform == TargetPlatform.iOS) {
    // Request tracking authorization for Classic Login
    final status = await Permission.appTrackingTransparency.request();
    print("ATT Status: $status");
  }

  final LoginResult result = await FacebookAuth.instance.login();

  if (result.status == LoginStatus.success) {
    final AccessToken token = result.accessToken!;
    if (token is LimitedToken) {
      print("Limited Login Token (JWT): ${token.tokenString}");
    } else if (token is ClassicToken) {
      print("Classic Login Token: ${token.tokenString}");
    }
  }
}

4. Check Login Status & Active Token #

Check if an active session exists on app launch:

final AccessToken? accessToken = await FacebookAuth.instance.accessToken;

if (accessToken != null) {
  print("User is already logged in with token: ${accessToken.tokenString}");
} else {
  print("No active Facebook session");
}

5. Fetch User Profile Data #

Fetch user details from Facebook Graph API (requires Classic Login or granted permissions):

// Fetch default profile fields (name, email, picture, id)
final Map<String, dynamic> userData = await FacebookAuth.instance.getUserData();

print("User Name: ${userData['name']}");
print("User Email: ${userData['email']}");
print("Profile Picture: ${userData['picture']['data']['url']}");

// Fetch customized Graph API fields
final customData = await FacebookAuth.instance.getUserData(
  fields: "name,email,picture.width(400),birthday,gender",
);

6. Firebase Auth Integration #

Integrate seamlessly with firebase_auth. This snippet properly handles both Classic Login and iOS Limited Login (which requires rawNonce via OAuthProvider):

import 'package:firebase_auth/firebase_auth.dart';
import 'package:flutter_facebook_auth/flutter_facebook_auth.dart';

Future<UserCredential?> signInWithFacebookFirebase() async {
  final LoginResult result = await FacebookAuth.instance.login();

  if (result.status == LoginStatus.success) {
    final AccessToken accessToken = result.accessToken!;

    OAuthCredential credential;
    if (accessToken is LimitedToken) {
      // iOS Limited Login: Authenticate via OAuthProvider with idToken and rawNonce
      credential = OAuthProvider('facebook.com').credential(
        idToken: accessToken.tokenString,
        rawNonce: FacebookAuth.instance.nonce,
      );
    } else {
      // Classic Login (Android, Web, Desktop, iOS with ATT)
      credential = FacebookAuthProvider.credential(accessToken.tokenString);
    }

    return await FirebaseAuth.instance.signInWithCredential(credential);
  }
  return null;
}

7. Android Express Login #

Allows returning users to re-authenticate with a single tap on Android:

final LoginResult result = await FacebookAuth.instance.expressLogin();

if (result.status == LoginStatus.success) {
  print("Express login success: ${result.accessToken!.tokenString}");
}

8. Log Out #

Sign out and clear stored session tokens across all platforms:

await FacebookAuth.instance.logOut();

🛠️ Common Issues & Solutions #

📱 Example App #

A full multi-platform example showcasing login, permissions, user information, and error handling is available in the example directory.

📄 License #

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.