@capacitor-community/facebook-login

Capacitor community plugin for native Facebook Login.

Read the full documentation

Maintenance Status: Actively Maintained

Made with contributors-img.

Demo code is here.

Capacitor community plugin for Facebook Login and Facebook App Events on Android, iOS, and Web. It wraps the native Meta SDKs on Android and iOS and the Facebook JavaScript SDK on Web.

This plugin targets Capacitor 8, iOS 15 or later, and Android API 24 or later. It declares the native Facebook SDK dependencies for both CocoaPods and Swift Package Manager.

npm install @capacitor-community/facebook-login
npx cap sync

Install the plugin major version that matches your Capacitor major version.

Complete the required native and Web setup in Configuration before calling the plugin.

After Installation and Configuration, call login from a user action such as a button click. Request only email for the first check:

import { FacebookLogin } from '@capacitor-community/facebook-login';

async function onLoginClick() {
  const result = await FacebookLogin.login({ permissions: ['email'] });

  if (result.accessToken) {
    console.log('Facebook login succeeded.');
  } else {
    console.log('Facebook login canceled or returned no token.');
  }
}

Expected result: success resolves with an accessToken object (do not log the raw token string). Cancellation on Android and iOS resolves without a token. On Web, a failed login rejects instead.

iOS Limited Login returns an OIDC authentication token (JWT), not a Graph API access token. Profile via Graph requires different token conditions—see Authentication.

Start with Configuration, then use the guide for the feature you are implementing. Method signatures and generated type information remain in the API section below.

• Configuration — Meta app settings and Android, iOS, and Web SDK setup.
• Authentication — login, logout, current tokens, profile fields, reauthorization, and platform differences.
• App Events — custom events, parameters, automatic event logging, and advertiser settings.

An open, non-draft pull request can be published to the npm beta dist-tag after its Validation and Package Candidate workflows pass. A repository owner or maintainer must add a comment whose entire body is:

/beta

The request authorizes only the pull request head SHA that existed when the comment was added. The workflow revalidates the owner or maintainer permission and head SHA immediately before publishing. Any new commit requires CI to pass again and a fresh owner or maintainer /beta comment. Fork pull requests are supported. Pull requests that change a release-gating workflow cannot be beta-published until those workflow changes land on main.

Beta versions use <base>-beta.pr<PR number>.sha<12-character SHA>. The candidate is built in a read-only workflow without npm publishing credentials. The privileged release workflow publishes only the validated immutable package artifact with lifecycle scripts disabled. A notification failure cannot invalidate a successful npm publish.

When a pull request is merged into main, it is automatically published to beta only after the required CI and Package Candidate succeed for that exact merge commit. Direct pushes to main do not publish a candidate.

Only npm run release creates a release tag. Stable vX.Y.Z tags publish to npm latest; revision/prerelease tags publish to next. Neither beta nor next publishing changes the npm latest dist-tag.

• initialize(...)
• login(...)
• logout()
• reauthorize()
• getCurrentAccessToken()
• getProfile(...)
• logEvent(...)
• setAutoLogAppEventsEnabled(...)
• setAdvertiserTrackingEnabled(...)
• setAdvertiserIDCollectionEnabled(...)
• Interfaces
• Type Aliases

initialize(options: Partial<FacebookConfiguration>) => Promise<void>

Initializes the Facebook JavaScript SDK on Web. This is a no-op on Android and iOS, where the SDK is configured natively.

login(options: { permissions: string[]; tracking?: 'limited' | 'enabled'; nonce?: string; }) => Promise<FacebookLoginResponse>

Starts the Facebook login flow with the requested permissions. A cancelled native login resolves without a token.

Returns: Promise<FacebookLoginResponse>

logout() => Promise<void>

Logs out the current Facebook session.

reauthorize() => Promise<FacebookLoginResponse>

Requests renewed data access for the current Facebook session.

Returns: Promise<FacebookLoginResponse>

getCurrentAccessToken() => Promise<FacebookCurrentAccessTokenResponse>

Returns the current token. iOS returns an OIDC authentication token for Limited Login. Native platforms resolve without a token when logged out; Web rejects when there is no connected Facebook session.

Returns: Promise<FacebookCurrentAccessTokenResponse>

getProfile<T extends Record<string, unknown>>(options: { fields: readonly string[]; }) => Promise<T>

Requests the selected fields from the Facebook Graph API /me endpoint.

Returns: Promise<T>

logEvent(options: { eventName: string; parameters?: Record<string, string | number>; }) => Promise<void>

Logs a Facebook App Event with optional string or number parameters.

setAutoLogAppEventsEnabled(options: { enabled: boolean; }) => Promise<void>

Enables or disables automatic App Event logging on native platforms.

setAdvertiserTrackingEnabled(options: { enabled: boolean; }) => Promise<void>

Enables or disables advertiser tracking on iOS.

setAdvertiserIDCollectionEnabled(options: { enabled: boolean; }) => Promise<void>

Enables or disables advertiser ID collection on native platforms.

Make all properties in T optional

{ [P in keyof T]?: T[P]; }

Construct a type with a set of properties K of type T

{ [P in K]: T; }