Ok, so we are talking about COBOL-based Object Oriented Programming of drag-and-drop mashable objects to build a front-end to SAP that will show your sales forecast on mobile phones.
What?
Hang on. None of the above. Let’s start again.
This post is about “Hello, World” level applications in Facebook. So everyone else: Go away.
Getting a bit serious about it: I’ve been reading up on the Facebook API in the developer docs. The stuff I came across was generating a throbbing headache a couple of centimeters behind my frontal lobe. I was thinking: This is complicated.
The reason is that there’s no developer guide that I could find. The reference, or any other reference manual for that matter, is meant for people already at the medium to expert level who need to refer to parameters of individual API’s. For beginners, you need a beginner’s guide. The few lines of code on FB’s own site failed to bring any revelations. I had to spend a lot of time at Google.
The reason I had to Google so much is this: The tutorials that you find are perfectly good but the problem is Facebook itself. FB people change their API’s and user interface every time one of them comes back from lunch. So the first thing to note is that today is December 10th, 2010. If the FB interface that you see is any different from the screen shots given here, stop reading and go find a later tutorial.
I shall be updating this entry as I find the gotchas. The first gotcha is: check the PHP version on your host. If your server runs PHP5, well and good. If it runs PHP4, go away. I’ve spent too much time looking for 3rd party ports of the API’s. However, they’re all obsolete or may become so any minute now.
Programming Models
There are four slightly different methods of FB programming. Do not confuse the docs covering them.
The first is using an application to run your application. Sounds daft? I meant, there is an application called “Static FBML”. From the FB main page, click on Applications, type Static FBML in the Search box and select it from the result. Add it to your Wall. What this will do is to let you type static FBML code right there to be displayed on your Wall. This can be done for product pages that you make. However, none of the fancy stuff is allowed here.
The second method is your own page on your own website that pulls info from and pushes back to FB. The method is mentioned here because the API’s that you would use would be slightly different in this case.
The last two methods are for displaying a page on your own wall’s tab or that of a product page. In both these cases, there are two things to remember:
1. The page’s code itself resides purely on your server but you never open it as http://www.myownserver.com/MyFBApp.
2. The resulting page is shown within FB’s pages as http://apps.facebook.com/MyFBApp
Let’s call them methods FB1 and FB2.
What they have in common is that they are simple HTML to begin with. For starters, just write <P>Hello, World</P> in a file and save it.
Here’s the first reason for a blank page that every beginner will get: The file must not contain <HTML>, <HEAD> or <BODY> tags. Obvious when pointed out but a common mistake.
Where they differ is… they differ in ways too long to detail. Let me give the short answer:
FB1 generates an IFrame with the source set as your page. FBML will not work in this case. This is an IFrame content being pulled from your server with all that implies. That the IFrame is within an FB page is incidental; don’t try to use any FB features here. To tell the truth, you can get FBML to work here but not by the straight forward method, so till you progress to higher level, forget about FBML.
The page can run JavaScript and it will work as expected. More on that later.
FB2 is the real programmer’s way of doing things; all functions will work. You can pull login info, friends lists, messages, personal info, bank account detail, 3rd grade results. Well, maybe not the last couple of items but pretty much everything else.
The page can run JavaScript but it will not work as expected. The reason is that FB will rename all your id’s.
There are also differences when using FB1 & FB2 methods in the fonts and placement. Since they don’t have a <HEAD> section, the normal method of using CSS won’t work.
Now, go back and read the stuff on the four different methods again and decide how you want to proceed. I shall be going over FB2 only from here.
…
Done? Let’s proceed.
Prerequisites
You need your own server that runs PHP5. This is a beginner tutorial and I won’t be covering C##.NET with Framework 4.5, Delphi, Visual FoxPro and others.
As per the documentation, you need the PHP include file from github. Inside the zip archive is a folder called src which contains a file named facebook.php. This file would be included in ever page.
Time for your next set of errors. Nothing is going to ever work regardless of what you do if you are using PHP4. Don’t even try. This file is for PHP5 only. The official link for the PHP 4 and 5 Client Library for the tar.gz file is giving an error. As I am getting a 404 on nearly all developer.facebook.com pages today, they could be updating the site. Lunch time already?
Building the Application
Let’s click on the Applications menu on the left:
and then select the Developer application from the list. One assumes that you’ve gone thru the terms of use, agreed to them, and so on.
Click on the button to Set Up New Application
Give your app a name.
Nothing special on the About page other than the name of the application, Leave the two URL fields alone till you can provide pages for them.
This confused me for a bit and is another of those things that are clear in retrospect only.
The values on this page are to be used only if you are going to have a page on your own site that uses FB API’s for data. Otherwise, leave them blank.
Last of the Obvious-Things-That-Trip-You.
The Canvas Page is the URL of the application as far as the external world is concerned. All of them have the same starting http://apps.facebook.com The next part is what yours is going to be known by. Do not try for a cute name; they’re all taken.
The Canvas URL is the physical location of the page. More gotcha’s here: This can not be www.myserver.com/mytest.php This must be a folder name so it can be a file named index.php in www.myserver.com/mytest/. Only in the case of dynamically created pages can it have a name different from the default. But don’t try it right now. That is too an advanced topic.
Some older documents talk of a Callback URL. This parameter no longer exists on this page.
The Canvas Type is our FB1 and FB2 method mentioned above.
Leave all other fields blank.
Leave the other tabs alone. Don’t fill in any values there.
Also note the API Key and Application Secret values. You need to put these in your PHP file.
The PHP
All the stuff that was needed to be done on the FB site has been done. The rest shall be done on your server only. Check the results on http://apps.facebook.com/YourAppName.
Let’s ensure that all the FB settings have been done correctly. In your index.php file, put only the single line:
<P>Hello, World!</P>
and test it. If you have done everything correctly then it should work.
Next, check that PHP is working. Add the following lines:
<?php
echo ‘Hello from PHP’;
?>
That should show that you are now all set to start building the most popular FB application in the world.
Next, take the facebook.php file that you downloaded from the FB developer site and upload it to your server.
Next major gotcha is that a high number of sample code for index.php that you would see on the Internet looks like this:
<?php
require_once 'facebook.php';
$appapikey = '21e4dd7042467d0b23809aafb6f20217';
$appsecret = '115a5e8df3ad491b6bc1a8434af0544e';
$facebook = new Facebook($appapikey, $appsecret);
$user_id = $facebook->require_login();
$callbackurl = 'http://www.myserver.com/MyApp/';
?>
I assume that your are aware that the API key and secret should be the one in your application and not from the copy above.
Here is the $callbackurl. There are differing documents about it. Originally, it was in the application description on the FB page but must now be given in your PHP file.
There are three variations of what the callbackurl is:
- http://apps.facebook.com/YourAppName
- http://www.myserver.com/MyAppName
- http://www.myserver.com/MyAppName/index.php
I guess it’s another one of those time-of-day things and the sources that I found claim that only one method works. Check FB documents to see which variation is in vogue today.
In actuality, don’t waste your time. All of the above is not going to work at all. Ignore all sample code along the lines that you see above. The new, updated, improved, latest version of FB API’s don’t support this any more. All such code is obsolete.
As of 1pm today, the one that works is totally different.
First off, upload the fb_ca_chain_bundle.crt file from the zip that was downloaded from FB to your server.
Your index.php should read:
<?php
require_once 'facebook.php';
$appapikey = '21e4dd7042467d0b23809aafb6f20217';
$appsecret = '115a5e8df3ad491b6bc1a8434af0544e';
$facebook = new Facebook(array(
'appId' => $appapikey,
'secret' => $appsecret,
'cookie' => true,));
$session = $facebook->getSession();
$mypageurl = 'http://www.myserver.com/myapp/';
if (!empty($session)) {
$userdata = $facebook->api('/me');
echo '<h1>My First FB Application</h1>';
echo '<h2>Hello, ' . $userdata['first_name'] . '</h2>';
echo '<p>Nice to meet you</p>';
} else {
$login_url = $facebook->getLoginUrl(array(
'canvas' => 1,
'fbconnect' => 0,
'next' => $mypageurl,
'cancel_url' => $mypageurl,
'req_perms' => 'PERMISSIONS'
));
echo '<a href="<?=$login_url?">Login</a>';
}
?>
This should be enough for one day.
There are two things that I leave you with.
First off is that there is a lot of data in the $userdata variable that was fetched above. Use print_r($userdata) to see for yourself. This is an array with these items:
- [id] – The internal numeric id of the FB user
- [name] – Full name of the user
- [first_name]
- [last_name]
- [link] – The FB profile page of the user
- [about]
- [birthday]
- [hometown] – Array of [id], [name]
- [gender]
- [religion]
- [timezone]
- [locale]
Two more fields that really are funny:
- [relationship_status]
- [significant_other] – This is an array of names and FB id’s. Why? In case of polygamy?
There are two other items in the $userdata array. These are [work] and [education]. Both of them are arrays and most of the items are arrays themselves.
My second, and more important, closing point is that you must not rely on the code samples on various web sites because the FB API’s keep changing so much. You have to always refer back to FB’s own developer reference site to see what will work for you.
