Welcome to the Badge Center

The Badge Center is an iOS SDK (Android coming soon) that allows you to easily incorporate "badges" in to your applications. Popularized by foursquare, farmville, and others, badges are powerful ways to encourage desired user behaviors in your app by turning your app itself into a "game". This software is licensed under the Apache license, version 2.0.

Key benefits of the SDK include:

Centralized location to define all badge related logic, including earning criteria, images, and text, for non-programmers.
Simple API call for the app to report user activities for earning badges.
Automatically keep track and manage the user's badge status.
Notifying the hosting app badge status changes (e.g., earning a new badge).
Ready-to-use and easy-to-extend view controllers to display and interact with badges.
Built-in support for sharing badges.
Ready-to-use library of badge images.

badges badge actions

Getting Started

Drag the libBadgeKit.a file into the Frameworks section of your XCode project. And make sure that it is included in your product targets.

Drag BadgeKit.h header file into the source section of your XCode project.

Create a BCBadgeDefinition.plist file to define all badge images, text, and award criteria. An example of this file is given in the next section. For now, just remember that each badge has a "metric" property associated with it. Once the metric property reaches certain value, a new level of the badge will be awarded to the user. For instance, the metric officialuser might refer to the number of times the user opens the app. The user could get an "silver level official user" badge once it reaches 5.

Initialize the BCBadgeManager object in your application delegate.

- (BOOL)application:(UIApplication *)application 
              didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    self.manager = [[BCBadgeManager alloc] init];
    ... ...
}

Throughout your application, you can make a simple API call to report activities tracked by badges. The badges are represented here by its metric name.

[[BCBadgeManager sharedManager] incrementMetric:@"officialuser" by:1];

Display the badges in a built-in view controller. You can get the view controller as follows, and then you can present it from your current view controller.

UIViewController* badgeView = [[BCBadgeManager sharedManager] badgeViewController];    
[self presentModalViewController:badgeView animated:YES];

Define your badges

Here is an example of BCBadgeDefinition.plist file. It defines two badges.

The officialuser badge is tracked by the officialuser metric. When the metric has value between 0 to 4, the image officialuser-1.png is display for the badge; when the metric value is from 5 to 24, the officialuser-2.png is display for the badge; etc. The messages correspond to the messages to display when the user taps on the badge or shares the badge.
The 7daystretch badge is tracked by the daysused metric. When the metric has value between 0 to 6, the image 7daystretch-1.png is display for the badge; when the metric value is from 7 to 13, the 7daystretch-2.png is display for the badge; etc. The messages correspond to the messages to display when the user taps on the badge or shares the badge.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>metrics</key>
  <array>
    <string>officialuser</string>
    <string>daysused</string>
  </array>

  <key>badges</key>
  <array>
    <dict>
      <key>levels</key>
      <array>
        <integer>0</integer>
        <integer>5</integer>
        <integer>25</integer>
        <integer>50</integer>
      </array>
      <key>messages</key>
      <array>
        <string>Please open the app at least 5 times to earn this badge!</string>
        <string>a silver level badge for Official User!</string>
        <string>a gold level badge for Official User!</string>
        <string>a diamond level badge for Official User!</string>
      </array>
      <key>id</key>
      <string>officialuser</string>
      <key>name</key>
      <string>Official User</string>
      <key>metric</key>
      <string>officialuser</string>
    </dict>

    <dict>
      <key>levels</key>
      <array>
        <integer>0</integer>
        <integer>7</integer>
        <integer>14</integer>
        <integer>21</integer>
      </array>
      <key>messages</key>
      <array>
        <string>Please use the app at least once a day for 7 days in a row to earn this badge.</string>
        <string>a badge for using the app 7 days in a row!</string>
        <string>a badge for using the app 14 days in a row!</string>
        <string>a badge for using the app 21 days in a row!</string>
      </array>
      <key>id</key>
      <string>7daystretch</string>
      <key>name</key>
      <string>7 Day Stretch</string>
      <key>metric</key>
      <string>daysused</string>
    </dict>
  </array>

  <key>background</key>
  <string>metal-2.jpg</string>
</dict>
</plist>

Receive notifications

The SDK emits two notifications for the hosting app to process.

The kBCNotificationMetricChanged is sent whenever a badge metric is changed. The userInfo of this notification contains the metric name and value.

-(void) metricChanged:(NSNotification*) notification {
    NSDictionary* info = [notification userInfo];
    NSString* metricName = [info objectForKey:@"metric"];
    NSNumber* value      = [info objectForKey:@"value"];

    ... ...
}

The kBCNotificationLevelUp is sent whenever a new badge level is reached. The userInfo of the notification contains the badge itself.

-(void) levelUp:(NSNotification*) notification{
    NSDictionary* info = [notification userInfo];    
    BCBadge* badge = [info objectForKey:@"badge"];
    ... ...
}