Facebook APIs got you down? Try the following step-by-step guide to an awesome fan page
===================================
Hopefully you weren't beating your head against the FB APIs too long before you turned to a Google search. The following is a soup-to-nuts guide for creating a Facebook fan page with content customized for fans vs. non-fans (i.e. visitors pre- and post-like).
A little background: we had a fan page on FB that wasn't really doing anything for us, an idea for content that might be useful to people -- and a design to make things pretty. We wanted 1) visitors to see a custom tab, not just the wall, 2) our fans to get some useful info for liking us, and 3) to be able to poll our fans for answers to insurance-related questions.
Now that we have the basic requirements, what's stopping us? Well, first [what's a custom tab](#the_nuts) and [how do we populate it with content?](#tab_content) Then, [how do we know when a user likes our page?](#user_likes) Last, [how do we get the Facebook userID](#userID) from the tab so we can track unique votes on our polls?
Prereqs.
-------
1. [A Facebook account](#prereq_1)
2. [A fan page of some kind](#prereq_2)
3. [Developer access](#prereq_3)
If you've already got a handle on these, skip the soup and go straight to [the nuts](#the_nuts). =]
Odds are you already have one of these, but I said soup-to-nuts dammit, and I didn't want all these likes, unlikes, pages and apps getting posted to my real profile while I was writing this, so here's an overview.
Go to www.facebook.com and fill out the Sign Up form on the right hand side.
Click the Sign Up button and answer the security CAPTCHA.
You can skip the next two or three steps and go directly to confirming your account's email.
We don't need to add friends, this will be a dev account.
Again, we don't really care, this account is for dev/test purposes
I like to add a profile photo so I can tell my accounts apart at a glance.
If you haven't already, go to your email and confirm the account you signed up with. Click the link or the Complete Sign-up button.
E voila...
Because, well, everyone wants to be liked, even companies. =]
Pick a page type, I'm going with "Company, Organization, or Institution."
Choose a category, fill in the Company Name and agree to the Facebook Pages Terms before clicking the Get Started button.
Fill in the CAPTCHA answers to prove you're human.
Add a profile photo for the company
Go ahead and skip this step, we're not ready for actual fans yet.
Add a description to the about blurb, this will show up in the fan page beneath the available tabs. It get's truncated, so keep it short and sweet.
Bada-bing-bang-boom!
This will give you access to the apps section of the facebook developers portal.
Click on the Developers link in the footer navigation.
or go directly to http://developers.facebook.com and click Apps
Click Allow to add the developer app to your profile.
And there you are, a full fledged Facebook developer. Wouldn't your mom be proud?
### Ans: It's just a Facebook app that lives in the left nav of your fan page. ##
Wait, really? Yup, that's it, let's see what it takes.
### Create a Facebook Page Tab App ##
Click the Create New App button at the top of the Apps section.
Fill in a name and accept the Terms before clicking the Continue button.
WTF? Srsly? OK, so if you see something like the following error,
Just go to Account -> Account Settings -> mobile and run through that whole rigamarole. I don't feel like screen-capping it. =P
Now that your account is 'verified', clicking Continue in the dialog will take you to the Settings -> Basic page for your new app.
Now let's make it a Page Tab. Click the Page Tab section at the bottom of the Basic settings and fill in Page Tab Name, Page Tab URL and Secure Page Tab URL. You can also edit the logo and icon for the App/Tab on this page.
After you click Save Changes, you'll get a nice little confirmation at the top of the section.
I made Facebook App that works as a Page Tab, now what?
### Add the Page Tab to your Fan page ##
Click View App Profile Page
Click Add to My Page
A lightboxed dialog pops up with a list of Pages that you have admin access to. Click Add to Page for the fan page you created earlier.
Close the dialog and go to your fan page. You can get there by searching for the company name or by going to you profile and clicking the page name in the Pages section.
Sweet! Now we have a Fan page with a custom tab. What's in there?
Oh, snap!
#### 1. Create the app
[keith : demos]$ rails new facebook_app && cd facebook_app
create
create README
create Rakefile
...
create vendor/plugins/.gitkeep
[keith : facebook_app]$ rails g controller facebook index
create app/controllers/facebook_controller.rb
route get "facebook/index"
invoke erb
create app/views/facebook
create app/views/facebook/index.html.erb
invoke test_unit
create test/functional/facebook_controller_test.rb
invoke helper
create app/helpers/facebook_helper.rb
invoke test_unit
create test/unit/helpers/facebook_helper_test.rb
#### 2. Set up the routes
[keith : facebook_app]$ vim config/routes.rb && head config/routes.rb
FacebookApp::Application.routes.draw do
match "facebook" => 'facebook#index'
...
#### 3. Start the server
[keith : facebook_app]$ rails s
=> Booting WEBrick
=> Rails 3.0.10 application starting in development on http://0.0.0.0:3000
=> Call with -d to detach
=> Ctrl-C to shutdown server
[2011-08-29 11:52:38] INFO WEBrick 1.3.1
[2011-08-29 11:52:38] INFO ruby 1.9.2 (2011-02-18) [x86_64-darwin10.7.0]
[2011-08-29 11:52:38] INFO WEBrick::HTTPServer#start: pid=65128 port=3000
Now refresh the Page Tab. Aaaand...
Now that we have a fan page, and a page tab pulling content from outside Facebook, let's change the default landing for our visitors. From the Get Started tab of the page click Edit Page.
This will take you to the Manage Permissions panel for your fan page. Change the Default Landing Tab to your Page Tab App
Then you'll want to Save Changes.
To see what your visitors will see, you'll have to log out of Facebook (or open a private browsing session) and go to the fan page you created.
Why did we have to log out first? Well according to [these guys](http://www.socialappshq.com/help/change-default-landing-page-for-facebook-page)
1. Only visitors who are non-fans and non-admins will land on it. Once a user “likes” your page, the page will reload and show them the “fans-only” content (if you’re using a landing tabs application like SocialAppsHQ.)HOWEVER, when a user who was already a fan visits the page, they will always default to the wall.
2. Similarly, page admins will always land on the Wall, whether they “liked” their own page or not. (Unfortunately, these are set by Facebook, and not something anyone can change.)
Sit back, relax a little, pat yourself on the back, you just got through the easy part. Yes, all of the preceding was just to get you to a point where you could start mucking around in the SDKs, now let's handle the sexy bits.
### Ans: Parse the signed_request param for the value of parsed_data['page']['liked'] ##
First you need to know about Facebook's signed_request param and what's in it. Whenever Facebook loads your application as a Page Tab it sends a signed_request param to your server. This will let you do things like, verify the request came from Facebook, figure out which page the request came from, and retrieve some basic user info. Note, fb only sends signed_request on the initial load of your app, clicks inside the iframe will not make this available to you.
The [signed_request](https://developers.facebook.com/docs/authentication/signed_request/) consists of an encrypted signature, followed by a dot ('.') followed by a base64url encoded JSON object. The thing to look out for here is the 'url' part of base64url encoding. Basically it strips padding and replaces + and / with - and _ respectively, check out the [wikipedia entry](http://en.wikipedia.org/wiki/Base64#URL_applications) for more details.
All set with signed_request? Good let's move on... oh wait, you probably want to know how to parse the signed_request. Well since this is just a demo I'm gonna show you the quick and dirty way to roll your own parser with Ruby. Libraries are for chumps.
### Set up the like-gate ##
Edit facebook_helper.rb and facebook/index.html.erb to look something like
Now our Page Tab will have the following content
And after adding a helper to parse the signed_request param, we can make user_likes_page? return a meaningful truthiness.
Once they like the Page, fans will see
### Ans: Use the Facebook JavaScript SDK to grab the userID from the response. ##
This was by far the most error prone, face-palming, bastardly part of the project. Let's jump right in!
#### Prep for using the JavaScript SDK ##
First we'll add a channel_url route and action per the SDK [best practices](https://developers.facebook.com/docs/reference/javascript/FB.init/)
Edit your routes.rb file and add the following below your original route
`match "facebook/channel.html" => 'facebook#channel', :as => :facebook_channel `
Then add a channel action to the facebook controller, something like
Good, now add the .js lib and the FB.init block to your application layout, along with a fbml login tag.
You'll also need to set the FACEBOOK_APP_ID to the App ID/API Key from your App summary in the Facebook developer portal in some environment.
With any luck, the Page tab should show...
Let's dig down and see if we can figure out what's going on. From the JavaScript console of your browser call the `FB.login()` function to see if the SDK is even functioning for us.
That should pop up a login dialog, but if you've been following along exactly, you'll most likely see
It took me for-fricking-ever to finally figure out that you need some additional settings in your App configuration. i.e. If you want to have facebook users interact with your application via the JS SDK, you need to set the Canvas URL in App on Facebook section of the Basic settings.
More specifically, [if you want to get a user's ID they need to log in to your Facebook App](http://www.google.com/search?sourceid=chrome&ie=UTF-8&q=site%3Awww.hyperarts.com+%22can+i+access+user+data%22+facebook), and in order for them to log in, you need to fill in the previous settings. Don't forget to Save Changes.
So we're hooked up to the API, now when we call login() from the console, you'll get the login dialog if you're not signed in to facebook yet, or an authorization dialog if you are
#### Let's add something for the user to do where we need to track their userID ##
Say we want to know which users clicked our special ninja link. First we need a special ninja link, add it to the fan-only section
`
We let fans click this <%= link_to 'special ninja link', '#', :id =>'ninja' %>
`
Then we need some JavaScript to check for a user that's authorized our App.
#### Let's walk through that real quick ##
Lines 5-11 define a function that gets called in our click handler when the user is logged in and already authed or after they login and allow the App access.
Lines 13-28 uses jQuery to override the click handler of the ninja link and
1. checks if they're logged in to facebook and have our app authorized already
2. asks them to login and auth if they're not
3. responds with one message for authed users
4. responds with another message for users that decline to allow access
Holy Crap! Are we really done?
--------------------------
Well let's see, we've got a fan Page with a custom Page Tab, that we set to be the Default Landing Tab. The content of our App is customized for Likers vs. non-likers, and we can pull the userID from Facebook when we need it. I'm going to call that good. Hope this has helped you. It'll be out of date any day now. FML.
### To recap the caveats and gotchas I ran into ##
1. Upload your logos and Icons as GIFs or Facebook will transcode them into hideous caricatures.
2. Remember to set your App's Canvas URL if you want to be able to log users into it.
3. The Custom landing will only be default for not-logged-in-to-facebook users and non-fans, i.e. once they like the page any subsequent visits will take them to the Wall.
