Gioco: The Gamification Gem

Share this article

new_logoIn the past two years I’ve heard a lot about new marketing techniques, and how they can be applied in web development. One of the most well known techniques these days is gamification. This article explains what gamification is and how you can use it with a new gem.

What is Gamification?

It’s a technique based on rewarding the user for the purpose of of keeping them focused and engaged. In essence, gamification keeps the user coming back with the promise of “levelling up” and continued rewards.

Is Gamification New?

Gamification, as a marketing concept, isn’t new. On the contrary, it has been used for quite some time by many different business areas, such as banking, travel companies and others.

If it isn’t news, why has it spread so quickly in the past few years?

It’s simple. Someone changed the business world rules and now we have a different context. We have younger entrepreneurs building applications and services for younger audiences who demand these features.

The old marketing techniques don’t work so well anymore, thus it’s getting harder to keep users engaged, particularly younger audiences.

All this new context, along with the successful implementations like Zinga and Foursquare, are responsible for bringing gamification back again.

The founder of SCVNGR, Seth Priebatsch, has a strong opinion:

“It feels like the next natural evolution of human-technological interaction to me”

”As we complete the social layer, we’ll begin construction in earnest on the game layer.”

We, as developers, often wear business and marketing hats, so we should be aware of the best known ways of using techniques like gamification in our development process.

Basic Theory Behind Gamification

There are not too many secrets behind gamification, almost every implementation is tied to one of the five most commonly used game mechanics:
– Points
– Badges
– Levels
– Leaderboards
– Challanges

Based on those rules, I started the Gioco project.


Gioco, is a gem that implements gamfication for Rails applications using Active Record.

It isn’t a closed implementation by itself, it just gives you the means that you need to build what you want using common game mechanics.

Why Did I Make It?

In January of 2012, I was starting this new Brazilian e-commerce project as a consultant. The CEO did some research about the efficiency of gamification techniques in sales and that resulted in a big task for our development team. Before we began to implement this feature, we decided to look for a service or a gem that could help us to do it faster, avoiding known initial mistakes.

After some more research, we found a few solutions, but most were what I call “Plug & Play Platforms”, such as Bunchball, BadgeVille, and BigDoor. Usually, I wouldn’t have any issue using an external service. In fact, we do this in many of our applications. However, in this case, I was not confortable sharing my users’ behavior information and some of my business rules with an external service, nor was I confortable about having to implement fallbacks in case that service goes offline.

My colleges and I discussed how it would be nice to have a toolbox to help us with the Architecture and Usual Methods of a gamification implementation. Thus, Gioco was born.

The Logic

It’s simpler than you might imagine. The idea is that all gamification implementations are built around stages, phases, or Badges – as I prefer to call it. The basic Gioco setup would involve only Badges, but you can also tie those badges with any points system. Here is a basic flow:

Badges Flow

It follows a Linear Progression, so you earn one badge to get the another one. Also, if you own Badge #3 at the beginning, you will automatically win Badge #2 since it’s positioned before the first one in the Linear Expectation.

What if you don’t want to use a Linear Progression implementation because your application is going to have different Types of Badges? In that case, you can use a points system, so you will also have different types of Points.

Badges Complex Flow

This is an example of a Multiple Linear Progression. You’ll have different types (groups) of badges that will be organized following a Linear Progression. The logic is still the same, but your user will have different amounts of points for each type.

The points system is optional. If you don’t need it, you can setup Gioco without it and manage badges by itself.

How to Start

TThe first step to use Gioco is to add it to your Gemfile and run de bundle command:

gem 'gioco'


The Gioco setup command is a Rails Generator that accept two parameters --points and --types, both can be used together.

When you set up Gioco, it will ask you for your resource model, and expect that to already exist.

To setup badges:

rails g gioco:setup

To setup badges of different types:

rails g gioco:setup --types

To setup badges with points system:

rails g gioco:setup --points

To setup badges of different types and with points system:

rails g gioco:setup --points --types

Badges Management

The Badges are added and removed by Rake tasks that will support different arguments depending on the ones that you used in the set up process.

All operations using those rake tasks will generate seed files. As a result, when you decide to move your application to another environment like QA, Staging or Production, just run rake db:seed and every badge and type will be created and/or removed as you have specified in the development environment.

Adding Badges

The POINTS_NUMBER and TYPE_NAME arguments should only be used if you set up gioco with it. Otherwise, they can be ignored.

The DEFAULT argument is optional, it will automatically add the badge created to all Resources that you already have in you database.

Destroying Badges

The TYPE_NAME should only be used if you set up gioco with it.

rake gioco:remove_badge[BADGE_NAME,TYPE_NAME]
Destroying Types

Destroying types is only possible when there are no badges related to the type. In other words, before you destroy a type you must also destroy all badges that belong to it.

rake gioco:remove_type[TYPE_NAME]

Gioco Methods

Gioco will provide you with some methods that will be linked to your Resource Model (user for example.) Some new models will be generated, like Badges Model.

You will also have some badges and ranking methods. You can find everything you need about the Gioco methods at the Documentation

Behind the Scenes

Let’s do a brief dissection of Gioco and show exactly what kind of architecture is built on top of your application. When you setup Gioco, it generates models, templates, rake tasks, config files, seed files, and then it runs the migrations automatically. This is the architecture generated (setting User as the resource model in gioco full stack implementation):

Gioco Architecture

There will be 4 new generated models:

  • BadgeResponsible for badges data, such as it’s number of points and name.
  • LevelIt’s a transparent layer used by Gioco internal methods to manage the badges flow. It can also be used as a Levels system but it doesn’t have any methods to help you out with that yet.
  • PointIt stores the operations for points of each Resource, meaning subtractions and additions. It also stores the type of points that performed the operation.
  • TypeIt contains all the existing types, which are related to Points and Badges.

Future Plans

The objective is to make Gioco simpler, dynamic, and customizable every release. To achieve this, there are a lot of cool features that must be developed and your help would be great!

One of the features that I care the most about is an easy way to migrate implementations and architectures that already exist to Gioco. If you already have a gamification concept applied to your application and it’s getting too complex and harder to maintain, why not migrate to a more complete, OpenSource toolbox without losing any data? It would be amazing, right? It certainly is one of the challenges for the next version.


If you read this entire article you must have interest in gamification implementations, so consider using Gioco in your application. Also, why not help to make it better? All links that you will need are in this article. Contributors are always welcome!

João M. D. MouraJoão M. D. Moura
View Author

I’m a leader engineer and manager, currently living in São Paulo, Brazil. I'm an enthusiast technologist that love open source, a blog author in RubySource and my own blog, and also a speaker of some international and national conferences like TakeOff Conf in France, Ruby Italian Day in Italy, GURU, SevenMasters and others.

Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week
Loading form