This is a reference guide for all Flutter SDK requirements, known limitations, API reference, and performance impact information.

All Flutter SDK artifacts are distributed through pub.dev.

For notes on the latest SDK versions, see our Flutter changelog.

Heap Flutter Bridge Reference

Requirements + Known Limitations

• Requires iOS 13 or above, Android API 16 or above, and Flutter 3.16.9 or above.

Installation

The Heap Flutter Bridge SDK can be installed using the flutter command line tool.

flutter pub add heap_flutter_bridge

API Reference

Heap

• Import: import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

The public-facing API for the Heap Flutter Bridge SDK.

Future<void> startRecording(String environmentId, [Map<String, dynamic>? options])

Description
Initializes the Heap SDK and enables Heap to start recording data.

If Heap is already recording and the options have changed, Heap will restart tracking with the new options, creating a new session. Otherwise, calling this method multiple times with the same value has no effect.

Parameters

• environmentId: The environment ID to which data should be attributed.
• options: (optional) A map of configuration options for use starting the SDK. See Flutter Custom Configuration for available options.

Examples

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

Heap().startRecording('YOUR_APP_ID');

Heap().startRecording('YOUR_APP_ID', {
  'uploadInterval': 60,
});

Future<void> stopRecording()

Description
Shuts down the Heap SDK and prevents any further data collection.

Examples

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

Heap().stopRecording();

Future<void> track(String event, [Map<String, dynamic>? properties, DateTime? timestamp, HeapSourceInfo? sourceInfo, Pageview? pageview])

Description
Creates an event message to be tracked and sent to the Heap API.

Parameters

• event: The string name of the event.
• properties (optional): A Map<String, dynamic> containing properties to associate with the event.
• timestamp (optional): The DateTime of when the event occurs. Defaults to the current time. Customer implementations shouldn't assign values for this parameter.
• sourceInfo (optional): The nullable HeapSourceInfo object if this event was generated by an autocapture SDK. Defaults to null. Customer implementations shouldn't assign values for this parameter.
• pageview (optional): The Pageview to associate with the tracked event. This is most commonly the case if the event was generated by an autocapture SDK. Defaults to null. Customer implementations shouldn't assign values for this parameter.

Examples

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

// Without properties
Heap().track("Added to cart");

// With properties
Heap().track("Added to cart", {
  'product_category': product.category,
});

Future<void> identify(String identity)

Description
Assigns an identity to be associated with the current user ID, used for combining users across multiple implementations.

If the identity is already set and it is different from the past identity, this will reset the user ID and session while setting the identity.

Parameters

• identity: The string value representing the identity to associate with events. This should uniquely identify the person using the app, and never be a hard-coded value.

Examples
In this example, the app has a method userAuthenticated which is called when the user logs into the app.

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

void userAuthenticated(AppUser user) {
	Heap().identify(user.customerId)
}

Future<void> resetIdentity()

Description
Resets the state for a user that was previously identified with identify, creating a new user and session while clearing event properties. If the user wasn't previously identified, this method has no effect.

Examples
In this example, the app has a method userLoggedOut which is called when the user logs out of the app.

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

void userLoggedOut() {
  ...
  Heap().resetIdentity();
}

Future<void> addUserProperties(Map<String, dynamic> properties)

Description
Add a collection of properties to be associated with the current user.

Parameters

• properties: A Map<String, dynamic> containing properties to associate with the user.

Examples
In this example, the app has a method userAuthenticated which is called when the user logs into the app.

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

void userAuthenticated(AppUser user) {
  ...
  Heap().addUserProperties({
    'membership_tier': user.membershipTier,
    'team_name': user.team.name,
  });
}

Future<void> addEventProperties(Map<String, dynamic> properties)

Description
Add a collection of properties to be associated with all future events from the current user.

Parameters

• properties: A Map<String, dynamic> containing properties to associate with future events.

Examples
In this example, the app has a method contentLoaded which is called when a view loads data and we want to group future events based on the hero banner that was displayed.

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

