In my case, I worked on a donation system on Facebook which is kind of like the Causes Facebook app except that each cause gets its own Facebook app. The Facebook apps are created on the fly from the web admin interface by cause administrators and all the apps point to the same server.

The problem is that Facebooker does not allow serving multiple Facebook applications dynamically. I had to monkey patch it in order to make it work. In my config/initializers folder, I created a new file named facebooker.rb with the following code :

require 'facebooker'

module Facebooker
  class << self  
    def fetch_config_for(api_key)
      cause = Cause.find_by_api_key(api_key)
      if cause
        cause.attributes.merge("callback_url" => Settings.facebook.callback_url)
      else
        false
      end
    end
  end
end

The fetch_config_for method is called on each request to bind the request to a facebook application configuration. The original method looks for the config in facebooker.yml. This methods overrides that to use a database lookup instead. In the Cause model, I have fields named canvas_page_name, api_key and secret_key. The callback_url is the same for all the apps but it will change depending on the environment. I use the settingslogic plugin to handle that.

Don’t forget to leave a dummy facebooker.yml file in the config folder since it’s loaded when the Facebooker plugins initializes.

1- Setup a local_env.rb file

Create a local_env.rb file in which you will put all your environment variables. This works great with Heroku. This technique is better explained in the article Managing Heroku environment variables for local development. The local_env.rb file is not checked in your version control. It remains on your local development machine and it’s loaded by your environment.rb file. I declare my Tunnlr and Facebook configuration keys this way :

# config/local_env.rb
ENV['FACEBOOK_API_KEY']            = '1cv10ddbd7c4374e70996071343c9ed5'
ENV['FACEBOOK_SECRET_KEY']         = '39c4c4c060a5fd8335a21e22bdb2w26c6'
ENV['FACEBOOK_CALLBACK_URL']       = 'http://web1.tunnlr.com:10521'
ENV['FACEBOOK_CANVAS_PAGE_NAME']   = 'my-facebook-app'

ENV['TUNNLR_PUBLIC_HOST_USERNAME'] = 'tunnlr917'
ENV['TUNNLR_PUBLIC_HOST']          = 'ssh1.tunnlr.com'
ENV['TUNNLR_PUBLIC_PORT']          = '10521'
ENV['TUNNLR_LOCAL_PORT']           = '3000'

# config/environment.rb
# Load heroku vars from local file
# credits: http://tammersaleh.com/posts/managing-heroku-environment-variables-for-local-development
local_env = File.join(RAILS_ROOT, 'config', 'local_env.rb')
load(local_env) if File.exists?(local_env)

Replace those values with your Facebook application keys and tunnlr keys. Each developer is going to need it’s own Facebook App and it’s own Tunnlr account.

2- Put the variables in facebooker.yml

Facebooker.yml is where “facebooker”: fetch its configurations. Reading the Facebooker source code, I realized the file is first parsed in ERB, which lets you put variables in your YAML file. We can put the variables we declared in step 1 :

development: &development
  api_key: <%= ENV['FACEBOOK_API_KEY'] %>
  secret_key: <%= ENV['FACEBOOK_SECRET_KEY'] %>
  callback_url: <%= ENV['FACEBOOK_CALLBACK_URL'] %>
  canvas_page_name: <%= ENV['FACEBOOK_CANVAS_PAGE_NAME'] %>
  pretty_errors: true
  tunnel:
    public_host_username: <%= ENV['TUNNLR_PUBLIC_HOST_USERNAME'] %>
    public_host: <%= ENV['TUNNLR_PUBLIC_HOST'] %>
    public_port: <%= ENV['TUNNLR_PUBLIC_PORT'] %>
    local_port: <%= ENV['TUNNLR_LOCAL_PORT'] %>

test:
  <<: *development

3- That’s it!

Each developer now has its own configuration for Facebook and Tunnlr and the keys are stored in local_env.rb. This file is not checked in git. This way, all the developers can then share the same facebooker.yml file.

See my other article on speeding up Tunnlr for more tips on developping Facebook applications.

1. Prepare the map in your model

In your Geolocation model, start by adding this snippet of code which will initialize your map.

def map
  @map ||= prepare_map
end

def mapped?
  latitude && longitude
end

