B

Ruby Gem

Our API can be easily accessed using the StatsMix ruby gem. To install it, just run:

$ gem install statsmix

You must have an API key to use the gem. You can find it in the API section under "My Account" in StatsMix. If you don't have an account, sign up for a free Developer account here.

Once you have your API key, configure the gem according to your version of Rails.


For Rails 2

Add the following to config/environment.rb, then restart the server:

gem 'statsmix'
StatsMix.api_key = "YOUR API KEY"

For Rails 3

Add the following to your Gemfile:

gem 'statsmix'

Then create an initializer (config/initializers/statsmix.rb) with your StatsMix API key and restart the server:

StatsMix.api_key = "YOUR_API_KEY"

Using StatsMix to Track Events

Any time you want to track an event in your app, simply call:

StatsMix.track(name_of_metric, value = 1, options = {})

If a metric with that name doesn't exist in your account, one will be created automatically. If the profile isn't set, the metric will use the first profile_id created in your account. (Developer, Basic, and Standard plans only have one profile.)


Examples

Track every time a new blog post is created:

# create a stat with the value 1 (default) for the metric called "Blog Posts"
StatsMix.track("Blog Posts")

Count the number of new user accounts in the last 24 hours (i.e. run daily in a daily rake task):

count = User.count(:conditions => ["created_at >= ?", 24.hours.ago]) 
# create a stat with the value count for the metric called "Daily New Users"
StatsMix.track("Daily New Users", count)

Adding Metadata

You optionally can "tag" your data with metadata in the :meta option. For example, if you have a file upload utility and want to track what kinds of files you are receiving:

# a user just uploaded a PDF file; track the type of file using metadata
StatsMix.track("File Uploads", 1, {:meta => {"file type" => "PDF"}})

You can include multiple key-value pairs in the same stat:

StatsMix.track("File Uploads", 1, {:meta => {"file type" => "PDF", "size" => "1 mb", "country of origin" => "Absurdistan"}})

Adding Your Own Identifier

If you need the ability to update a stat after the fact, you can pass in a unique identifier ref_id (scoped to that metric).

For example, perhaps you want to update the number of users every hour instead of every day. If you pass in the date as ref_id, StatsMix will check whether a stat with that ref_id already exists for that metric. If found, StatsMix will update instead of inserting.

count = User.count(:conditions => ["created_at >= ?", Time.now.strftime("%Y-%m-%d")]) 
# create/update a stat using today"s date as the unique identifier
StatsMix.track("Daily New Users", count, {:ref_id => Time.now.strftime("%Y-%m-%d")})

Additional Options

If you’d like to change the timestamp of a stat, pass in the parameter generated_at, which is a datetime value. Any datetime value is stored in the database as UTC. For daily email reports and charting on the StatsMix site, we convert from UTC to the user's timezone, which can be configured in the Account Settings section of StatsMix.

# backdate the stat to yesterday
StatsMix.track("Blog Posts", 1, {:generated_at => 1.days.ago})

Higher level StatsMix accounts can have additional profiles. A profile can be described as a grouping or "bucket" of metrics. For example, an agency may want to create a profile for each customer.

If you are tracking metrics with the same name in two different profiles, you must specify which profile to use with profile_id. (If you don't specify profile_id, StatsMix will default to the first profile in your account.)

StatsMix.track("Blog Posts", 1, {:profile_id => 789})

You can find the profile ID in StatsMix by creating a metric and looking at the API Details under Code Snippets in the Data & API section. (It will also be in the URL as /profiles/123/metrics/456 - in this case the profile id is 123.)


Limitations

If you hit a plan level limit (i.e. you go over the number of API requests available to your account), the API will return a 403 Forbidden error and an explanation.

The number of API requests and profiles you can create is based on the type of account you have. For example, Standard plans are limited to 300,000 API requests per month. You can see the current options on our pricing page.


Local Setup

When running StatsMix in development, you can tell StatsMix to either ignore calls to it altogether or funnel them all into a single test metric.

For ignoring calls altogether, just put the following in a configuration file such as environment.rb or an initializer:

StatsMix.ignore = true

For logging to a test metric, add this instead:

StatsMix.test_metric_name = "My Test Metric"

This routes all StatsMix.track calls to "My Test Metric" regardless of the metric name passed.

Notice If StatsMix.ignore is set, then the test metric will not be used unless StatsMix.ignore is first reset to false.