void contentLoaded(content: HomeScreenContent) {
  ...
  String? heroName = content.hero?.name;
  if (heroName != null) {
    Heap().addEventProperties({
      'home_screen_hero': heroName,
    });
  }
}

Future<void> removeEventProperty(String name)

Description
Removes a single event-wide property that was previously added with addEventProperties.

Parameters

• name: The name of the property to remove.

Examples
In this example, we want to track a property on all events while a component is on screen:

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

void updateChatProperties(bool chatPopupVisible) {
  if (chatPopupVisible) {
    Heap().addEventProperties({
      'chat_popup_is_visible': true,
    });
  } else {
    Heap().removeEventProperty("chat_popup_is_visible");
  }
}

Future<void> clearEventProperties()

Description
Removes all event-wide properties that were previously added with addEventProperties.

Examples
In this example, the app has a method checkoutComplete which is called when the user finishes a purchase.

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

void checkoutComplete() {
  ...
  Heap().clearEventProperties();
}

Future<String?> getUserId()

Description
Returns a Future that resolves to the current user ID if Heap is recording, otherwise null.

Return Value
The current Heap-generated user ID used for tracking events, or null if Heap is not recording.

Examples

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

String? heapUserId = await Heap().getUserId();

Future<String?> getIdentity()

Description
Returns a Future that resolves to the currently set identity if Heap is recording and the user has been identified, otherwise null.

Return Value
The value that was provided to identify for the current user, or null if Heap is not recording or identify has not been called.

Examples

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

String? heapIdentity = await Heap().getIdentity();

Future<String?> getSessionId()

Description
Returns a Future that resolves to the current session ID if Heap is recording and the session has started and is not expired, otherwise null.

This method is useful for reading the current state for purposes such as logging. If you are using the session ID for server-side events, it's recommended that you use fetchSessionId(), which will create a new session if needed.

Return Value
The current Heap-generated session ID, or null if Heap is not recording, the session has not started, or the current session has expired.

Examples

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

String? heapSessionId = await Heap().getSessionId();

Future<String?> fetchSessionId()

Description
Returns a Future resolving to the current session ID if Heap is recording, otherwise null.

If the previous session has expired, this will start a new session.

Return Value
The current Heap-generated session ID, or null if Heap is not recording.

Examples

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

String? heapSessionId = await Heap().getSessionId();

Heap Flutter Autocapture Reference

Requirements + Known Limitations

• Requires iOS 13 or above, Android API 16 or above, and Flutter 3.16.9 or above.
• Requires Heap Flutter Bridge 0.3.0 or above.
• Autocapture of pageviews is not currently supported if using the AutoRoute package for navigation.

Installation

The Heap Flutter Autocapture SDK can be installed using the flutter command line tool. You must install the Heap Flutter Bridge SDK as well.

flutter pub add heap_flutter_bridge
flutter pub add heap_flutter_autocapture

API Reference

HeapAutocapture

• Import: import 'package:heap_flutter_autocapture/heap_flutter_autocapture.dart';

The public-facing API for the Heap Flutter Autocapture SDK.

static Future<void> register()

Description
Registers the autocapture SDK to start collecting events and pageviews. This should be called as soon as possible when your app starts, preferably in your main method as the first thing that happens when the app starts. Additionally, no data will be collected after registration until startRecording is called.

Examples

import 'package:heap_flutter_autocapture/heap_flutter_autocapture.dart';

HeapAutocapture.register();

static Future<void> unregister()

Description

Unregisters the autocapture SDK, causing the SDK to stop collecting interaction events and pageviews.

Examples

import 'package:heap_flutter_autocapture/heap_flutter_autocapture.dart';

HeapAutocapture.unregister();

HeapAutocaptureNavigatorObserver

• Import: import 'package:heap_flutter_autocapture/heap_flutter_autocapture.dart';

A navigation observer used by the SDK to automatically capture pageviews.

Examples

import 'package:heap_flutter_autocapture/heap_flutter_autocapture.dart';

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      ...
      navigatorObservers: [
        HeapAutocaptureNavigatorObserver(),
      ],
      ...
    );
  }
}