def coordinates
  [latitude, longitude]
end

private

def prepare_map
  return unless mapped?
  returning GMap.new("gmap") do |map| 
    map.control_init(:large_map => true, :map_type => true)
    map.center_zoom_init(coordinates, 15) # Set the center and zoo level
    map.overlay_init(GMarker.new(coordinates))
  end
end

The important method here is prepare_map. What it does is create a new map centered at the given coordinates. The overlay_init method sets a marker at the coordinates position. This is a basic vanilla map initialization. You might want to read the YM4R api for more options like adding an info window or multiple markers.

2. Call it from your controller

In our controller, we will set the @map variable to make it accessible in our view :

@map = customer.geolocation.map

3. Display the map in your view

You will need this snippet of code in the header section of your document to do the proper javascript imports and initializations :

= GMap.header
= @map.to_html

And in the body of your view, where you want to display the map, simply add :

@map.div(:width => 600, :height => 400)

This last line will generate a div with the id “gmap” (or whatever name you set in the GMap.new function). I find it’s cleaner to just set the width an height through CSS.

4. Adding complexity

This technique will only work if you display only one map on the page. The map needs to be visible on page load to be properly displayed. But what if there is multiple maps you want to display on the same page? And what if you want to show them in overlay popups? You probably don’t want to initialize them all on page load since it will freeze the client browser. This will require some javscript hacking. I will show you how to do that next week!

1. The user enters an address and you need to validate it and geoposition it (latitude & longitude) on a map.
2. You need to display the google map for that given address on a webpage.

Today, I will show you how I did the first step using the YM4R/GM plugin.

1- Setup the plugin and get you Google Maps key

First thing to do is to install the YM4R/GM plugin plugin. There is also a gem but it seems to be a stripped-down version of the plugin. I couldn’t get it working so I would advise to use the plugin :

script/plugin install svn://rubyforge.org/var/svn/ym4r/Plugins/GM/trunk/ym4r_gm

The plugin creates a file in your config folder named gmaps_api_key.xml. You need to enter your Google Maps API keys for the different environments. You can get the keys here.

2- Create the model

Next thing to do is to create your Geolocation activerecord model. You need to at least have those four attributes :

create_table "geolocations", :force => true do |t|
  t.string   "address"
  t.string   "city"
  t.float    "latitude"
  t.float    "longitude"
end

You might also want to add the country and postal code to the mix. But in most case, Google Maps will be able to return you a location with just a street address and a city.

3- Set the geolocation on the before_save

When you create a new gelocation record, you want to geoposition it. Here’s my code in the Geolocation.rb model :

before_save :set_geolocation

def set_geolocation
  if changes['address'] || changes['city'] || !mapped?
    results = Geocoding::get(complete_address)
    if results.status == Geocoding::GEO_SUCCESS
      self.latitude, self.longitude = results[0].latlon
    else  
      self.latitude, self.longitude = nil
    end
  end
end

def complete_address
  [address, city].select(&:present?).join(', ')
end

def mapped?
  latitude && longitude
end

What this does is set the latitude and longitude for the given address on the before_save callback. We first check if the address or the city changed and if so we try to get a geocoding. If the API responds with SUCCESS, we set the latitude and longitude with the first result. If the API failed to return a valid address, we set the latitude and longitude to nil. We can check if the address was mapped using the mapped? method.

4- Wrap it up

Geopositionning the address is only the first part of the problem. Next week I’ll show you how to use the latitude and longitude information we stored to display Google maps in your webpages.

Next week : How to display a google map for a geopositioned address

On some rare occasion, I stumble on a job listing site that has no support for RSS feed. This is the case for the Working With Rails job board. Apparently I’m not the only one complaining about the lack of a RSS feed for the job board.

I did some Google searches and found Feed43, a nice little web app that lets you build a RSS feed for any pages on the web. It’s free, intuitive and fairly easy to build your own RSS feed if you’re a little tech savvy. If you’re also looking for Rails gigs, feel free to use my generated WWR job board feed!

When I developed SalsaJungle.com, I was sometimes confusing my development and production websites. I know it doesn’t sound too clever but there are times when I reloaded a page after a fix only to realize that I was looking at the production site. That’s what happen when you multitask between development and client support.

