Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results
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.

 

Heap's identify API enables you to attach a unique identity to a user that will be used to merge users and receive data from other data sources including integrating with our server-side API. The API also enables you to change a user's identity based on the customer lifecycle and Heap will store the history of user identities to receive data in the future.

When called, Heap will attach a unique identity to a user based on the identity value and a user property with the name identity_type with the value of identity. If another identity is available for a user in the future, you can call the identify API with a second set of arguments to change the user's primary identifier. Please note that Heap will also store the history of previous identities as unique values that can merge user data. In the example below, a user's email is available and uniquely identifying until a user creates their account where the primary key is a user ID.

// Format
heap.identify(identity, identity_type);

// When a user provides their email address, uniquely identify them based on their email and create a user property for Email:
heap.identify('foo@bar.com', 'email');

// When a user becomes a customer, re-identify them based on their User ID and create a user property for User ID:

heap.identify('12345', 'ID');
//Method Signature
+ (void)identify:(NSString *)identity;

// Example
[Heap identify:@"alice123"];
// Method signature
public static void identify(String identity);

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

Per the above example, the following would occur in Heap assuming a user is not already identified:

  • When heap.identify('foo@bar.com', 'email) is called for a given user:
    • The user is no longer anonymous and is uniquely identified by foo@bar.com. The builtin Email user property will also be written to with the value of foo@bar.com.
  • When heap.identify('12345', 'ID'): is later called for the same user:
    • The user is re-identified from foo@bar.com to 12345. An ID user property will be created with the value of 12345.
  • After both identities have been provided to Heap, a user will have the identity value of 12345 with two user properties containing the latest identity value for a given identity_type. Heap will merge data to this user if data is sent to Heap for a user identified by either foo@bar.com or 12345.

Switching Users

If a given client switches to a different user (login as a different user, sharing computers, etc.), you'll need to call heap.resetIdentity() when a user logs out or is no longer identified by the previous identities. Any event behavior after calling heap.resetIdentity() will be associated with the next identity value provided via heap.identify().

To support previous versions of our identify API (before April 2018), Heap will also switch user identities (and create a new user) when only one argument is provided (only the identity value). If you are migrating from a previous implementation of our identify API, we also recommend reading our identify migration guide.

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.
  2. identity_type: 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 automatically identify the user based on identity and will create a user property named identity_type with the value of identity. Must be fewer than 255 characters.

Case Sensitivity

The strings you pass to heap.identify() are 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 an 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 or when your application has the concept of a user switch applied (Jane is now using the application instead of John). The event data from the client after heap.resetIdentity() is called will be associated with an anonymous user or the next identity value provided via heap.identify thereafter.

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

heap.resetIdentity();
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 user_id 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.

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

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

 

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. Limited to 255 characters.

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

This API is not intended to support large-scale event backfills. Please contact support@heapanalytics.com if you are interested in ingesting past data.

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