heap.track('Purchase', {dollars: 50, item: 'Furby'});

// Method signature
+ (void)track:(NSString *)event withProperties:(NSDictionary *)properties;

// Example
[Heap track:@"Open Album" withProperties:@{@"gallery": @"Picnic Photos", @"pictureCount": @50}];

// Method signature
public static void track(String event, /* @Nullable */ Map<String, String> properties);

// Example
Map<String, String> props = new HashMap<>();
props.put("gallery", "Picnic Photos");
props.put("pictureCount", String.valueOf(50));
Heap.track("Open Album", props);

Arguments

1. (required) event name: name of the custom interaction. Limited to 255 characters.
2. (optional) event properties: a JSON object, NSDictionary, or Map containing key-value pairs to be associated with an event. Keys and values must be a number or string.

For Android, the properties map may be null to track an event with no properties. The property map keys and values must be converted to strings, but they can be queried as numbers in Heap.

Custom event properties can be queried in the same fashion as any other event property.

For instructions on setting up common custom events, including tracking impressions, field validation errors, page load time, and hover events, see our documentation on Common Custom Events.

If you assign the same identity to a user on a separate device, their past sessions and event activity will be merged into the existing Heap user with that identity.

To better understand the client-side identify and addUserProperties APIs, take a look at our comprehensive guide.

heap.identify('alice123');

//Method Signature
+ (void)identify:(NSString *)identity;

// Exampe
[Heap identify:@"alice123"];

// Method signature
public static void identify(String identity);

// Example
Heap.identify("alice123");

Arguments

1. identity: a case-sensitive string that uniquely identifies a user, such as an email, handle, or username. This means no two users in one environment may share the same identity. Must be fewer than 255 characters.

heap.resetIdentity() resets a user's identity to a random anonymous user ID. A new session for anonymous user will begin when called if the user was previously identified. The method has no effect if the user was previously anonymous when called.

This method should be used typically when a user logs out of an application on a device that might be shared with others who use the application, or when your application has the concept of a user switch applied (Jane is now using the application instead of John, this is common for support teams who log in or "masquerade" as their customers). The event data from the client after heap.resetIdentity() is called will be associated with an anonymous user and the next identity value provided via heap.identify if it is called later.

Note that calling this method disassociates the user from any user properties set with addUserProperties().

// resetIdentity should be called when a user logs out of an application.

heap.resetIdentity();

// Method signature
- (void)resetIdentity;

// resetIdentity should be called when a user logs out of an application.
[Heap resetIdentity]

// Method signature
public static void resetIdentity();

// resetIdentity should be called when a user logs out of an application.
Heap.resetIdentity()

The addUserProperties API lets you attach custom properties to user profiles, such as account-level info from your database, or demographic info.

To better understand the client-side identify and addUserProperties APIs, take a look at our comprehensive guide.

heap.addUserProperties({'Name': 'Alice Smith','Profession': 'Data Scientist'});

// Method signature
+ (void)addUserProperties:(NSDictionary *)properties;

// Example
[Heap addUserProperties:@{@"Name": @"Alice Smith", @"Profession": @"Data Scientist"}];

// Method signatures
public static void addUserProperties(Map<String, String> properties);

// Example
Map<String, String> props = new HashMap<>();
props.put("Name", "Alice Smith");
props.put("Profession", "Data Scientist");
Heap.addUserProperties(props);

Arguments

1. user properties: a JSON object, NSDictionary, or Map containing key-value pairs to be associated with a user. Keys and values must be a number or string, with the value being 255 characters or fewer.

Also, the string user_id cannot be used as a key in the user properties object.

For Android, the property map keys and values must be converted to strings, but they can be queried as numbers in Heap.

User properties are associated with all of the user's past activity, in addition to their future activity. Custom user properties can be queried in the same fashion as any other user property.

These event properties are stored in a cookie and will persist across multiple events and sessions on the same device. They are applied to both autocaptured and custom events.

