Initialization Options

Heap().startRecording accepts a variety of options meant to customize core and autocapture SDK behavior.

These properties are passed in using the options parameter:

Heap().startRecording("YOUR_APP_ID", {
  'uploadInterval': 60, // Upload every 60 seconds instead of every 15.
  'baseUrl': "https://heap-proxy.example.com", // Send Heap data through a proxy.
});

The options map accepts any value type and values are validated and copied during startRecording. To confirm which values are applied, use LogLevel.debug before startRecording.

Core Configuration Options

clearEventPropertiesOnNewUser (bool)

When true, resetting and identity or changing between two identities will also call clearEventProperties. Defaults to false.

baseUrl (String)

The base URL to upload data to while Heap is running. This follows relative link mechanics must end with a / for paths to resolve correctly.

This parameter primarily exists for testing and proxying purposes, and in the majority of use cases this parameter shouldn't be set.

uploadInterval (double)

The interval at which event batches should be uploaded to the API. Defaults to 15 seconds.

For apps with limited connectivity, it may make sense to increase this interval. Note: Shorter upload intervals may impact device battery life but improve the experience while using the live data feed to create events.

captureVendorId (bool)

Indicates whether or not to track the vendor-specific device ID in events. Defaults to false.

captureAdvertiserId (bool)

Indicates whether or not to track the advertising ID in events. Defaults to false.

Autocapture Configuration Options

disablePageviewAutocapture (bool)

Indicates whether or not to disable pageview autocapture. Defaults to false.

If set, registered autocapture libraries are instructed not to capture pageviews.

disableInteractionAutocapture (bool, iOS only)

Indicates whether or not to disable interaction autocapture. Defaults to false.

If set, registered autocapture libraries are instructed not to capture user interactions.

disableInteractionTextCapture (bool)

Indicates whether or not to disable user interface text capture. Defaults to false.

If set, the core SDK will prevent user interface text from being stored or uploaded and autocapture libraries will be instructed not to capture them.

📘

Because text can be copied over to accessibility labels when accessibility services are enabled, you may also want to set disableInteractionAccessibilityLabelCapture if using this property.

disableInteractionAccessibilityLabelCapture (bool)

Indicates whether or not to disable user interface accessibility label capture. Defaults to false.

If set, the core SDK will prevent user interface accessibility labels from being stored or uploaded and autocapture libraries will be instructed not to capture them.

Setting the Log Level

The Heap Flutter SDKs output logs at industry-standard log levels based on the severity and usefulness of the log message being printed. You can customize how much is logged to the console by setting the log level like so:

import 'package:heap_flutter_bridge/heap_flutter_bridge.dart';

Heap().setLogLevel(HeapLogLevel.debug);

Heap can be customized to print logs at the following log levels:

• HeapLogLevel.none: Heap won't print any log messages.
• HeapLogLevel.error: Heap will only print the most critical log messages, such as when the SDK encounters an error and needs to shut down.
• HeapLogLevel.warn: Heap will print warning messages for recoverable errors, such as when unexpected data types are passed into the SDK or the network is unreachable. Also includes from Error logs.
• HeapLogLevel.info: Heap will print messages that are useful in a production environment, such as when recording starts/stops, when a batch of events is successfully sent, or when a new session has begun.
  This level is recommended for production environments so that developers can see Heap lifecycle messages in their own logging environment. Also includes Error and Warn logs.
• HeapLogLevel.debug: Heap will print messages that the implementing developer may find helpful. Messages may include things such as invalid environment ID value, truncated event names, or attempts to track an event before recording has started.
  This level is recommended for use during implementation to help with debugging normal installation and tracking issues. Also includes Error, Warn, and Info logs.
• HeapLogLevel.trace: Heap will print messages that help the Heap team diagnose SDK issues. Heap support may ask the implementing developers to enable this log level to gain better insight into issues developers may have encountered when implementing the Heap SDK.
  Full event details are also printed at this level.
  This level is recommended when gathering information to send to Heap support personnel. Heap support may also ask that this level be turned on to help debug installation and tracking issues that require extra investigation. Also includes Error, Warn, Info, and Debug logs.

Using GoRouter for Navigation

The Heap Flutter Autocapture SDK supports the GoRouter package for pageview autocapture. To set this up, you'll want to add the HeapAutocaptureNavigatorObserver to the list of observers for GoRouter.

// Using the GoRouter class
...
  final _goRouter = GoRouter(
    observers: [HeapAutocaptureNavigatorObserver()],
    routes: <GoRoute>[...],
...
      
// Using the routingConfig method
...
  final _goRouter = GoRouter.routingConfig(
    observers: [HeapAutocaptureNavigatorObserver()],
    routingConfig: ...,
...

// If using the ShellRoute class for configuring navigation
...
  ShellRoute(
    observers: [HeapAutocaptureNavigatorObserver()],
    routes: <RouteBase>[...],
...

// If using the StatefulShellBranch class for configuring navigation
...   
  StatefulShellBranch(
    observers: [HeapAutocaptureNavigatorObserver()],
    routes: <RouteBase>[...],
...

Requirements + Known Limitations

• StatefulShellRoute.indexedStack is not supported. Using this for navigation will cause each screen to only be tracked the first time it's shown, but will not be tracked on subsequent visits to the same screen.
• Using a CustomTransitionPage is supported, but a key and name should be provided for the page to be tracked correctly as shown below.

...
  pageBuilder: (BuildContext context, GoRouterState state) {
    return CustomTransitionPage<void>(
      key: state.pageKey, // Required for proper tracking
      name: state.matchedLocation, // Required for proper tracking
...