Heap Server-Side API Client for Ruby

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

Prerequisites

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

Installation

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'

Setup

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'
else
  Heap.app_id = 'YOUR_DEV_APP_ID'
end

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
  end

  def teardown
    Heap.stubbed = false
  end

  ...
end

Usage

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'

Development

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'