How to: Gamification setup - Gitification/gitification GitHub Wiki

This page shows the standard flow to get a new gamification engine setup. All curl query shown in the how-to are example (server URL are bogus). Refer to apiary documentation to see the actual JSON scheme used.

Create an application

The first and foremost step is to create an application. It represents the service you want to gamify. Require fields are:

• site service URL
• callback URL for the service
• admin contact email address

example

curl --include --header "Content-Type: application/json" \
     --request POST \
     --data-binary "{
	site: 'http://example.com',
	callback: 'http://example.com/callback',
	admin: '[email protected]'
     }" \
"https://gamification-engine.com/applications"

In response, you will receive your own application ID, API key ($API_KEY in following examples) and secret key, keep them to yourself!

Add users

In order to associate users with badges, achievements and so on, you first need to create the user entity. Required fields:

• login associated with the service
• firstname first name of the user
• lastname last name of the user
• email of the user

example

curl --include --header "Content-type: application/json" --header "Authorization: $API_KEY" \
     --request POST \
     --data-binary "{
	login: 'johnsnow',
	firstname: 'John',
	lastname: 'Snow',
	email: '[email protected]'
     }" \
"https://gamification-engine.com/applications/{appid}/users"

In response, you will get the user id.

Create badges

You must create badges in order to award the user for reaching a threshold. Badge are associated with an icon (preferably hosted on your server) and a name. Required fields:

• name of the badge
• icon, image file in jpeg or png format
• category_id to group badges together

example

curl --include --header "Content-Type: application/json" --header "Authorization: $API_KEY" \
     --request POST \
     --data-binary "{
	name: 'Night Watch',
	icon: 'http://example.com/images/badge_night.png',
	category_id: 1
     }" \
"https://gamification-engine.com/applications/{appid}/badges"

Create event types

Event are the atomic action done by users on your website. To categorize them, we use event type. An event type is a string used to match the event from your website to our engine. Required field:

• name of the event type

example

curl --include --header "Content-Type: application/json" --header "Authorization: $API_KEY" \
     --request POST \
     --data-binary "{
	name : 'got.nightwatch.kill'
     }" \
"https://gamification-engine.com/applications/{appid}/events/types"

Create rules

Rules are the entity linking badges and event types together. A rule will award a badge when all threshold of each event type associated are met. Required fields:

• name of the rule
• badge_id, badge awarded by the rule
• event_types, array with event_type_id and threshold

example

curl --include --header "Content-Type: application/json" --header "Authorization: $API_KEY" \
     --request POST \
     --data-binary "{
	name: 'got.nightwatch.recruit',
	badge_id: 6,
	event_types:
	[
		{
			event_type: 12,
			threshold: 15
		}
	]
     }" \
"https://gamification-engine.com/applications/{appid}/rules"

Next steps

You are all set to use our gamification engine! Now, once a user does an action on your service, generate an event and send it to us. Badges will be awarded immediately after receiving the right amount of event. Required fields:

• type of the event
• user associated with the event
• issued, when the event occurred on your service

example

curl --include --header "Content-Type: application/json" --header "Authorization: $API_KEY" \
     --request POST \
     --data-binary "{
	type: 12,
	user: 19221,
	issued: 1369590061
     }" \
"https://gamification-engine.com/applications/{appid}/events"