Badges

Badges are symbols of accomplishment by volunteers or teams - for example, how much computing they've contributed. Badges are shown as icons on project web sites. In the future, they may also be shown in client GUIs and statistics sites.

BOINC provides a general mechanism for defining and assigning badges. You can create badges for whatever accomplishments you want - average credit, total credit, length of participation, number of message-board posts, etc.

The data associated with a badge includes:

• A name (used to identify the badge internally; not visible to users)
• The URL of an image file. Images are sized on display (currently 48 pixels high). Make them somewhat larger than this, e.g. 300x300 pixels. For flexibility, use a PNG with transparent background.
• A title - a phrase that explains the accomplishment for which the badge is granted.

Badges are granted (or removed) by a PHP script that you would typically run as a periodic task from your config.xml file.

The default badges

The BOINC server code supports badges for the top 1%, 5%, and 25% of recent average credit (RAC). They are represented by gold, silver, and bronze medal images, respectively, and are assigned to both users and teams.

The script that assigns these badges is here: http://boinc.berkeley.edu/gitweb/?p=boinc-v2.git;a=blob;f=html/ops/badge_assign.php

To enable these badges on your project's site, add the following to your config.xml file:

    <task>
      <cmd>run_in_ops ./badge_assign.php</cmd>
      <period>24 hours</period>
      <output>badge_assign.out</output>
    </task>

Writing a badge-assignment script

You can use the default badge-assignment script as a template for writing your own. The script uses the following utility functions, defined in html/inc/util_ops.inc:

get_badge($name, $title, $image_url)

Return a PHP object representing the badge with the given name, title, and image file URL. Badge descriptions are stored in the MySQL database; this function creates a DB record if it's not already there.

assign_badge($is_user, $item, $badge)

Assign the given badge to the given user or team; item is either a user ID or a team ID.

unassign_badges($is_user, $item, $badges, $k) 

Remove badges from a given user or team. $badges is a vector of badges to remove. Remove all except the $kth one; if $k is negative, remove them all.

Using these utility functions, the script works as follows:

• Use get_badge() to get the gold, silver, and bronze badge objects.
• get_percentiles(): compute the top 1, 5, and 25 percentile values of RAC.
• assign_badges(): loop over the set of all items (users or teams). This is done 1000 items at a time to limit memory usage.
• For each item, compare its RAC with the RAC percentiles, and determine which badge to assign (if any). Assign that badge, and unassign the others.

These steps are performed first for users, then for teams.

While you're developing your own badge assignment script, you can run it manually in your project's html/ops directory. Use the admin web interface (see below) to clean up badge records as needed. When you're done, arrange to run the script periodically by adding it as a task in config.xml (see above).

Managing badges

The administrate web interface has a page for administering badges, which lets you add and remove badges.