heap-api
v1.0.1
Published
Heap Server-Side API Client
Downloads
580
Readme
Heap Server-Side API Client for Node.js
This is a node.js client for the Heap server-side API.
Prerequisites
This package is tested on node.js 0.10 and above.
Installation
Install using npm.
npm install [email protected] --save
Usage
Create an API client.
var heap = require('heap-api')('YOUR_APP_ID');
Recommended Usage Patterns
Track a server-side event in a fire-and-forget fashion.
heap.track('event-name', 'user-identity');
heap.track('event-name', 'user-identity', { property: 'value' });
Add properties to a user. Take advantage of the returned ES6 Promise to do more work when the call completes.
heap.addUserProperties('user-identity', { plan: 'premium1' })
.then(function() {
// Do more work.
});
Set up an event listener to log Heap API call failures.
heap.on('error', function(error) {
console.error(error);
});
Callback-Based Usage
Track a server-side event.
heap.track('event-name', 'user-identity', function(error) {
if (error)
console.error(error);
});
Track a server-side event with properties.
heap.track('event-name', 'user-identity', { property: 'value' }, function(error) {
if (error)
console.error(error);
});
Add properties to a user.
heap.addUserProperties('user-identity', { plan: 'premium1' }, function(error) {
if (error)
console.error(error);
});
Promise-Based Usage
The methods described above return
ES6 Promises.
The promises can be safely ignored. track
is a good candidate for
fire-and-forget usage.
heap.track('event-name', 'user-identity');
Alternatively, the promises can be used to learn when an API call completes or fails.
heap.addUserProperties('user-identity', { plan: 'premium1' })
.then(function() {
console.log("API call succeeded");
});
.catch(function(error) {
console.error(error);
});
The Promises are created using any-promise, which can be configured to use your application's favorite Promise implementation. The v8 Javascript engine versions used by node.js 0.12 and above include a native Promise implementation that is used by default.
require('any-promise/register')('when');
On node.js 0.10 and below, you must either explicitly configure a Promise library, or install a polyfill such as es6-promises, as shown below.
require('es6-promises').polyfill();
Stubbing
In some testing environments, connecting to outside servers is undesirable. Set
the stubbed
property to true
to have all API calls succeed without
generating any network traffic.
beforeEach(function() {
heap.stubbed = true;
});
afterEach(function() {
heap.stubbed = false
});
Alternatively, pass the stubbed
option when creating the API client.
var heap = require('heap-api')('YOUR_APP_ID', { stubbed: true });
Development
After cloning the repository, install the dependencies.
npm install
Make sure the tests pass after making a change.
npm test
When adding new functionality, make sure it has good test coverage.
npm run cov
When adding new functionality, also make sure that the documentation looks reasonable.
npm run doc
If you submit a pull request, Travis CI will run the test suite against your code on the node versions that we support. Please fix any errors that it reports.
Copyright
Copyright (c) 2016 Heap Inc., released under the MIT license.