Heap

Heap is a simple rubygem that makes is simple to integrate your application with heap analytics. It provides:

Helpers to easily integrate heap into your Rails application
An easy way to submit events to heap directly from your code
The possibility to set additional attributes on your users directly from your app

Installation

Installation is simple via:

gem install heap

For Rails applications, run the following command to add an initiatlizer for your heap app_id:

rails generate heap:install

To enable the tracking code on your website, place the following in just before the closing </head> tag in your layout:

<%= heap_analytics %>

Usage

After installing, you will have access to Heap.event and Heap.identify in your ruby code. For Rails, Heap provides 2 helpers to include the tracking code, and to identify individual users.

Heap needs your application ID to successfully submit data to heapanalytics.com. You can set this directly using Heap.app_id = 123, or in Rails, by using the provided generator to generate an initializer at config/initializers/heap.rb

Identifying your users

The heap_identify view helper can be used to supply heap with attributes for your users. The helper takes 2 arguments:

[String] email: The e-mail address used to identify your visitor in Heap
[Hash, optional] properties: A hash containing additional properties for your users (Hashes with multiple levels are currently not supported)

Example:

<%= heap_identify(current_user.email, name: current_user.name, role: current_user.role) if signed_in? %>

If you wish to use a different handle type, only handle/email are supported at the time of writing, you can set it using Heap.default_handle_type = 'handle'.

Default is set to email.

Adding custom event properties

With heap_set_event_properties, you can specify key-value pairs to associate with all of a user's subsequent events. This helper takes one argument:

[Hash] properties: A hash containing all of the properties you want to attach to the user's events

Tracking server-side events

In case you want to track server-side events -- for example when sending a welcome e-mail to a new user --, you can do so using Heap.event. Heap.event takes 3 arguments:

[String] event: A description of the event
[String] identity: The e-mail address used to identify your user
[Hash, optional] properties: A hash containing additional properties for the event (Hashes with multiple levels are currently not supported)

Example:

Heap.event("Welcome e-mail sent", "[email protected]", promotion:'second gem free', segment:'ruby developers')

Adding server-side user attributes

To update or set properties on your users directly from your application, use Heap.identify. Heap.identify takes 2 arguments:

[String] identity: The e-mail address used to identify your user
[Hash] properties: A hash containing additional properties for your users (Hashes with multiple levels are currently not supported)

Example:

Heap.identify("[email protected]", segment:'ruby developers', age: 25)

Advanced load configuration

When calling 'heap_analytics', you may set additional advanced configuration options (such as secure cookies, enabling SSL, and disabling text capture). The helper takes an optional argument:

[Hash, optional] properties: A hash containing additional configuration options (Hashes with multiple levels are currently not supported)

Example:

  <%= heap_analytics(forceSSL: true, secureCookie: true, disableTextCapture: true) %>

Contributing to Heap

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
Fork the project.
Start a feature/bugfix branch.
Commit and push until you are happy with your contribution.
Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright

The Heap gem is a personal project and not affiliated to heapanalytics.com