Flutter SDK Reference
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
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])
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()
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])
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): AMap<String, dynamic>
containing properties to associate with the event.timestamp
(optional): TheDateTime
of when the event occurs. Defaults to the current time. Customer implementations shouldn't assign values for this parameter.sourceInfo
(optional): The nullableHeapSourceInfo
object if this event was generated by an autocapture SDK. Defaults tonull
. Customer implementations shouldn't assign values for this parameter.pageview
(optional): ThePageview
to associate with the tracked event. This is most commonly the case if the event was generated by an autocapture SDK. Defaults tonull
. 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)
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()
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)
Future<void> addUserProperties(Map<String, dynamic> properties)
Description
Add a collection of properties to be associated with the current user.
Parameters
properties
: AMap<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)
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
: AMap<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)
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()
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()
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()
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()
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()
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
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()
static Future<void> register()
Description
Registers the autocapture SDK to start collecting events and pageviews.
Examples
import 'package:heap_flutter_autocapture/heap_flutter_autocapture.dart';
HeapAutocapture.register();
static Future<void> unregister()
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
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(),
],
...
);
}
}
Updated about 4 hours ago