DEV Community

Michael Otieno Olang
Michael Otieno Olang

Posted on

Meta App Events in Flutter for iOS: Setup, Tracking, and Attribution

I had already added Meta App Events to the Android side of a Flutter booking app. Getting the same booking funnel onto iOS required more than copying the Dart calls: iOS needs its own native SDK, app delegate setup, URL handling, and privacy configuration.

The app uses a Flutter MethodChannel for both mobile platforms, but the iOS side maps those calls to Meta's native Swift SDK.

First, line up the IDs

ID What it identifies Where it belongs
Meta App ID The mobile app registered with Meta for Developers iOS SDK configuration and the app selected for an app campaign
Bundle ID The iOS app identifier Xcode target and the iOS platform settings in Meta for Developers
Ad Account ID The business account that runs campaigns Meta Business and Ads Manager; it does not go in the iOS SDK
Pixel ID A website data source Website Pixel or web Conversions API setup; it does not replace the mobile App ID

For this TRAVLER build, the bundle identifier is com.syn.ma3app, and the Meta App ID is 1320645970220890. The SDK App ID and the app selected in Ads Manager need to refer to the same Meta app. The ad account and website Pixel have separate jobs.

The Client Token must come from that same Meta app as the App ID. It is included in the built app, so treat it as public app configuration rather than a server secret. Do not commit its value or paste it into a public post.

What I needed before coding

  • A Meta for Developers app with its iOS platform configured.
  • The exact iOS Bundle ID used by the Runner target.
  • The matching Meta App ID and Client Token.
  • CocoaPods installed, since this Flutter project uses CocoaPods for its iOS plugins and Meta SDK.
  • An iPhone simulator or device and access to the app's Events Manager data source.

Facebook Login is not required for App Events. This integration records app sessions and booking funnel activity; it does not add a Facebook sign-in screen.

Step 1: Register the iOS app in Meta for Developers

In Meta for Developers → My Apps, open the app that will own these events and add its iOS platform. Enter the Bundle ID from the Runner target, not a display name or the Android package name. For this app, that value is com.syn.ma3app.

Keep the App ID and Client Token from the same Meta app. Later, in Ads Manager, select that same app for the campaign. A correct SDK setup can send events to one Meta app while a campaign points at another; those events will not become conversions for the other app automatically.

Step 2: Install Meta's iOS Core SDK with CocoaPods

App Events are part of Meta's iOS CoreKit, so I added that pod to the Runner target in ios/Podfile:

target 'Runner' do
  use_frameworks! :linkage => :static
  use_modular_headers!

  google_utilities_pods
  pod 'FBSDKCoreKit', '18.1.1'
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end
Enter fullscreen mode Exit fullscreen mode

The project pins FBSDKCoreKit to 18.1.1; its podspec supplies the CoreKit XCFramework and its required Meta dependencies. Check the versioned Meta podspec and current releases before using this exact version in a new project. After changing the Podfile, run pod install from ios/ and open Runner.xcworkspace in Xcode.

For an event-only integration, CoreKit is the SDK piece used here. Add LoginKit or ShareKit only if the app actually needs those features.

This project has Swift Package Manager disabled in Flutter's iOS config and resolves its iOS plugins through CocoaPods. Flutter may still print a notice listing plugins without Swift Package Manager support. That notice is separate from the CocoaPods build; it was not the cause of the simulator failure I hit.

Step 3: Configure Info.plist and the Client Token

The Runner Info.plist contains the Meta App ID and display name, and disables automatic app-event logging because activation is called manually from the app delegate:

<key>FacebookAppID</key>
<string>YOUR_META_APP_ID</string>
<key>FacebookDisplayName</key>
<string>TRAVLER</string>
<key>FacebookAutoLogAppEventsEnabled</key>
<false/>
<key>FacebookClientToken</key>
<string></string>
Enter fullscreen mode Exit fullscreen mode

The real Client Token is stored in the root .env file:

