wiki:BadgeDoc

Version 1 (modified by davea, 10 years ago) (diff)

--

Badges

Badges are symbols of accomplishment by volunteers or teams - for example, how much computing they're 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 shown to users)
  • The URL of an image file. The image will be sized on display (currently 48 pixels high). Make it somewhat larger than this, e.g. 300x300 pixels. For flexibility, use a PNG with transparent background.
  • A title - a short 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

By default (for new projects) there are 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.

Writing a badge-assignment script

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

You can use this 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.