track
Send additional events to Heap.
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
- (required)
event name
: name of the custom interaction. Limited to 255 characters. - (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.
identify
Attach a unique identity to a user.
Do Not Use a Non-Unique Identifier
Passing a non-unique identifier in the identify field, such as 'undefined', 'null', or 'user' will result in all anonymous user data being merged into one user profile. This will destroy the integrity of your data and cannot be undone. Review the Identify Pitfalls section of our Using Identify guide for steps to manage anonymous users.
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
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.
The string you pass to heap.identify() is case sensitive. To avoid split users due to capitalization, we recommend converting your identity to lowercase before sending to Heap if you are using email as the identity.
resetIdentity
Reset a user's identity to an anonymous state.
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.
// 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()
Update Your Heap Snippet
To take advantage of resetIdentity()
you must make sure your snippet matches the version in our installation instructions. Please reach out to support@heap.io with any questions!
addUserProperties
Attach custom properties to user profiles.
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
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.
Important
If you want to write your user's email into the builtin Email property, you must send the key lowercase i.e. heap.addUserProperties({"email": "user@example.com"});
Sending an email value with a non-lowercase key will create a new property to store this data.
Requests are limited to 30 requests per 30 seconds per identity per app_id
addEventProperties
Specify a set of global key-value pairs to get attached to all of a user's subsequent events.
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
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.
removeEventProperty
Stops a single event property from getting attached to all subsequent events.
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");
clearEventProperties
Removes all stored event properties.
heap.clearEventProperties();
// Method signature
- (void)clearEventProperties;
// Example
[Heap clearEventProperties];
// Method signature
public static void clearEventProperties();
// Example
clearEventProperties();
userID and Identity
Retrieves the current user's ID or identity.
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.
changeInterval
Changes the frequency with which events are sent back to the Heap server from an iOS mobile device.
+ (void)changeInterval:(double) interval;
// Change interval to send data every 25 seconds
[Heap changeInterval:25.0];
setAppId
Sets the app ID where you'll be sending data. It can be used to switch between projects or between your production and development environments.
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>');
init
Sets the app ID where you'll be sending data. It can be used to switch between projects or between your production and development environments.
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>");
startEVPairing
Starts the Android Event Visualizer pairing process. It may be used to provide an custom method of initiating Event Visualizer pairing.
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 Event Visualizer pairing process.
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]
Disable Mobile Visualizer Pairing Gesture
Disables the default gesture for pairing with mobile Event Visualizers
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]
Add User Properties
You can also assign custom properties to any of your users from your servers.
Important
If you want to write your user's email into the builtin Email property, you must send the key lowercase as per the example above.
Sending an email value with a non-lowercase key will create a new property to store this data.
Requests are limited to 30 requests per 30 seconds per identity per app_id
Bulk Track
If you have many custom events to send at once, you can use our bulk Track API.
Requests are limited to 1000 events per minute per identity per app_id and 15,000 events per minute per app_id
Bulk Add User Properties
Important
If you want to write your user's email into the builtin Email property, you must send the key lowercase as per the example above.
Sending an email value with a non-lowercase key will create a new property to store this data.
User Deletion
Delete users from a Heap account
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 support@heap.io if you require an API key.
The user deletion API checks all environments in your account for a matching user and deletes their records and data. The API auths using a combination of the environment id of your Main Production environment ( app_id
) and an api_key. Using any other environment id in the request will result in an Unauthorized
response.
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
- Basic auth header:
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
oridentity
- Headers
- Bearer auth header:
auth_token
- Content-type:
Application/json
- Bearer auth header:
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>
- deletion_request_location:
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": "alice@email.com" }, { "identity": "bob@email.com" }] }'
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
- Bearer auth header:
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 successfully401
- Unauthorized. Occurs when the credentials are invalid for a specific request (e.g. badapi_key
when requesting anauth_token
, or requesting a user deletion in an env that the suppliedauth_token
does not authorize)404
- Not found. Occurs when requesting adeletion_request_id
that does not exist, or belongs to an env theauth_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.