Notice the last two tabs which are running the same application on two different environments

Well I took the matter in hands and simply created a second favicon with a different background color for my development environment. I named it favicon_dev.ico and put it in the same directory as the favicon.ico. Then I added this little snippet of haml code to my application.html.haml template :

- if RAILS_ENV == 'development'
  %link{ :rel => "shortcut icon", :href => "/favicon_dev.ico" }

With this code, I force the path of the favicon to favicon_dev.ico in the development environment.

Et voila! Now I know at a glance that blue is for development and red for production!

This fourth and last article about Facebook Connect gives you a few tricks to gain a viral effect with your application on Facebook. This is basically done by getting friends of your users to notice your application.

1- Post updates on your users walls

Using the Stream.publish function, you can post news on your users walls that will appear on their friends newsfeeds. There are different ways to do this and it requires some extra permissions from you users if you wish to auto-publish without users approval each time. Personally, I prefer to let my users decide whether they want the application to publish on their feed and they can personalize the content of the message :

The dialog asking to publish on your wall

2- Add the friends invitation widget

The invitation widget lets your users invite friends to try your application. I used this code to get it done. Unfortunately, the restriction on how many friends you can invite per day is rather draconian.

Friends invitation dialog

3- Add the Fanbox widget

This widget is a simple snippet of code that adds a Fanbox to your page. When a Facebook user become fan of you application, it’s displayed in his friends newsfeed highlights (column on the right).

SalsaJungle.com Fanbox

4- Use Facebook comments system

Another very interesting widget that you can configure in a minute is the comment box. You get the basic comment thread (Facebook style) and the user can choose to publish his comment on his profile. And this equals more visibility for your app.

The Facebook comment box

5- Optimize the Facebook links to your site

When a Facebook user posts a link to your site in a status update or in a message to a friend, you want it to get noticed. Facebook automatically checks for images on your website to display with the link. It also figures out a description by parsing the text on page.

But instead of relying on luck, you should control all of this by using the description meta-tag and the link tag in your HTML header. You tell exactly Facebook which image and description to use when a link is made to a page of your site :

<meta name="description" content="My application description" />
<link rel ="image_src" href="http://montreal.salsajungle.com/images/logo_for_fb.gif">

Note that the image_src href has to be absolute in order to work.

That’s it! Your site should now get all the attention it deserves. Let me know in the comments if you have other ways to promote your Facebook Connect website.

In my Facebook Connnect salsa network application, I have a cron task that runs each night to create new Facebook events associated with clubs. So for example, if there is a salsa night every Tuesday at Moe’s bar, the related Facebook event will be created 7 days in advance on behalf of the administrator of the bar. But in order to create the events on behalf of a Facebook user that doesn’t have an active session on the site, there is a few steps to follow.

1- Request the offline_access extended permission

Some of the Facebook API functionalities require you to get permission from the user first. In this case, we need the offline_permission to access user’s data.

<div id="grant-permissions">
  <fb:prompt-permission perms="offline_access" next_fbjs="$('#grant-permissions').hide()">
    Click here to grant offline access!
  </fb:prompt-permission>
</div>

The previous line can be inserted in your view. The XFBL code creates a link to a popup prompt asking the user for offline access permission. The next_fbjs attribute is a javascript callback function that executes once the user has granted or refused the permission. In this case, we just hide the div using a jQuery function.

2- Store the user’s infinite session key

If the user has granted the offline_access permission, each request will now contain an infinite session key. We need to store this information somewhere in the DB if it’s not already there. In this case, I added a session_key attribute to my User model.

# This goes in your application_controller.rb
before_filter :set_fb_session_key
def set_fb_session_key
  if logged_in? && facebook_session.infinite? && !current_user.fb_session_key
    current_user.update_attribute(:fb_session_key, facebook_session.session_key)
  end
end

You will notice that the keys have this format <random hexadecimal key>-<facebook user_id>

3- Use the session key to access user’s data

Finally, you will be able to access your user’s datas through the Facebooker API by initalizing the session with the user’s session key this way:

facebook_session = Facebooker::Session.create
facebook_session.secure_with!(user.fb_session_key)

That’s it! You can now use the user’s data as you wish!

