Badgeville RESTful Wrapper for Berlin API -- Basic README

This is an open source Ruby wrapper for interacting with the Badgeville RESTful Berlin API.

Features

Uses the activeresource (3.1.3) gem to map ActiveModel-like RESTful methods to resources on the remote Badgeville server.
Allows creating, reading (finding), updating and deleting the following classes of remote resources: Site, User, Player, ActivityDefinition, Activity, Reward and RewardDefinition.

Basic Examples

1. Configure the gem to use your Badgeville Private API Key and the site to which your requests should go.

        BadgevilleBerlin::Config.conf(
          :host_name => "http://example.com",
          :api_key   => MY_API_KEY)

:host_name should be the Badgeville endpoint that receives your calls, NOT your site URL. Example: "http://sandbox.v2.badgeville.com"

        new_site = BadgevilleBerlin::Site.new(
          :name       => "My Website",
          :url        => "mydomain.com",
          :network_id => MY_NETWORK_ID )
        success = new_site.save

3. Create a user on your network.

See the API Explorer for required and optional parameters.

        new_user = BadgevilleBerlin::User.new(
          :name       => 'visitor_username',
          :network_id => MY_NETWORK_ID,
          :email      => '[email protected]',
          :password   => 'visitor_password' )
        success = new_user.save

4. See error messages from the remote server.

Here we attempt to create a second user on the network with the same email as the first user.
See the API Explorer for required and optional parameters.

        new_user2 = BadgevilleBerlin::User.new(
          :name       => 'visitor_username',
          :network_id => MY_NETWORK_ID,
          :email      => '[email protected]',
          :password   => 'visitor_password' )
        success = new_user2.save

        puts new_user2.errors.messages # {:email=>["user email is already taken"]}
        puts new_user2.errors[:email]  # ["user email is already taken"]

5. Find a user to update user properties.

Here we find the newly created user by ID to update their email address.
See the API Explorer for a full list of user properties to update.

        user_found_by_id = BadgevilleBerlin::User.find( new_user.id )
        user_found_by_id.email = '[email protected]'
        success = user_found_by_id.save

        updated_user = BadgevilleBerlin::User.find( new_user.id )
        puts updated_user.email # [email protected]

6. Create a player.

Here we create a player for the new site, corresponding to the user with the updated email address.
See the API Explorer for required and optional parameters.

        new_player = BadgevilleBerlin::Player.new(
          :site_id => new_site.id,
          :user_id => user_found_by_id.id )
        success = new_player.save

7. Find existing players by email.

Here we find an existing player by email.
To get all players on the network that match the email, we have passed :all.
You can alternatively pass :first or :last in the place of :all.

        @existing_player = Player.find(:all, :params => {:email => "[email protected]"})

8. Register a player behavior.

Here we record the fact that the newly created player performed a "share" behavior.
See the API Explorer for required and optional parameters.

        new_activity = BadgevilleBerlin::Activity.new(
          :verb      => 'share',
          :player_id => new_player.id )
        success = new_activity.save

Monitoring HTTP Requests and JSON Responses

Print HTTP requests and JSON responses by installing the "logger" gem and including this code in your script.

        require 'logger'
        BadgevilleBerlin::BaseResource.logger       = Logger.new(STDOUT)
        BadgevilleBerlin::BaseResource.logger.level = Logger::DEBUG

Dependencies

activeresource (3.1.3) - Provides Ruby classes to RESTfully interact with remote resources.

Installation

gem install badgeville_berlin

Documentation

For more documentation on how the Badgeville RESTful Berlin API works, see here.

Submitting an Issue

You can use the GitHub issue tracker to report bugs. After ensuring that the bug has not already been submitted, please submit:

A gist a that contains a stack trace.
Details needed to reproduce the bug, including gem version, Ruby version and operating system.

Submitting a Pull Request

Click the GitHub "Fork" button to fork this project.

Clone the repository for a local copy:

git clone git@github.com:username/badgeville-ruby.git

Create a topic branch:

git checkout -b my_bug_fix_or_feature_branch

Add documentation and specs for your bug fix or feature.
Implement your bug fix or feature.
Run the following command to ensure your tests cover your changes:
```
bundle exec rake spec
```
Commit and push your changes.
Click the GitHub "Pull Request" to submit a pull request. Please do not include changes to the gemspec, version or history file.

-## Contributors -David Czarnecki wrote the initial gem that inspired this wrapper.