META_CLIENT_TOKEN=YOUR_CLIENT_TOKEN_FROM_THE_SAME_META_APP
Enter fullscreen mode Exit fullscreen mode

An Xcode build phase runs ios/scripts/configure_meta_client_token.py and copies that value into the built app's Info.plist. The source plist stays free of the token value. This prevents an accidental source-control commit, but a value packaged inside a mobile app can still be inspected after installation; it is not a place for a server credential.

The app also registers the Meta URL scheme and query schemes:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>fbYOUR_META_APP_ID</string>
    </array>
  </dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>fbapi</string>
  <string>fb-messenger-api</string>
  <string>fbauth2</string>
  <string>fbshareextension</string>
</array>
Enter fullscreen mode Exit fullscreen mode

The URL scheme lets iOS route SDK callback URLs back to the app. The query schemes are useful when a feature can switch to a Meta app, such as Login or Share; they are not a replacement for configuring App Events.

Step 4: Initialize the SDK and handle the iOS lifecycle

In AppDelegate.swift, I set the Graph API version before initializing Meta's application delegate:

Settings.shared.graphAPIVersion = "v24.0"
_ = ApplicationDelegate.shared.application(
  application,
  didFinishLaunchingWithOptions: launchOptions
)
Enter fullscreen mode Exit fullscreen mode

This is a project setting, so recheck it when upgrading the SDK or changing the Graph API version used by the app.

Because FacebookAutoLogAppEventsEnabled is false, I activate App Events from the app lifecycle callback:

override func applicationDidBecomeActive(_ application: UIApplication) {
  AppEvents.shared.activateApp()
  super.applicationDidBecomeActive(application)
}
Enter fullscreen mode Exit fullscreen mode

Meta's SDK documentation says activateApp() belongs in this callback when automatic app-event logging is disabled. It records app activation when appropriate and handles the SDK's first-launch install signal; it does not emit a new activation event on every foreground transition. See the v18.1.1 App Events API.

This app uses SceneDelegate, too. Its URL handler gives incoming URLs to Meta's ApplicationDelegate first, then forwards unhandled URLs to app_links. Keep the app's existing deep-link handling when adding SDK callbacks, or an unrelated sign-in or web link may stop working.

Step 5: Keep App Tracking Transparency separate from event logging

The app declares NSUserTrackingUsageDescription in Info.plist, and AppAnalytics.initialize() requests Permission.appTrackingTransparency on iOS. Apple's App Tracking Transparency framework controls permission for tracking a person or device across other companies' apps and websites. It is distinct from whether the Flutter bridge can invoke the native App Events SDK. Read Apple's App Tracking Transparency documentation and make sure the prompt's description matches the app's actual use.

Do not interpret a green local SDK log as user permission or ad attribution. The OS permission choice and Meta's attribution/reporting rules affect what can be measured for campaigns.

Step 6: Define events at real booking milestones

The Dart event calls are shared by Android and iOS. The native bridge translates them into Meta event names at the point where each action actually happens:

Event Type When it fires
fb_mobile_activate_app Standard lifecycle event AppEvents.shared.activateApp() runs from the iOS app delegate
travler_home_view Custom The booking home screen is reported as visible
travler_search_screen_view Custom The bus schedules/results screen opens
fb_mobile_search Standard Search A route search is submitted, with fb_content_type=bus_route
travler_search_results_view Custom Results finish loading, with result_count (including zero)
travler_search_results_error Custom The results request fails
fb_mobile_initiated_checkout Standard Initiated Checkout The payment screen opens with a valid positive amount and currency
fb_mobile_purchase Standard Purchase A paid booking succeeds, with amount and currency

Purchase belongs after payment confirmation, not when someone taps Pay or receives a pending payment prompt. On this installation, Dart keeps a local list of booking references to avoid sending the same purchase twice from duplicate success callbacks.

The current native bridge also includes booking_id as an event parameter. A booking reference can be linkable to a person in your own systems, so review whether Meta needs that value. Local purchase deduplication can use the booking reference without necessarily sending it as an event parameter.

