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"

2. Add a new site to your network. Find your network ID the Publisher Module's tabbed menu ( Develop > Home ) or contact support@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      => 'visitor@emailserver.com',
          :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      => 'visitor@emailserver.com',
          :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.

```ruby user_found_by_id = BadgevilleBerlin::User.find( new_user.id ) user_found_by_id.email = 'revised_visitor@emailserver.com' success = user_found_by_id.save

    updated_user = BadgevilleBerlin::User.find( new_user.id )
    puts updated_user.email # revised_visitor@emailserver.com


### 6. Create a player.
<ul>
  <li>Here we create a player for the new site, corresponding to the user with the updated email address.</li>
  <li>See the API Explorer for required and optional parameters.</li>
</ul>
```ruby
        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.

``` ruby @existing_player = Player.find(:all, :params => {:email => "revised_visitor@emailserver.com"}) ```

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.

```ruby 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] (http://rules.badgeville.com/display/doc/2.0+Core+API+Documentation).

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.

badgeville_berlin

Development

Runtime