Heap Server-Side API Client for Ruby

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

Prerequisites

This gem is tested on Ruby 1.8.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 'user-handle', 'event-name', property: 'value'

Add properties to a user.

Heap.add_user_properties 'user-handle', 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-handle', 'event-name', property: 'value'

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.