Step 7: Bridge Dart to Swift with a MethodChannel

The channel name and method names must match on both sides. The existing Dart service invokes com.ma3app/meta_app_events:

static const _channel = MethodChannel('com.ma3app/meta_app_events');

await _channel.invokeMethod<void>('logSearchSubmitted');

await _channel.invokeMethod<void>('logPurchase', {
  'bookingId': bookingId,
  'amount': amount,
  'currency': currency,
});
Enter fullscreen mode Exit fullscreen mode

The Swift plugin is registered with Flutter's implicit engine in AppDelegate.swift. Its method handler converts parameter keys to AppEvents.ParameterName and calls the SDK:

AppEvents.shared.logEvent(
  AppEvents.Name("fb_mobile_search"),
  parameters: [
    AppEvents.ParameterName("fb_content_type"): "bus_route",
  ]
)

AppEvents.shared.logPurchase(
  amount: amount,
  currency: currency,
  parameters: typedParameters
)
Enter fullscreen mode Exit fullscreen mode

The bridge rejects negative result counts, non-positive or non-finite purchase amounts, and currencies that are not three uppercase ISO letters. Meta's SDK accepts string and numeric parameter values; keep the event names and parameter set small and stable.

Step 8: Verify locally, then verify in Meta

The Flutter service now prints a debug line before invoking the native method and a green success line after the method channel returns. A run on the iPhone 18 Pro simulator showed:

[DEBUG] 📊 META APP EVENT: Sending travler_home_view to native SDK.
[SUCCESS] ✅ META APP EVENT: Native SDK accepted travler_home_view.
Enter fullscreen mode Exit fullscreen mode

That confirms the call reached the iOS native handler and the SDK method returned. It does not prove the event reached Meta's servers or was attributed to an ad. Meta queues and flushes events asynchronously; test receipt in Events Manager → Test Events for the app data source with the same App ID.

Then exercise each booking step and check for Search, Initiated Checkout, and Purchase. Use a confirmed test payment for Purchase. For campaign attribution, select the same Meta app in Ads Manager and test with an eligible ad interaction; debug or organic events can appear in Events Manager without becoming ad-attributed conversions.

ATT and campaign attribution

On iOS, a successful event in Events Manager and an attributed campaign conversion are different checks. The App Tracking Transparency prompt concerns cross-company tracking and access to the advertising identifier. Apple requires ATT when an app collects and shares data for tracking across apps and websites. If the user declines, the app can still call this event bridge, but identifier-based measurement and campaign attribution may be limited. Follow Apple's privacy requirements and Meta's current guidance for the campaign type you plan to run.

Troubleshooting notes from this integration

  • Flutter lists plugins that do not support Swift Package Manager: This project has Swift Package Manager disabled and uses CocoaPods. The message is a compatibility warning; the CocoaPods build can still run.
  • The iPhone 18 Pro simulator says no Xcode build settings were found: In my case, old manually linked Meta frameworks and an arm64 simulator exclusion were the real problem. Replacing the hand-copied frameworks with the CocoaPods XCFramework and removing the simulator architecture exclusion let the build compile and launch.
  • The event appears in Flutter logs but not in Events Manager: The Flutter success log only confirms the local method call. Check the built app's App ID and Client Token, network access, the app data source, and Events Manager's Test Events view.
  • Activate App appears but Purchase does not: Confirm that the paid booking callback calls logPurchase, the amount and currency pass validation, and the booking has not already been deduplicated on that installation.
  • Events appear, but Ads Manager shows no conversions: Verify that the campaign selected the same iOS app/App ID, the user interacted with an eligible ad, and the event is available for that campaign's optimization settings. Event collection alone does not prove ad attribution.

The useful distinction is: the SDK receives the event call, Meta receives the event, and Ads Manager attributes that event to an ad are three separate outcomes. I check each one separately.

References

Top comments (0)