When developing a Facebook or Facebook Connect application, there are times when Facebook servers will need to directly make requests to your application. This means your local web server has to be remotely accessible for incoming requests.

Typically, when working locally, your mongrel or webrick instance running on port 3000 is not accessible unless you enable port forwarding on your router. And even then, your ISP probably doesn’t assign you a fixed IP address which means you have to run a dynamic IP address service like dyndns. This quickly gets complicated and if you work behind a corporate network or develop from different locations (ex.: home, office, Starbucks…), this solution won’t even work.

Meet Tunnlr, an easy to use service that makes your local Rails server accessible from the Internet by just typing a single rake command in your console. When you register to the service, you will be assigned a fixed URL address with a port number and this is the address you will use to configure your Facebook application and access it locally.

One downside to that approach is that since each request has to do a return trip to the Tunnlr servers, you loose the lightning speed loading time you’re used to when developing from your local machine (no network latency). I found a little hack that will bypass the need to do a return trip and it can be done in three easy steps

1- Modify your /etc/hosts file and add the following line :

127.0.0.1	web1.tunnlr.com

This tells your machine to route all requests made to the web1.tunnlr.com address to your local machine. Unfortunately, there is no way to specify port redirections in the hosts file so we need step 2 and 3 to make sure our remote and local ports are the same.

2- Modify your tunnlr.yml or facebooker.yml file to make your local port the same as your remote port. In my case, this is port 10524.

remote_port: 10524
local_port: 10524

3- Start your Rails server with the same port that has been assigned to you by Tunnlr.

script/server -p 10524

That’s it! Now when you query web1.tunnlr.com your local requests will stay local and your server will still be remotely accessible from the tubes!

Over the course of the week, I will write one post a day about the following technical topics :

1. Today: 5 strategies when developing with Facebook Connect
2. Wednesday: Speeding up Tunnlr
3. Thursday: Working with offline user’s data access
4. Friday: Viral Facebook Connect application tips

Stay tuned if you’re planning on developing a Facebook application or are curious about this new platform. So let’s start with today’s topic, 5 questions to ask yourself before you kick off your project:

1- What will my interactions with the Facebook platform be? Are there API limitations?

If there was only one advice I could give you, it would be to read the Facebook API first. Your application will be limited in terms of what data it can access and how the data can be used. Knowing those limitations and how to get around them is essential.

As an example, I took for granted that I would be able to rsvp to events on Facebook on behalf of users. Turns out that when I carefully read the events API, rsvps would only work on events your application created. Now that was a real bummer that I could have managed earlier if I had read the API more carefully.

2- What will my authentication strategy be?

Facebook Connect provides a way to authenticate users on your website. But should you rely entirely on Connect or should you provide an hybrid registration process that lets the user choose whether they prefer to create a new account for your site or use their Facebook account?

My application relies heavily on Facebook Connect so I decided not to provide other means of logging on to the site. Turns out this was maybe not such a great idea since a lot of people still don’t know about Facebook Connect and are concerned with phishing scams when entering their Facebook credentials to log on to my site.

3- Which wrapper should I use?

The wrapper is the link between your programming language and the Facebook REST api. In the Rails world, Facebooker is the obvious choice. The gem is stable and great developers are working on adding new features and fixes each week. But still, the Facebook API changes quickly and you might find yourself wanting to use features that haven’t made their way to the gem yet.

In that case, I woud recommend forking the project on GitHub and using it as a git submodule plugin in your application. This way you can add the missing features yourself and ask for a pull request once its done and tested.

4- Facebook application or Facebook Connect?

While Facebook Connect is new on the scene, Facebook applications have been around for a few years now and Facebook user are used to them. But I somehow feel the golden age of Facebook applications is behind. Users got fed up with all the noise and newsfeed clogging from those applications and Facebook responded by moving them away in separate tabs. As a result, it has got a lot more difficult for an application to get noticed and go viral.

Facebook connect will give you a lot more freedom and independence, letting you use the Facebook platform without being trapped in it.

5- How will it go viral?

Viral marketing is still one of the best argument as to why you should not neglect Facebook in your marketing strategy. You need to make the best use of your users newsfeed so that your application gets noticed by a maximum of potential users.

Making your application go viral will be Friday’s subject.

What do you think of these tips? Do they make sense to you? Do you have a few others?