This is useful if you have some persistent state, and you don't want it to apply to all of a user's events by calling addUserProperties. A good example is "Logged In", which changes over the user's lifecycle. You can use addEventProperties to measure how a user's behavior changes when they're logged in vs. when they're logged out.

heap.addEventProperties({'Logged In': 'true', 'Payment Plan': 'Free'});

// Method signature
+ (void)addEventProperties:(NSDictionary *)properties;

// Example
[Heap addEventProperties:@{@"Logged In": @"true", @"Payment Plan": @"Free"}];

// Method signature
public static void addEventProperties(Map<String, String> properties);

// Example
Map<String, String> props = new HashMap<>();
props.put("Logged In", "true");
props.put("Payment Plan", "Free");
Heap.addEventProperties(props);

Arguments

1. event properties: a JSON object, NSDictionary, or Map containing key-value pairs to be associated with every subsequent event. Keys and values must be a number or string fewer than 1024 characters.

For Android, the property map keys and values must be converted to strings, but they can be queried as numbers in Heap.

heap.removeEventProperty('Logged In');

// Method signature
+ (void)removeEventProperty:(NSString *)property;

// Example
[Heap removeEventProperty:@"Logged In"];

// Method signature
public static void removeEventProperty(String property);

// Example
Heap.removeEventProperty("Logged In");

Arguments

1. event property: name of the event property to remove. This stops attaching the property to all subsequent events.

This is primarily used in conjunction with the server-side API. The userId can only be used with anonymous users and the identity with identified users.

var userid = heap.userId;
var identity = heap.identity;

// Method signature
- (NSString * const)userId;

// Example
NSString *userid = [Heap userId];

These are not yet exposed in the Android SDK.

+ (void)changeInterval:(double) interval;

// Change interval to send data every 25 seconds
[Heap changeInterval:25.0];

Arguments

1. interval: number of seconds in length

setAppId initializes Heap tracking on iOS or React Native. It should be called only once per app open. If it is called multiple times, it will initiate a new session for the user.

// Method signature
+ (void)setAppId:(NSString *) appId;

// Send data to a different project
// This is actually one of your project IDs!
[Heap setAppId:@"21"];

// React Native function declaration
export function setAppId(appId: string): void;

// Usage
Heap.setAppId('<your-app-id>');

Arguments

1. appId: the appId corresponding to one of your projects

init initializes Heap tracking on Android. It should be called only once per app open.

// Method signature
public static void init(Context context, String appId);

// Send data to a different project
// This is actually one of your project IDs!
Heap.init(getApplicationContext(), "<your-app-id>");

Arguments

1. context: the application context for the Android app
2. appId: the appId corresponding to one of your projects

startEVPairing begins the Android and iOS Event Visualizer pairing process. It may be called to provide an alternate method of initiating the Event Visualizer pairing, often from a button on a debug menu, or in order to provide a pairing gesture other than the out-of-the-box default.

// Method signature
public static void startEVPairing();

// Start EV pairing
Heap.startEVPairing()

// Method signature
+ (void)startEVPairing;

// Start EV pairing
[Heap startEVPairing]

stopEVPairing stops the Android and iOS Event Visualizer pairing process. It may be called to explicitly shut down the pairing process.

// Method signature
public static void stopEVPairing();

// Stop EV pairing
Heap.stopEVPairing()

// Method signature
+ (void)stopEVPairing;

// Start EV pairing
[Heap stopEVPairing]

disableVisualizerPairingGesture disables the out-of-the-box pairing gesture for mobile Event Visualizers. This can be called from production apps to ensure that end users don't accidentally trigger an EV pairing process.

The API is currently slightly different for Android, using disableDefaultPairingGesture. This API will be deprecated in an upcoming release and replaced with disableVisualizerPairingGesture.

// Method signature
public static void disableDefaultPairingGesture();

// Disable the default EV pairing gesture
Heap.disableDefaultPairingGesture()

// Disable iOS visualizer default pairing gesture
[Heap disableVisualizerPairingGesture]

