activity_flow 0.0.12

VTEX Activity Flow Flutter SDK

VTEX Activity Flow Mobile RUM for Flutter apps focused in Android and iOS.

Features

This plugin coupled to an app, aims to:

• Track user navigation between app pages and send events.

Usage

1. Import the package inside the main.dart file:

import 'package:activity_flow/activity_flow.dart';

2. Initialize Activity Flow at app startup

Call initActivityFlow inside the build method of your main widget (e.g., MyApp), passing your account name (and any extra params if needed), as in the example:

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    initActivityFlow(accountName: appAccountName);

    return MaterialApp(
      // rest of the code

Screen view event

Create an instance of the Screen View observer class, by setting the account name:

void main() {
  runApp(
    ...
      final afObserver = PageViewObserver();
    ...
  )
}

Automatically tracks your route navigation using the previous AF observer instance created:

MaterialApp(
  // Add the routeObserver to the navigatorObservers list.
  navigatorObservers: [ afObserver ],
  routes: {
    ... //define your named routes
  },
);

Manually Track Navigation Using trackPageView

Since NavigatorObserver currently lacks support for automatically tracking screen view events in Bottom Navigation or Tab Navigation, trackPageView can be effectively utilized for manual event tracking.

// Example for BottomNavigationBar
BottomNavigationBar(
  items: items,
  currentIndex: _selectedIndex,
  onTap: (index) {
    _onItemTapped(index);
    final label = items[index].label ?? 'Tab-$index';
    trackPageView(label);
  },
)

Touch event

Automatically tracks touch gesture using the detector as a Provider in your app, together with the page view observer to get routes names too.

    return TouchDetector( //AF config
      accountName: {accountName},
      child: MaterialApp(
        ...
        navigatorObservers: [afObserver], //AF config
      ),
    );

Ad Events

To start collecting ad events (impression, view, and click), use the extension addAdsListener at the end of any widget that is considered an ad widget. This extension receives a map of data params related to the ad. The adId params is mandatory.

return AnyAdWidget(

  // Widget code ...

).addAdsListener({
  "adId": "ad-123",
  "foo": "bar",
  "abc": "xyz",
});

Test Environment Setup

Why enable the test environment variable?

By enabling the test environment variable, you disable Activity Flow to run your app tests without interference. This is necessary because the plugin and its dependencies have some timers defined that can be unpredictable in test environments.

Enabling the test environment variable will:

• Prevent side effects or asynchronous behaviors that could interfere with test assertions.
• Ensure your analytics and event tracking logic is test-friendly and deterministic.

How to enable the test environment variable

Add the following Dart define when running your tests:

flutter test --dart-define=ACTIVITY_FLOW_TEST_ENV=true

FAQ

• Why do my tests pass with flutter test --dart-define=ACTIVITY_FLOW_TEST_ENV=true, but fail when using the test button in VS Code? VS Code does not automatically add the ACTIVITY_FLOW_TEST_ENV parameter when running tests with the test button. To fix this, add --dart-define=ACTIVITY_FLOW_TEST_ENV=true to your VS Code settings. Search for dart.flutterTestAdditionalArgs in the settings and add the value --dart-define=ACTIVITY_FLOW_TEST_ENV=true. Alternatively, edit your settings.json file and include:

  "dart.flutterTestAdditionalArgs": ["--dart-define=ACTIVITY_FLOW_TEST_ENV=true"]
  

• Where should I call initActivityFlow? Always call initActivityFlow inside the build method of your main widget (e.g., MyApp). This ensures Activity Flow is disabled every time you use pumpWidget(const MyApp()); otherwise, it may interfere with the app tests.