Flutter SDK API

The Flutter SDK provides a comprehensive API that lets you track and send your event data to any destination.

Identify

The identify call lets you identify a visiting user and associate them to their actions. It also lets you record the traits about them like their name, email address, etc.

A sample identify event is shown below:

RudderTraits traits = RudderTraits();
traits.putBirthdayDate(new DateTime.now());
traits.putEmail("alex@example.com");
traits.putFirstName("Alex");
traits.putLastName("Keener");
traits.putGender("Male");
traits.putPhone("5555555555");

Address address = Address();
address.putCity("City");
address.putCountry("USA");
traits.putAddress(address);

traits.put("boolean", true);
traits.put("integer", 50);
traits.put("float", 120.4);
traits.put("long", 1234);
traits.put("string", "hello");
traits.put("date", new DateTime.now().millisecondsSinceEpoch);

rudderClient.identify("1hKOmRA4GRlm", traits: traits, options: null);

The identify method has the following signature:

Once a user is identified, the SDK persists all user information and passes it to the successive track or screen calls. To reset the user identification, you can use the reset method.

For unidentified users, RudderStack captures the deviceId and uses that as the anonymousId for identification. This way, you can track the users across the application installation. To attach more information to the user, you can use the identify method.

deviceId for Android and iOS

• On the Android devices, the deviceId is assigned during the first boot. It remains consistent across the applications and installs. This can be changed only after factory resetting the device.
• According to the Apple documentation, if the iOS device has multiple apps from the same vendor, all apps are assigned the same deviceId. If all applications from a vendor are uninstalled and then reinstalled, then they are assigned a new deviceId.

Obtaining user traits

The following snippet shows how you can obtain the user traits after making an identify call:

Map context = await rudderClient.getRudderContext();
print(context["traits"]);

For the web apps, the getRudderContext API returns the user’s traits and anonymousId.

Setting a custom ID

You can pass a custom ID along with the standard userId in your identify calls. RudderStack adds this value under context.externalId.

RudderStack supports passing externalId only in the identify events. You must not pass this ID in other API calls like track, page, etc.

The following code snippet shows how to add externalId to your identify event:

RudderOption option = RudderOption();
option.putExternalId("externalId", "some_external_id_1");
rudderClient.identify("1hKOmRA4GRlm", options: option);

Track

The track call lets you track the user actions along with any properties associated with them.

A sample track event is shown below:

RudderProperty property = RudderProperty();
property.put("test_key_1", "test_key_1");
RudderProperty childProperty = RudderProperty();
childProperty.put("test_child_key_1", "test_child_value_1");
property.put("test_key_2",childProperty);
rudderClient.track("Test Event", properties: property);

The track method has the following signature:

Lifecycle events

The Flutter SDK automatically tracks the following optional application lifecycle events:

• Application Installed
• Application Updated
• Application Opened
• Application Backgrounded

You can disable these events by calling withTrackLifeCycleEvents(false) in the RudderConfigBuilder object while initializing the SDK. However, it is highly recommended to keep them enabled.

Screen

The screen call is the mobile equivalent of the page call. It lets you record the screen views on your mobile app along with other relevant information about the screen.

For the web apps, the SDK internally calls the page API with the provided parameters.

A sample screen event is shown below:

RudderProperty screenProperty = RudderProperty();
  screenProperty.put("browser", "Chrome");
  screenProperty.put("device", "Macbook Pro");
  rudderClient.screen("Walmart Cart",
      category: "home",
      properties: screenProperty,
      options: null);

The screen method has the following signature:

Automatic screen recording

The recordScreenViews parameter records the screen views of the native Android activities or the iOS view controllers only and not of the Flutter screen views.

To track the screen views of your Flutter app screens, follow these steps:

1. Define the routes with their names to the Material App constructor of the entry widget.
2. Register an instance of the custom navigation observer to the Material App constructor of the entry widget.

The following snippet includes the code for the above two steps:

import 'package:flutter/material.dart';
import 'home_screen.dart';
import 'screen2.dart';
import 'screen3.dart';
import 'my_route_observer.dart';

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
// Step 2. Registering an instance of our custom navigation observer.
      navigatorObservers: [
        MyRouteObserver(),
      ],
      home: const HomeScreen(),
// Step 1. Defining the named routes
      routes: {
        'screen2': (context) => const Screen2(),
        'screen3': (context) => const Screen3(),
      },
    );
  }
}

Future<void> main() async {
  runApp(const MyApp());
}

3. Finally, add the below code for the custom navigation observer used above:

import 'package:flutter/material.dart';
import 'package:rudder_sdk_flutter/RudderController.dart';

class MyRouteObserver extends RouteObserver<PageRoute<dynamic>> {
  @override
  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) {
    super.didPush(route, previousRoute);
    if (route is PageRoute && route.settings.name != null) {
      RudderController.instance.screen(route.settings.name!);
    }
  }

  @override
  void didPop(Route<dynamic> route, Route<dynamic>? previousRoute) {
    super.didPop(route, previousRoute);
    if (previousRoute is PageRoute && route is PageRoute) {
      RudderController.instance.screen(previousRoute.settings.name!);
    }
  }
}

Group

The group call lets you link an identified user with a group, such as a company, organization, or an account. It also lets you record any custom traits or properties associated with that group.

RudderStack does not persist the group traits across the sessions.

A sample group event is shown below:

RudderTraits groupTraits = RudderTraits();
groupTraits.put("foo", "bar");
groupTraits.put("foo1", "bar1");
rudderClient.group("sample_group_id",
    groupTraits: groupTraits, options: null);

The group method has the following signature:

Alias

The alias call lets you merge different identities of a known user. It is an advanced method that lets you change the tracked user’s ID explicitly. You can use alias for managing the user’s identity in some of the downstream destinations.

RudderStack supports sending alias events only to select downstream destinations. Refer to the destination-specific documentation for more details.

When you make an alias call, RudderStack replaces the old user ID with the new user ID and persists this identification across the sessions.

A sample alias call is shown below:

rudderClient.alias("new_user_id", options: null);

The alias method has the following signature:

Reset

You can use the reset method to clear the persisted traits for the identify call. This is required for scenarios where the user logs out of a session.

rudderClient.reset();

Questions? Contact us by email or on Slack