Scorecard

A Rails engine for tracking points, badges and levels for gamification.

For anyone who comes across this, please note this is not yet feature complete, and the API will very likely change.

Installation

Add this line to your application's Gemfile:

gem 'scorecard', '0.1.0'

Don't forget to bundle:

$ bundle

Then, add the migrations to your app and update your database accordingly:

$ rake scorecard:install:migrations db:migrate

Rules

In an initializer, define the events that points are tied to - with a unique context and the number of points:

Scorecard.configure do |config|
  config.rules.add :new_post, 50
end

You can also provide a block with logic for whether to award the points, the maximum number of points allowed to be awarded for this rule, and the timeframe for that limit:

Scorecard.configure do |config|
  config.rules.add :new_post, 50, limit: 100, timeframe: :day,
  if: lambda { |payload| payload[:user].posts.count <= 1 }
end

The payload object contains the context plus every option you send through to score call (see below).

For levels, you can set the central piece of logic that calculates the user's current level in the initializer as well:

Scorecard.configure do |config|
  config.levels = lambda { |user|
    if user.created_at > 2.years.ago
      3
    elsif user.created_at > 1.year.ago
      2
    else
      1
    end
  }
end

Scoring

And then, when you want to fire those events, use code much like the following:

Scorecard::Scorer.points :new_post, gameable: post

This presumes that the user the points are for is a method on the gameable object. If that's not the case, you can pass in a custom user:

Scorecard::Scorer.points :new_post, gameable: post, user: user

If you're using Sidekiq, you can push the scoring behaviour into a background worker using score_async instead. Make sure scorecard is listed below sidekiq in your Gemfile.

Scorecard::Scorer.points_async :new_post, gameable: post

Whenever you want to recalculate a user's level, run the following:

Scorecard::Scorer.level user

To remove points related to a given gameable object, you can use the Scorecard::Cleaner class:

Scorecard::Cleaner.points post

Results

To get the current points count for a given user:

Scorecard::Card.new(user).points

And the current level:

Scorecard::Card.new(user).level

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Licence

Copyright (c) 2013, Scorecard is developed and maintained by Inspire9, and is released under the open MIT Licence.