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 dictionary 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

startSessionImmediately (boolean)

Indicates whether or not to start the session immediately when startRecording is called. Defaults to false.

The default behavior is to wait for the first event (either from track or autocapture) before starting the session to prevent sessions from starting during background app launches.

clearEventPropertiesOnNewUser (boolean)

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 (number)

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 (boolean)

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

captureAdvertiserId (boolean)

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

Autocapture Configuration Options

disablePageviewAutocapture (boolean, iOS only)

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

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

disableInteractionAutocapture (boolean, 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 (boolean)

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 (boolean)

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.

Customizing SDK Logs

Setting the Log Level

The Heap Swift 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 { Heap, LogLevel } from '@heap/heap-react-native-bridge';

Heap.setLogLevel(LogLevel.Debug);

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

• LogLevel.None: Heap won't print any log messages.
• LogLevel.Error: Heap will only print the most critical log messages, such as when the SDK encounters an error and needs to shut down.
• LogLevel.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.
• LogLevel.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.
• LogLevel.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.
• LogLevel.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.

Routing Logs to Metro

By default, Heap logs all messages to platform-specific tools. These events can be viewed in Android Studio, Xcode, logcat, and Console.app.

To send logs to Metro and console middleware, call Heap.logToConsole().

import { Heap, LogLevel } from '@heap/heap-react-native-bridge';

Heap.logToConsole();

Routing Logs to Custom Destinations

If you are using a logging framework that has console middleware (i.e., it intercepts console messages out of the box), the above Heap.logToConsole() method will get those messages to your logging system.

If not, and you want messages directed to a console, you can write a small LogChannel that consumes messages and routes them to your destination:

import * as log from 'loglevel';
import { Heap, LogLevel } from '@heap/heap-react-native-bridge';

Heap.setLogChannel((logLevel, message, source) => {
  if (!message) {
    return;
  }
  const text = source ? `[${source}] ${message}` : message;
  switch (logLevel) {
    case LogLevel.Error:
      log.error(text);
      break;
    case LogLevel.Info:
      log.info(text);
      break;
    case LogLevel.Warn:
      log.warn(text);
      break;
    case LogLevel.Debug:
      log.debug(text);
      break;
    case LogLevel.Trace:
      log.trace(text);
      break;
    default:
      break;
  }
});