👍

Target Platforms

This quick start guide shows you how to get Heap set up on an Android or iOS app implemented with Capacitator bridge.

Requirements + Known Limitations

• This SDK requires the following minimum OS versions:
  • iOS 12.0
  • Android API level 21

Installation

To install, run

• npm i @heap/heap-capacitor-bridge
• npx cap sync

Initialize Heap when the app launches

import { Heap, HeapLogger } from '@heap/heap-capacitor-bridge';

Heap.startRecording('YOUR_APP_ID')

You may also want to increase the log level from info to debug to help validate the install:

HeapLogger.setLogLevel('debug');

Log messages will appear in the following places:

• Android:
  • Logcat output in Android Studio.
  • Debug Console in Visual Studio Code.
• iOS:
  • Console debug area in Xcode.
  • Console.app when using Visual Studio Code.
    • Open the macOS console app.
    • Select your simulator or device and start recording.
    • Filter logs to the “Runner” process and the “Heap” category.

API Methods

Start Recording

startRecording(environmentId: string, options?: Options): void;

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 dictionary of configuration options for use starting the SDK.

Example
Heap.startRecording('YOUR_APP_ID');

Stop Recording

stopRecording(): void;

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

Examples

Heap.stopRecording();

Track

track(event: string, properties?: Properties | null, timestamp?: Date | null): void;

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

Parameters

• event: The string name of the event.
• properties (optional): The Object of properties to associate with the event. Object keys are represented by strings and values can be any combination of any string, number, boolean, bigint
• timestamp (optional): The non-null Date of when the event occurs. Defaults to the current time. Customer implementations should not assign values for this parameter.

Examples

Heap.track("Click: Submit", {
    "string property": "string value",
    "number property": 123,
    "boolean property": true
})

Identify

identify(identity: string): void;

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 different from the past identity, this will have the effect or resetting 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 a hard-coded value.

Examples
Heap.identify("THE_IDENTITY")

Reset Identity

resetIdentity(): void;

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 was not previously identified, this method has no effect.

Examples
Heap.resetIdentity()

Add User Properties

addUserProperties(properties: Properties): void;
Description
Add a collection of properties to be associated with the current user.

Parameters

• properties: The Object of properties to associate with the current user. Object keys are represented by strings and values can be any combination of any string, number, boolean, bigint

Examples

Heap.addUserProperties({
  "string property": "string value",
  "number property": 123,
  "boolean property": true
})

Add Event Properties

addEventProperties(properties: Properties): void;

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

Parameters

• properties: The Object of properties to associate with the current user. Object keys are represented by strings and values can be any combination of any string, number, boolean, bigint

Examples

Heap.addUserProperties({
  "string property": "string value",
  "number property": 123,
  "boolean property": true
})

Remove Event Property

removeEventProperty(name: string): void;

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

Parameters

• event: The string name of the event.

Examples
Heap.removeEventProperty("number property")

Clear Event Properties

clearEventProperties(): void;

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

Examples
Heap.clearEventProperties()

Get Session Id

getSessionId(): Promise<string | null>;

Description
Returns the current session ID if Heap is recording and the session has 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 is 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.

Examples
const heapSessionId = await Heap.getSessionId()

Fetch Session Id

fetchSessionId(): Promise<string | null>;

Description

Returns 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

const heapSessionId = await Heap.fetchSessionId()

Get User Id

getUserId(): Promise<string | null>;

Description

Returns 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

const heapUserId = await Heap.getUserId()

Get Identity

getIdentity(): Promise<string | null>;

Description
Returns the 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
const heapIdentity = await Heap.getIdentity()