Suggest Edits

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
  1. event name: name of the custom interaction. Limited to 255 characters.
  2. 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.

Suggest Edits

identify

Attach a unique identity to a user.

 

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.

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.

Suggest Edits

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

Update Your Heap Snippet

To take advantage of resetIdentity() you must make sure your snippet matches the version in our installation instructions. Please contact Support with any questions!

Suggest Edits

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

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

Suggest Edits

addEventProperties

Specify a set of global key-value pairs to get attached to all of a user's subsequent events.

 

These event properties will persist across multiple sessions on the same device and get applied to both auto-captured and custom events.

This is useful if you have some persistent state, but you don't want to apply it across all of a user's events with identify. 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.

Suggest Edits

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");
// 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.
Suggest Edits

clearEventProperties

Removes all stored event properties.

 
heap.clearEventProperties();
// Method signature
- (void)clearEventProperties;

// Example
[Heap clearEventProperties];
// Method signature
public static void clearEventProperties();

// Example
clearEventProperties();
Suggest Edits

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.

Suggest Edits

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];
Arguments
  1. interval: number of seconds in length
Suggest Edits

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. 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"];
Arguments
  1. appId: the appId corresponding to one of your projects
posthttps://heapanalytics.com/api/track
curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "11",
    "identity": "alice@example.com",
    "event": "Send Transactional Email",
    "timestamp": "2017-03-10T22:21:56+00:00", 
    "properties": {
      "subject": "Welcome to My App!",
      "variation": "A"
    }
  }' \
  https://heapanalytics.com/api/track
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

app_id
string
required

The app_id corresponding to one of your projects.

identity
string
required

An identity, typically corresponding to an existing user. If no such identity exists, then a new user will be created with that identity. Case-sensitive string, limited to 255 characters.

identity_type
string

A case-sensitive string that defines what type of identity you are sending to Heap (email, user ID, etc.) and can be any custom string. When provided, Heap will create a user property named identity_type with the value of identity. This is only needed if you have an advanced multi-type identify implementation.

event
string
required

The name of the server-side event. Limited to 1024 characters.

properties
object

An object with key-value properties you want associated with the event. Each key and property must either be a number or string with fewer than 1024 characters.

 
timestamp
string

ISO8601 or unix epoch milliseconds e.g. "2017-03-10T22:21:56+00:00".

idempotency_key
string

A unique ID that will be hashed to Heap's event ID keyspace, to prevent duplication of events. Subsequent calls with the same idempotency key will not update data.

 

Requests are limited to 30 requests per 30 seconds per identity per app_id

Suggest Edits

Add User Properties

You can also assign custom properties to any of your users from your servers.

 
posthttps://heapanalytics.com/api/add_user_properties
curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "11",
    "identity": "bob@example.com",
    "properties": {
      "age": "25",
      "language": "English",
      "profession": "Scientist",
      "email": "bob2@example2.com"
    }
  }' \
  https://heapanalytics.com/api/add_user_properties
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

app_id
string
required

The app_id corresponding to one of your projects.

identity
string
required

An identity, typically corresponding to an existing user. If no such identity exists, then a new user will be created with that identity. Case-sensitive string, limited to 255 characters.

identity_type
string

A case-sensitive string that defines what type of identity you are sending to Heap (email, user ID, etc.) and can be any custom string. When provided, Heap will create a user property named identity_type with the value of identity. This is only needed if you have an advanced multi-type identify implementation.

properties
object

An object with key-value properties you want associated with the user. Each key and property must either be a number or string with fewer than 1024 characters.

 
 

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

Suggest Edits

Bulk Track

If you have many custom events to send at once, you can use our bulk Track API.

 
posthttps://heapanalytics.com/api/track
curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "app_id": "12343283",
  "events": [{
    "identity": "alice@gmail.com",
    "timestamp": "2016-05-10T22:21:56+00:00",
    "event": "Phone Call",
    "properties": {
      "Sales Rep": "Joe Smith",
      "Duration" : "15 minutes",
      "Purpose" : "Discovery Call"
    }
  },
  {
    "identity": "mike@gmail.com",
    "timestamp": "2016-05-10T22:23:56+00:00",
    "event": "Phone Call",
    "properties": {
      "Sales Rep": "Susie Smith",
      "Duration" : "30 minutes",
      "Purpose" : "Discovery Call"
    }
  }]
  }'\
  https://heapanalytics.com/api/track
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

app_id
string
required

The environment ID corresponding to one of your environments.

events
array of objects
required

An array of events where each item in the array is an object containing the following

identity
identity_type
timestamp
event
idempotency_key
properties 
 

Requests are limited to 1000 events per minute per identity per app_id and 15,000 events per minute per app_id

Suggest Edits

Bulk Add User Properties

 
posthttps://heapanalytics.com/api/add_user_properties
curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "app_id": "12345",
  "users":[{
    "identity": "alice@example.com",
    "properties": {
      "Role": "Admin",
      "Vertical": "Ecommerce",
      "email": "alice2@example2.com"
      }
  },
   {"identity": "bob@example.com",
    "properties": {
      "Role": "User",
      "Vertical": "Saas",
      "email": "bob2@example2.com"
      }
  }]
  }' \
  https://heapanalytics.com/api/add_user_properties
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

app_id
string
required

The app_id corresponding to one of your projects.

users
array of objects
required

Max of 1000 users per request

identity
identity_type
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.

Suggest Edits

User Deletion

Delete users from a Heap account

 

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

Auth

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 solutions@heapanalytics.com 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": "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

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.