facebook_app_events

pub package License: Apache 2.0 pub likes pub points commercial support

Flutter plugin for Facebook App Events, Meta's app measurement and ad attribution SDK.

An app event is an action that takes place in your app or on your web page such as a person installing your app or completing a purchase. Facebook App Events allows you to track these events to measure ad performance, and build audiences for ad targeting.

Documentation

This README is the quick start. The reasoning behind each setting, platform differences in depth, and what to do when something does not work are in the guides.

Requirements

Minimum
Flutter 3.41.0
iOS deployment target 15.0
Xcode 26.4

On an older Xcode the build fails inside the Facebook SDK with errors that do not mention Xcode: Facebook SDK .swiftinterface build errors.

Setting things up

You must first create an app at Facebook for developers: developers.facebook.com

  1. Get your app id (referred to as [APP_ID] below)
  2. Get your client token (referred to as [CLIENT_TOKEN] below). See "Facebook Doc: Client Tokens" for how to obtain it. It is not the app id, and it goes in a different file on each platform: where the Facebook client token goes.

Configure Android

Read through the "Get Started with App Events (Android)" and "Getting Started with the Facebook SDK for Android" tutorial. In particular, follow Update Your Manifest step by adding the following into android/app/src/main/res/values/strings.xml (or into respective debug or release build flavor)

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="facebook_app_id">[APP_ID]</string>
  <string name="facebook_client_token">[CLIENT_TOKEN]</string>
  <string name="fb_login_protocol_scheme">fb[APP_ID]</string>
  <string name="app_name">[APP_NAME]</string>
</resources>

After that, add that string resource reference to your main AndroidManifest.xml file, directly under the <application> tag.

<application android:label="@string/app_name" ...>
    ...
  <meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id"/>
  <meta-data android:name="com.facebook.sdk.ClientToken" android:value="@string/facebook_client_token"/>
    ...
</application>

Configure iOS

Follow step 5 of Meta's iOS guide: open Info.plist "As Source Code" and add the following just before the final </dict> element. If the file already has a CFBundleURLTypes array, add the <dict> to it instead of adding a second array.

<key>CFBundleURLTypes</key>
<array>
  <dict>
  <key>CFBundleURLSchemes</key>
  <array>
    <string>fb[APP_ID]</string>
  </array>
  </dict>
</array>
<key>FacebookAppID</key>
<string>[APP_ID]</string>
<key>FacebookClientToken</key>
<string>[CLIENT_TOKEN]</string>
<key>FacebookDisplayName</key>
<string>[APP_NAME]</string>

If your app targets an iOS version below 15.0, raise IPHONEOS_DEPLOYMENT_TARGET to 15.0 in ios/Runner.xcodeproj and, if your ios/Podfile has an uncommented platform :ios, ... line, set it to '15.0' as well.

The plugin works with both Swift Package Manager (the Flutter default since 3.44) and CocoaPods, and with both the UIScene and the legacy app-delegate lifecycle, without extra configuration. Which integration your build uses, and how to switch: Swift Package Manager setup for this plugin.

Upgrading with CocoaPods across a Facebook SDK major (for example from plugin 0.31.x): run cd ios && pod update FBSDKCoreKit once. Otherwise the build stops with "changed the constraints of dependency FBSDKCoreKit".

Usage

final facebookAppEvents = FacebookAppEvents();

await facebookAppEvents.logEvent(
  name: 'button_clicked',
  parameters: {'button_id': 'the_clickme_button'},
);

await facebookAppEvents.logPurchase(amount: 9.99, currency: 'USD');

Event parameter values must be String, num or bool. Anything else throws an ArgumentError, because the native SDKs silently drop an event that carries another type. Encode lists and maps as a JSON string first.

The plugin mirrors the App Events API of the native SDKs 1:1. What it leaves out on purpose: what Facebook App Events covers in Flutter. Missing something? Open an issue.

By default the Facebook SDK initializes before your Dart code runs, and initializing contacts Meta. The auto-log flags do not prevent that. To hold the SDK back until the user has consented, turn automatic initialization off:

<!-- ios/Runner/Info.plist -->
<key>FacebookAutoInitEnabled</key>
<false/>
<!-- android/app/src/main/AndroidManifest.xml, under <application> -->
<meta-data android:name="com.facebook.sdk.AutoInitEnabled" android:value="false"/>
// After the user has consented, and on every later launch where consent is
// already stored. The plugin does not remember the decision for you.
await facebookAppEvents.initializeSdk();
await facebookAppEvents.activateApp(); // only if auto-logging is also off

On iOS, call initializeSdk() before anything else. Until then every other call (except setGraphApiVersion) fails with sdkNotInitialized. Android does not enforce that order, so a flow that works on Android can still be wrong for iOS.

