Capacitor Bridge quick start
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): TheObject
of properties to associate with the event. Object keys are represented by strings and values can be any combination of anystring
,number
,boolean
,bigint
timestamp
(optional): The non-nullDate
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
: TheObject
of properties to associate with the current user. Object keys are represented by strings and values can be any combination of anystring
,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
: TheObject
of properties to associate with the current user. Object keys are represented by strings and values can be any combination of anystring
,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()
Updated 9 months ago