If you're planning to measure account health in Heap, you should use this endpoint to send useful account properties for analysis (e.g. payment tier, account owner, account name, etc). This endpoint can be used for either a single account, or multiple accounts at once.

To delete a user from your Heap account, follow these instructions.

All endpoints require an auth_token, which is obtained through HTTP Basic Authentication of an app_id and api_key, where app_id is the username and api_key is the password:

    Authorization: Basic <app_id>:<api_key>

The app_id and api_key will be provided by Solutions Engineering. Please contact [email protected] if you require an API key.

Once an auth_token is acquired, other endpoints can be accessed by passing the auth_token as a bearer token in the Authorization header:

    Authorization: Bearer <token>

API Endpoints

POST /api/public/v0/auth_token

This endpoint uses HTTP Basic Authentication to acquire a temporary auth_token from API credentials. The returned auth_token is used for authentication on the other endpoints.

Request

• Headers
  • Basic auth header: app_id:api_key

Response

• Code: 200 if credentials are valid.
• Body:
  • err (if unsuccessful)
  • auth_token (if successful)

Example
Request:

    curl -X POST https://heapanalytics.com/api/public/v0/auth_token -u '<app_id>:<api_key>'

Response:

    { "auth_token": "<auth_token>" }

POST /api/public/v0/user_deletion

Submits users to be deleted from Heap, and returns a unique identifier for the request (deletion_request_id). Up to 10,000 users can be submitted in a single request.

Request

• Body:
  • users[]
    • user_id or identity
• Headers
  • Bearer auth header: auth_token
  • Content-type: Application/json

Response

• Status: 201 if successful, 401 if unauthorized

If unsuccessful:

• Body:
  • error (if unsuccessful)
  • message (human readable)
  • Maybe other fields (symbolic reason, code, etc.)

If successful:

• Body:
  • deletion_request_location: https://heapanalytics.com/api/public/v0/deletion_status/<deletion_request_id>
  • deletion_request_id: <deletion_request_id>
  • status: <deletion_request_status>

Example
Request:

    curl -X POST https://heapanalytics.com/api/public/v0/user_deletion \
        -H 'Authorization: Bearer <token>' \
        -H 'Content-type: Application/json' \
        -d '{ "users": [{ "user_id": 1 }, { "user_id": 2 }] }'

    curl -X POST https://heapanalytics.com/api/public/v0/user_deletion \
        -H 'Authorization: Bearer <token>' \
        -H 'Content-type: Application/json' \
        -d '{ "users": [{ "identity": "[email protected]" }, { "identity": "[email protected]" }] }'

Response:

{
  "deletion_request_location": "https://heapanalytics.com/api/public/v0/deletion_status/c93fae81-f67a-46d6-acf1-0c3ba1c3e5a6",
  "deletion_request_id": "c93fae81-f67a-46d6-acf1-0c3ba1c3e5a6",
  "status": "pending"
}

GET /api/public/v0/deletion_status/:deletion_request_id

Fetches the status of the user deletions submitted in the request identified by deletion_request_id.

Request

• Headers
  • Bearer auth header: token

Response

• Status: 200 if found, 404 if does not exist
• Body:
  • deletion_request_id
  • status (‘pending’ or ‘complete’)

Example
Request:

    curl -G https://heapanalytics.com/api/public/v0/deletion_status/<deletion_request_id> \
        -H 'Authorization: Bearer <token>'

Response:

    {
      "deletion_request_id": <deletion_request_id>,
      "status": pending
    }

Errors

Errors will manifest in the response code and on an err object in the response body.

Status Codes

• 200 - The request completed successfully
• 401 - Unauthorized. Occurs when the credentials are invalid for a specific request (e.g. bad api_key when requesting an auth_token, or requesting a user deletion in an env that the supplied auth_token does not authorize)
• 404 - Not found. Occurs when requesting a deletion_request_id that does not exist, or belongs to an env the auth_token does not authorize.

err Object

The err object will appear only when an error occurs, and will have the following properties:

• message - A human-readable description of the error
• Other properties may be present.