In this guide, you'll learn how to install and configure the VTEX Activity Flow SDK in Flutter apps for Android and iOS. By following these steps, you'll be able to track user navigation, handle deep links, and collect ad events and customer interaction events (clicks, views, and impressions) in your app.

The Activity Flow SDK captures user navigation and sends events from your mobile app. To install the package, run the following command in your project directory:

This installs the SDK and updates your pubspec.yaml file with the activity_flow dependency.

In your app's main file, import the Activity Flow package as follows:

Set the account name to create an instance of the main package class:

To automatically track user navigation between app pages, add the PageViewObserver to the navigatorObservers list in your app:

This setup enables automatic screen view tracking for standard route navigation.

For navigation widgets such as BottomNavigationBar or TabBar that don't trigger route changes, use the screenViewChange function to manually track screen views.

For example, using the onTap callback within a BottomNavigationBar widget allows for capturing a new route each time the user taps on a different tab:

The Activity Flow SDK automatically captures deep link query parameters and includes them in page view events when your app is configured for deep linking. Configure each platform as follows.

Android

Add intent filters to AndroidManifest.xml for each route that can be accessed via deep link:

The main difference between intent filters for different routes is the android:pathPrefix attribute, which specifies the app route.

iOS

Configure both Info.plist and the app delegate to handle deep links.

1. Register a custom URL scheme in Info.plist:

   ios/{YourApp}/Info.plist

   
   

   _11

   <key>CFBundleURLTypes</key>

   _11

   <array>

   _11

   <dict>

   _11

   <key>CFBundleURLSchemes</key>

   _11

   <array>

   _11

   <string>{YOUR_BUNDLE_URL_SCHEME}</string>

   _11

   </array>

   _11

   <key>CFBundleURLName</key>

   _11

   <string>{YOUR_BUNDLE_URL_NAME}</string>

   _11

   </dict>

   _11

   </array>

   
   

2. Handle incoming URLs in AppDelegate.swift (or AppDelegate.mm) for both cold and warm starts:

   
   

   _37

   import Flutter

   _37

   import UIKit

   _37

   import activity_flow

   _37

   _37

   @main

   _37

   @objc class AppDelegate: FlutterAppDelegate {

   _37

   override func application(

   _37

   _ application: UIApplication,

   _37

   didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?

   _37

   ) -> Bool {

   _37

   GeneratedPluginRegistrant.register(with: self)

   _37

   _37

   // Capture initial URL if app was launched with a deep link (cold start)

   _37

   if let initialURL = launchOptions?[UIApplication.LaunchOptionsKey.url] as? URL {

   _37

   DeepLinkManager.shared.handle(url: initialURL)

   _37

   }

   _37

   _37

   return super.application(application, didFinishLaunchingWithOptions: launchOptions)

   _37

   }

   _37

   _37

   // Handles incoming URLs from Custom URL Schemes (e.g., myapp://path)

   _37

   override func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

   _37

   DeepLinkManager.shared.handle(url: url)

   _37

   return super.application(app, open: url, options: options)

   _37

   }

   _37

   _37

   // Handles incoming URLs from Universal Links

   _37

   override func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {

   _37

   // Check if the activity is a web browsing activity (Universal Link)

   _37

   if userActivity.activityType == NSUserActivityTypeBrowsingWeb {

   _37

   if let url = userActivity.webpageURL {

   _37

   DeepLinkManager.shared.handle(url: url)

   _37

   }

   _37

   }

   _37

   return super.application(application, continue: userActivity, restorationHandler: restorationHandler)

   _37

   }

   _37

   }

   
   

3. Configure SceneDelegate

If your project uses a SceneDelegate, also forward deep links there:

Ads tracking is available only for accounts using VTEX Ads. If you're interested in this feature, open a ticket with VTEX Support.

When you apply the listener to a widget, the SDK automatically tracks three events:

• Impressions: When the widget is first built and rendered.
• Views: When at least 50% of the widget is visible on screen for at least 1 continuous second.
• Clicks: When the user taps the widget.

To start tracking your ad events, follow these steps:

1. Call the addAdsListener method

To enable tracking, call the addAdsListener extension method on any Flutter widget that represents an ad:

• yourAdWidget: The ad widget you want to monitor.
• adMetadata: A map containing specific details about the ad, which will be sent to your analytics service upon a click.

The following example initializes the Activity Flow to track page views automatically and demonstrates ad tracking:

This Flutter screen is constructed as a StatelessWidget that lists products and displays an ad banner. The banner's Container is wrapped with Activity Flow's addAdsListener, which attaches an ad-event listener and sends the provided metadata map with each event.

This instrumentation enables the automatic tracking of impressions, viewability, and clicks, allowing for comprehensive analytics tied to adId, creativeId, position, and campaignName.

Beyond page views and ad events, Activity Flow provides individual extension methods for tracking click, view, and impression events on any widget. These methods can be used independently or combined on the same widget.

All methods require elementSource, a string that identifies the tracked element. This field is sent as a top-level property in the event payload, separate from the other attributes.

Click event

Use addClickListener on any widget to capture tap interactions. A click event is fired when the user taps (not drags) on the element. Pass any custom attributes you want to associate with the interaction.

You must include the elementSource key in the method's metadata map.

View event

Use addViewListener to fire a view event when the widget has been at least 50% visible on screen for at least 1 second (IAB standard). The event fires once per app session — it does not re-fire if the widget scrolls off-screen and back, or if the user navigates away and returns.

You must include the elementSource key in the method's metadata map.

Impression events

Use the addImpressionListener method to trigger an impression event immediately upon the widget being built and rendered within the application's widget tree.

You must include the elementSource key in the method's metadata map.

Combining multiple listeners

Combine the listeners on a single widget to track the full interaction funnel: whether the element was rendered (impression), actually seen by the user (view), and clicked (click).

The example below chains the impression and view listeners on a single widget to capture both event types simultaneously:

To ensure your Flutter test runs work correctly when the Activity Flow is installed, run tests with a test environment flag using a --dart-define flag.

The --dart-define flag allows you to pass compile-time key=value pairs into your Flutter app as Dart environment declarations. To do so, follow the steps below:

1. In your terminal, run flutter test --dart-define=ACTIVITY_FLOW_TEST_ENV=true.

2. In a code editor, open your project.

3. In the code editor settings, search for dart.flutterTestAdditionalArgs.

4. Add to it the value --dart-define=ACTIVITY_FLOW_TEST_ENV=true.

   Alternatively, open the settings.json file of your project and add "dart.flutterTestAdditionalArgs": ["--dart-define=ACTIVITY_FLOW_TEST_ENV=true"].

Below is an example that contains an app with some pages and navigation through them:

The example demonstrates how to integrate Activity Flow into a Flutter app by importing the necessary package, initializing it with initActivityFlow(accountName: appAccountName), and constructing a MaterialApp with named routes and a PageViewObserver to automatically capture page-view events.

It outlines a MyHomePage that incorporates an AdBanner that uses addAdsListener to pass ad metadata, such as product name, price, and ID. Additionally, it features navigation buttons sourced from a routes list.

The reusable ButtonTemplate facilitates navigation through Navigator.pushNamed, showcasing a standard configuration for automatic screen tracking, as well as ad impression and click tracking, in a Flutter application.