The full picture, including what Android still does before consent: holding the Facebook SDK back until consent.

Event metadata (Facebook SDK v19)

Since SDK v19, every event carries the screen title and the last URL that opened your app, query string included. That covers OAuth and magic-link callbacks, and on Android the URL is stored from process start, even when initialization is deferred. It is on by default. To opt out:

<!-- ios/Runner/Info.plist -->
<key>FBSDKAutoLogMetaDataEnabled</key>
<false/>
<!-- android/app/src/main/AndroidManifest.xml, under <application> -->
<meta-data android:name="com.facebook.sdk.AutoLogMetaDataEnabled" android:value="false"/>

To turn it on after consent, call setAutoLogMetaDataEnabled(true) (on iOS after initializeSdk()). What exactly is collected, where it is stored and when it leaves the device: what Facebook SDK v19 attaches to your events.

Handling errors

When a native handler reports an error, the plugin method throws a FacebookAppEventsException. Its errorCode is a FacebookAppEventsErrorCode:

errorCode Wire code Meaning
invalidArgument INVALID_ARGUMENT An argument was missing or malformed. The message says which one.
sdkNotInitialized sdk_not_initialized The native SDK is not initialized. Call initializeSdk() first.
sdkInitializationFailed sdk_initialization_failed initializeSdk() could not start the SDK (Android). The message is the SDK's reason.
missingContext missing_context The plugin has no Android Context.
missingApplication missing_application The plugin has no Android Application.
unknown anything else An error the plugin does not classify, typically thrown by the native SDK. The raw code is in code.
try {
  await facebookAppEvents.initializeSdk();
} on FacebookAppEventsException catch (e) {
  if (e.errorCode == FacebookAppEventsErrorCode.sdkInitializationFailed) {
    debugPrint('Facebook SDK could not start: ${e.message}');
  }
}

Compare errorCode, not code: code is the wire string from the table, not the enum name. New values can be added to the enum in later releases, so keep a wildcard branch when you switch over it.

FacebookAppEventsException extends Flutter's PlatformException, and code still holds the wire code. Code that catches PlatformException and compares e.code strings keeps working. Invalid arguments caught in Dart before the call reaches the native side, such as an unsupported event parameter type, throw ArgumentError as before.

Platform notes

  • Graph API version. The plugin pins the Graph API version to v24.0 on both platforms, because the Android SDK still defaults to a version Meta has removed. Override it with setGraphApiVersion('vXX.0') early in startup if you need a specific one. Background: which Facebook SDK version you actually get.
  • Facebook SDK version. The plugin follows the SDK's major version (currently v19) and does not pin a minor, so two builds can resolve different SDK releases. The same guide explains how to read what you got. Release notes: iOS, Android.
  • clearUserDataForType works on iOS and is a no-op on Android, which has no per-field clear. Use clearUserData() there.
  • setUserData merges on both platforms: only the fields you pass are updated.

Troubleshooting

Symptom Guide
Events do not show up in Events Manager, or counts disagree with yours Events not showing in Events Manager
iOS build fails with "Consecutive statements on a line must be separated by ';'" in a .swiftinterface file Facebook SDK .swiftinterface build errors
A call fails with sdk_not_initialized, or lateinit property appEventsLogger has not been initialized Holding the Facebook SDK back until consent
Events Manager says "Please Upgrade SDK" to version 4.34.0 The "Please Upgrade SDK" warning explained
Not sure where the client token goes, or events fail silently after setup Where the Facebook client token goes
Swift Package Manager will not resolve the Facebook SDK Swift Package Manager setup

All guides: oddbit.id guides for this plugin.

Compatibility alerts

When Meta ships something that breaks Flutter apps, we email what changed and what to do about it. A few times a year, only when something real happened. Not a newsletter.

Subscribe to compatibility alerts

Getting help

Plugin defects are fixed for free, always. If this plugin does not behave the way the native SDK documents, open an issue.

Questions about using or configuring App Events: start with the guides, then the repository discussions or StackOverflow.

Attribution debugging where ad spend is on the line: if installs and purchases do not match up between your app, Events Manager and Ads Manager, that is usually not a plugin bug and not a quick answer. We offer a Meta attribution audit: a one hour diagnostic call at $300, credited in full against the audit fee if you go ahead. If the cause turns out to be a defect in this plugin, we fix it free and you keep the diagnostic.

facebook_app_events is built and maintained by Oddbit, a senior-led studio shipping Flutter, Firebase and analytics integrations. If your team would like an experienced pair of hands on Meta attribution, consent flows or the app around them, talk to us at oddbit.id.

Getting involved

First of all, thank you for even considering to get involved. You are a real super :star: and we :heart: you!

Please read our contribution guideline for more info.

Attribution

facebook_app_events is developed and maintained by Oddbit.