Manybots API - Getting started with Ruby on Rails 3.1, Devise and Omniauth

In this guide, we'll walk you through the creation of a Rails app that can authenticate a user using OAuth, post an activity and display an activity using Manybots. You should be done in 15 minutes.

The first step is to register your application with Manybots. This simple process is free and is required to obtain the OAuth credentials your app will use to authenticate the users.

Then, we'll get into the code and build your first Manybots application step by step.

Step 1 - Register your application

Go to the App Registration page and fill out the form taking note of the following:

  • You can use "http://localhost:3000" as your app's url while in development.
  • Don't check the box that requests to make your application public just yet :)

After you hit Register, you'll be taken to the app management page, where you'll see a preview of how the app shows up in the listings and the OAuth details.

Leave this page open in a tab somewhere, we'll come back to it for some copy-pasting action. You can proceed to step 2.

Step 2 - Setup the Rails application

As we said, your application will be able to authenticate a user on Manybots using OAuth- for that, we'll use Omniauth with Devise, a great combination for your app as they're a collection of Warden strategies and helpers. They're also easy to use.

The app functionality will be pretty basic: login, post an activity, display the activity returned by Manybots.

2.1 - Creating the app and setting up the gems

Let's start with the creation of rails project. From now on, we'll assume that you have Ruby on Rails 3.1.0 or above installed and ready to run.

rails new manybots_app


cd manybots_app
rm public/index.html

Now you should have created the Rails app and entered its directory. Now we'll proceed to installing and configuring Devise and your User model

Edit your Gemfile to include the following gems:

gem 'devise'
gem 'omniauth', '>= 1.0.0'
gem 'omniauth-manybots', :git =>'https://github.com/NikoRoberts/omniauth-manybots.git'

Then run bundle install to install them

bundle install

And now run the Devise generators

rails g devise:install
rails g devise User

2.2 Configuring Devise

We've just told rails to generate the devise install and to configure the basics for authenticating the User model. We're going to heavily edit Devise's default configuration to make your application Manybots only.

If you want to add Manybots authentication to an existing Devise install, you should just consider Manybots as another Omniauth provider.

Devise created a migration file, which you can edit to resemble the following:

Once you've saved your changes to the migration file, run it:

bundle exec rake db:migrate

Now that the User model is created and the database is ready, we're going to dive into the application.

Step 3 - The authentication flow

So, we want a user to come to the app and, if she's not logged in, ask her to login with Manybots. When she clicks the link to login with Manybots, we'll do the OAuth dance. Once the dance is finished, we'll log her in and greet her.

We'll need a login page, the controller to handle the OAuth dance, an authentication method for the user, and a page to redirect them to. And routes to handle it all.

Let's start with the OAuth dance. We'll stick as close as we can to standard Omniauth, so it should be easy for you to spot the differences between this Manybots centric implementation and a multi-provider usage.

Create a Controller to handle the OAuth callback. We'll also use it to write our own login/logout actions.

rails g controller users/omniauth_callbacks

Then, make it look like this:

Now, create let's create the view that will ask the user to login with Manybots

Where is this headed? Well, we need the routes. But we also need the page where our user will be redirected after login. Let's create a Dashboard controller, and we'll make everything happen within it.

rails g controller Dashboard

Now, let's add an index view to it

This implies that we'll use Devise's helpers to access the current user, and that we'll be creating an action that will handle posting the activity to Manybots.

So let's set up the routes for all this.

Then let's edit the Dashboard controller to look like this

Note how we use methods on the current_user object and use the Manybots module to create the Feed::Item.new_test_activity. We'll add the code to make that possible right now.

We start with the User model in models/user.rb

Note how we handle the authentication with OmniAuth and the fields we created with the Devise migration. Also note how we comment most of devise configuration and only use :omniauthable. Finally, note that we include Manybots::User.

To wrap up, you'll need to add the Manybots Rails initializer, which is a mix of configuration and helpers.

Step 4 - The Manybots Rails initializer

There's no Manybots gem for the moment, so bear with us as this is not the prettiest thing you'll see.

It works pretty well however and provides a simple one-stop configuration of Manybots OAuth and API helpers.

Simply paste this into an initializer file (it's rather long, here's a direct link to the raw version)


Now go back to your App's management page on the Manybots website and copy-paste your OAuth credentials into that file, at the appropriate place at the top.

You're done

rails server

Go to http://localhost:3000. Your app should be up and running, and should be able to login to Manybots and post a test activity.

Take a look at the code, it should have everything you need to integrate these same tools with your own ideas.

Getting help

The manybots-dev mailing list is the best place to get help, discuss API development and exchange feedback and ideas among developers and the Manybots team. Go to manybots-dev mailing list

Google Groups
Subscribe to manybots-dev
Go to group

Doing more

A tutorial on how to read activities is coming soon. You can take a look at the other resources available in the developers page.