Heap Server-Side API Client for Ruby

Build Status Coverage Status Dependency Status Yard Docs Gem Version

This is a Ruby client for the Heap server-side API.


This gem is tested on MRI 1.8.7 and above, and on JRuby 1.7 and above.


If you're using bundler, add the following line to your Gemfile.

gem 'heap', '~> 1.0'

Otherwise, install the heap gem and activate it in your code manually.

gem install heap
require 'heap'


Place the following code in a file that executes when your application initializes.

Heap.app_id = 'YOUR_APP_ID'

In a Ruby on Rails application, place the following snippet in an initializer, such as config/initializers/heap.rb.

if Rails.env.production?
  Heap.app_id = 'YOUR_APP_ID'
  Heap.app_id = 'YOUR_DEV_APP_ID'

In some testing environments, connecting to outside servers is undesirable. Set the stubbed accessor to true to have all API calls succeed without generating any network traffic.

class StubbedHeapTest < MiniTest::Test
  def setup
    Heap.stubbed = true

  def teardown
    Heap.stubbed = false



Track a server-side event. The properties are optional.

Heap.track 'event-name', 'user-identity', property: 'value'

Add properties to a user.

Heap.add_user_properties 'user-identity', plan: 'premium1'

If the global API client instance stored in Heap is not a good fit for your application's architecture, create your own client instances.

heap_client = Heap.new app_id: 'YOUR_APP_ID'
heap_client.track 'user-identity', 'event-name', property: 'value'


After cloning the repository, install the required gems.

bundle install

Make sure the tests pass after making a change.

rake test

If you submit a pull request, Travis CI will run the test suite against your code on the Ruby VMs that we support. Please fix any errors that it reports.

Legacy Gem Releases

Gem versions below 1.0 come from this repository, which is an entirely different codebase. We are very grateful to @HectorMalot for donating the heap gem name to us.

If you are using a pre-1.0 gem, please consider upgrading to an officially supported release. In the meantime, you can pin the old version in your Gemfile.

gem 'heap', '~> 0.3'


Copyright (c) 2016 Heap Inc., released under the MIT license.