Reach out with questions, bugs, or suggestions. We'll respond ASAP. Your message is sent! We'll respond via email shortly.

Custom API

Heap provides an API for custom events and users. On web, all API calls should be made within your page's <body>, after the script has been included.

identify

The identify API lets you attach a unique identifier 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.

Web
  heap.identify('alice123');
iOS
  // Method signature
  + (void)identify:(NSString *)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.

addUserProperties

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

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

Web
  heap.addUserProperties({'Name': 'Alice Smith',
                          'Profession': 'Data Scientist'});
iOS
  // Method signature
  + (void)addUserProperties:(NSDictionary *)properties;

  // Example
  [Heap addUserProperties:@{
      @"Name": @"Alice Smith",
      @"Profession": @"Data Scientist"
  }];
Arguments
  1. user properties: an object containing string key-value pairs to be associated with a user. Keys and values must be a number or string with fewer than 1024 characters.

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

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.

track

Web
  heap.track('Purchase', {dollars: 50, item: 'Furby'});
iOS
  // Method signature
  + (void)track:(NSString *)event withProperties:(NSDictionary *)properties;

  // Example
  [Heap track:@"Open Album" withProperties:@{
      @"gallery": @"Picnic Photos",
      @"pictureCount": @50
  }];
Arguments
  1. event name: name of the custom interaction. Limited to 1024 characters.
  2. event properties: a JSON object or NSDictionary containing key-value pairs to be associated with an event. Keys and values must be a number or string with fewer than 1024 characters.

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

Custom Tracking within iframes

Although we don't have the ability to track events in an iframe, you can utilize the APIs of many companies such as YouTube, Facebook, and Twitter to hook our heap.track API into event listeners. This allows Heap to track what is happening in the iframe!

Tracking Youtube Video Clicks

If you're using YouTube the API reference for iframes is here. This example generates a YouTube video embed and sends a heap.track call for several of the different player states. The way you go about implementing the callbacks is up to you. For example, you can leave out the Video Finished/Paused, and remove the onPlayerReady events and function.

Usually an iframe is embedded like this:

  <iframe allowfullscreen="" frameborder="0" height="360" src="//www.youtube.com/embed/VIDEO_ID" width="640"></iframe>

This example assumes you replace the iframe with the HTML/code below:

  <div id="player"></div>

Then in script tags add the following code. Make sure you replace VIDEO_ID with the videoId unique to your Youtube video.

  var tag = document.createElement('script');
  tag.src = "https://www.youtube.com/iframe_api";
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);
  var player;
  function onYouTubeIframeAPIReady() {
      player = new YT.Player('player', {
          width: '640',
          height: '390',
          videoId: 'VIDEO_ID', //replace VIDEO_ID with the videoId from Youtube
          events: {
             'onPlayerReady': onPlayerReady,
             'onStateChange': onPlayerStateChange
          }
      });
  }

  function onPlayerReady(event) {
      console.log('player ready');
  }

  function onPlayerStateChange(newState) {
      if (newState.data == 1) {
          heap.track('Video Playing');
      } else if (newState.data == 0) {
          heap.track('Video Finished');
      } else if (newState.data == 2) {
          heap.track('Video Paused');
      }
  }
Facebook

Facebook does have a Like button API, which you can usually use to send custom tracking events to Heap. Using the Facebook JavaScript SDK, you can also have events fire when someone clicks the Like button, as described here.

Modifying their example for Heap:

  var page_like_callback = function(url, html_element) {
      heap.track('Clicked Like Button');
  }

Make sure to include the following in your onload handler :

  FB.Event.subscribe('edge.create', page_like_callback);

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.

Web
  heap.addEventProperties({'Logged In': 'true', 'Payment Plan': 'Free'});
iOS
  // Method signature
  + (void)addEventProperties:(NSDictionary *)properties;

  // Example
  [Heap addEventProperties:@{
      @"Logged In": @"true",
      @"Payment Plan": @"Free"
  }];
Arguments
  1. event properties: a JSON object or NSDictionary containing key-value pairs to be associated with every subsequent event. Keys and values must be a number or string fewer than 1024 characters.

removeEventProperty

Stops a single event property from getting attached to all subsequent events.

Web
  heap.removeEventProperty('Logged In');
iOS
  // Method signature
  + (void)removeEventProperty:(NSString *)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.

clearEventProperties

Removes all stored event properties.

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

  // Example
  [Heap clearEventProperties];

userId and Identity

Retrieves the current user's user_id, which was automatically generated by the Heap library, or the identity if the user is no longer anonymous. 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.

Web
  var userid = heap.userId;
  var identity = heap.identity;
iOS
  // Method signature
  - (NSString * const)userId;

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

changeInterval (iOS only)

Changes the frequency with which events are sent back to the Heap server from an iOS mobile device.

  // Method signature
  + (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 (iOS only)

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