Facebook integration
From podhawk
Introduction
PodHawk 1.8 contains a completely new Facebook plugin. The old PodHawk Facebook facility which has been present in various forms since version 1.6 no longer works properly, because Facebook has made large changes to its API.
The new Facebok plugin enables you:
- to create an "application" on Facebook
- to create a "canvas page" for your application which displays your posts and plays your podcasts
- to create a "page tag" which you can attach to any Facebook page which you administer. Other people can attach the tab to pages which they administer also.
- to add Open Graph meta tags to your web pages. These allow Facebook to understand the type of material on your site, and to link it to Facebook users who "like" it;
- to add Facebook Social Plugins (eg "like" buttons) to your web pages.
To use any of these features you must create an "application" - see below. You can then choose which of the other features you want.
Why?
There are several Facebook applications (eg Network Blogs) which will display blog posts in a page tab and allow users to send posts to their friends. Why should you use the PodHawk plugin instead of an existing application?
- other Facebook blog applications run off your RSS feed. Some will cache your feed and so may not be fully up to date. The PodHawk plugin runs direct from your PodHawk site and your database.
- the Podhawk plugin uses templates which you can edit so that your podcasts are displayed as you want them.
- the PodHawk plugin allows your users to "share" not just your posts but also your podcast mp3s with their friends.
- the PodHawk plugin can add the correct Open Graph tags and 'like' buttons to your web-page.
First steps
You need a Facebook account. Go to Facebook to create one.
You need to enable the Facebook Developer application. Go to the Facebook developer application, and authorise the developer application to access your personal details.
Click on the "Create new app" button. When asked, give your application a "display name" (eg "Mike's Podcasts") and a "namespace" (eg "mikespodcasts"). The "namespace" has to be unique. If your chosen namespace is already in use, Facebook will let you choose again. Facebook will give you two vital bits of data - a secret key, and an ID for your application. PodHawk needs these in order to communicate with your new Facebook application.
Go to your PodHawk plugins page (Manage > Plugins). Install the Facebook plugin if it is still in the "not yet installed" list at the bottom of the page, then click "edit status and settings". Enter the name which you have just give to your Facebook application into the first text box on the page, and copy and paste your application ID and your secret key into the next two boxes. Select the "enabled" radio button. Click "save". Congratulations. Your PodHawk site is now a Facebook application.
Configuring your new Facebook application
Then return to the Facebook Developer page for your new application. (How do you find this? In the left-hand column of your Facebook home page, click 'apps', then 'developer', then on the name of your application). You need to enter a number of settings for your application before it will work.
- click on 'Edit app'.
- fill in any missing details in the "basic information" section. In the box labelled "App domain", enter the URL of your PodHawk site, without http:// and with no trailing slash eg www.mikespodcasts.com.
- ignore the section on Cloud Storage and scroll down to the sections headed "Select how your app integrates with Facebook"
- click on 'Website' so that the tick on the left turns green. Fill in the url of your website (with http:// at the beginning)
- click "Save Changes" at the bottom of the page.
Canvas Page
If you want your podcasts to have a Facebook Application Page:
- on the Facebook Developer page for your application, click on 'App on Facebook'. The tick will turn green and a box for data entry will open.
- in the first text field ("Canvas URL") enter http://[www.mysite.com]/podhawk/custom/plugins/facebook_plugin/ (with the trailing slash). This is the URL that Facebook will go to to get data for your canvas page.
- the next bit is really boring and may make you decide that you don't really want a Facebook canvas page at all. Facebook now require that all application canvas pages have a secure (https://) URL as well as a normal http:// URL. (The same applies to page tabs, see below, but there is a workround for page tabs which unfortunately doesn't work with canvas pages). Basically, you need a SSL Certificate for your website, and generally you have to pay for these. Your hosting provider may be able to give/sell you one. Otherwise Google for "SSL Certificates" and find a company that will provide a certificate for you. There are huge variations in cost between the cheap and cheerful self-signed certificates and ultra-secure certificates like Verisign. When you have sorted out a SSL Certificate, you can type the same address in the "Secure canvas URL" box as you put in the "Canvas URL" box, but with https:// at the beginning.
- as a purely temporary measure, to test out the canvas page, you could try adding the Secure canvas URl above even though you don't have a security certificate. I think that Facebook checks only that there is an https:// address in the "Secure canvas URL" field, but not that it is the correct one! Obviously,Facebook users will not be able to access your canvas page with an https:// address if you do this.
- click on "Save changes" at the bottom of the page
- note the "Canvas page" URL (the last box under "App on Facebook"). It will read http://apps.facebook.com/namespace where "namespace" is the namespace you entered when you set up your application. Go to the PodHawk plugins page for the Facebook plugin. Tick "Do you want an applications page on Facebook?" and enter the canvas page URL. Click "Save" at the bottom of the page.
If you now navigate to your canvas page URL, you should see first a dialogue asking you to "authorise" the application, and then the canvas page itself which contains your most recent podcasts.
If your canvas page does not display as you expect, you may have to adjust some of the advanced settings (click "settings > advanced" in the sidebar of the Developer page for your application.) The content of the "advanced settings" page varies with time, as Facebook introduce new features or retire old ones. Under "Authentication", the "app type" should be "web", and sandbox mode should be disabled. Under "migrations", if there is a pair of radio buttons for "Enhanced Auth dialogue", they should be set to "enabled". Similarly, if there are radio buttons for "iframe Page tab", they should be set to "enabled". Further down, under "Canvas settings", "canvas width" should be fixed (760px), and "canvas height" should also be fixed, at 800px. "Social discovery" should be enabled. If there is a setting for "canvas type", it should be set at "iFrame" and not "FBML". Don't forget to click "save changes" if you have changed any of the settings.
Adding a Page tab to a Facebook fan page
- go to the Facebook Developer page for your application
- click on "Page tab". The tick on the left should turn green and a box for entering data should open.
- in the first box enter the name you want your app tab to have ("Mike's Podcasts")
- in the second box ("Page tab URL"), enter http://[www.mysite.com]/podhawk/custom/plugins/facebook_plugin/apptab.php. This is the URL where Facebook will find the content for your page tab.
- the third box requires a secure URL, exactly as the canvas page does (see above). If you have a SSL certificate for your site, enter the same URL as in "Page tab URL" but with https:// at the beginning.
- if you don't have a SSL certificate and don't want the expense and hassle of getting one, go to this site. Some very public-spirited folk have set up a service for SSL certificates specifically for Facebook page tabs. Register, follow the instructions and enter the https:// address they give you in the "Secure Page Tab URL" box.
- you can leave the final box, "Page Tab Edit URL", blank.
- click "Save changes" at the foot of the page.
- go back to the Facebook plugin page on your Podhawk installation. At the bottom of the page, click on the link "Click here to add your app as a Page Tab to any Facebook pages which you administer". This will redirect you to a Facebook page where you can select the page or pages to which you want to add the tab.
Adding Open Graph meta tags to your PodHawk web page
Open Graph (OG) is a a system for discovering information about a web "object" such as a web page or a blog posting, and for linking eg individual Facebook users with web pages that they have "liked" or "shared". There is a fuller explanation here. Essentially, to allow your web page to be linked in to the Open Graph system, you need to add some meta tags to the head section of your web page. PodHawk will do this automatically, if you check "Add Open Graph tags to my web pages?" on the Facebook plugin management page. You should add your personal Facebook id or your personal Facebook user name in the box below, and your Facebook application "namespace" (which you set when you first set up your application) below that. If you have a Facebook fan page associated with your podcasts, enter the id of the page in the appropriate box further up the page. This will ensure that your Open Graph meta tags link your web page to your Facebook account, and to your page.
It is strongly recommended that you enable Open Graph tags for your site, even if you do not use any of the other features of the Facebook plugin. When, for example, a Facebook user "likes" your page, or shares it with their friends, the OG tags will allow Facebook to include better information about your page in the user's wall post and news stream. For example, if someone "shares" a post which contains an mp3, Facebook will include an mp3 player to play your podcast in the user's news item.
How do I find my Facebook personal name or ID?
Navigate to your Facebook home page. Click on your photograph in the top left hand corner. Then look at the address in the navigation bar of your browser. It will readhttp://www.facebook.com/[yourusername]. "yourusername" is your personal Facebook user name. If you want your numeric ID, first find your user name as above, then navigate to
https://graph.facebook.com/[username], which will return basic public data about you. The first data item is your unique Facebook numeric ID.
Facebook Social Plugins
Facebook Social Plugins are features which can be added to a web page to allow people visiting the page to interact with Facebook and to allow the page to display certain Facebook information. Facebook supports two methods for putting social plugins on a web page - iframes and a Javascript SDK. The PodHawk plugin uses the second of these. If you check "Use Facebook social plugins on your web pages?" on the plugin page, PodHawk will automatically include a call to the Facebook Javascript SDK in your web pages. Adding any of the social plugins is then simply a matter of including some "<fb:....>" tags in the appropriate place in your theme template.
The PodHawk Facebook plugin will allow you to add the most common Social Plugin, the "like button", automatically. Just click "yes" beside 'Add Facebook "like" button to your posts?', and fill in the information underneath.
If you want to add any of the other Social Plugins, click on the appropriate link on the Facebook social plugins page, and follow the instructions. You can use either the iframe or the Javascript methods, but the second is shorter - you do not need the <script....></script> bit (PodHawk already loads the Javascript) - simply the <fb:..></fb:..> tags. There is an example below.
Alternatives to the Facebook like button
You do not have to use the Facebook "like" button to enable users to share your content on Facebook. The PodHawk "Share This" plugin has options for including a Facebook button, as well as buttons for a number of other social media sites. You should however enable Open Graph tags (in the Facebook plugin) so that Facebook can find full information about your web page when users "like" it.
Communicating with your users on Facebook
You probably want to be able to send information to your users on Facebook from time to time eg to tell them when you have put a new posting on air.
It would be possible to write a Facebook plugin which would ask for "extended permissions" from users to write to their walls or to send them e-mails. However, this would require an extra database table to store details of authorised users, access codes and e-mail addresses. You would be responsible for the security of this data.
There is however a much simpler way. Facebook fan pages are easy to set up. Any status update which you, as the administrator of the page, post on your fan page is copied to the streams of all the users who have "liked" the page. Users can themselves post things on your page (you can remove them if you don't like them!), and can join in discussions etc. You can attach your PodHawk Facebook application to the page as an application tag (see above). You can of course link to your fan page from your PodHawk website and tell your users about it in your podcasts.
Once you have acquired a few "likes" you can set up a way of posting updates to your fan page automatically whenever you put a new post on air. You can't do this directly, but there is a simple indirect route through Twitter. Set up a Twitter account specially for your podcasts (unless you are happy to have stuff about your podcasts in your normal Twitter stream). Then set up the PodHawk "Ping" plugin to send a Tweet automatically when you publish a new post.
The second stage is to link your fan page with your Twitter stream. You do this using the Selective Twitter application. Click on "Your Fan Pages", fill in the details of the Twitter stream which you want the application to follow, and authorise it to write to your page. Then all you have to do is to include #fb at the end of Tweets that you want Selective Tweets to post to your page. (Do this by adding #fb to "Text of the tweet to send when you put a new post on air" on the Ping plugin page).
So, to summarise - you put new post on air; PodHawk Ping plugin sends tweet to Twitter; Selective Twitter application catches the tweet and posts it on your fan page; fan page posts to all users who "like" the fan page.
Adding a Like Box to your site
It is not even necessary for users to visit your fan page in order to "like" it. The Facebook Like Box social plugin allows them to "like" your fan page by clicking a link in your normal web-page. I have placed a Like Box on my website (http://www.listen-to-english.com) by adding the following code to the sidebar template:
<fb:like-box href="http://www.facebook.com/ListenToEnglish" width="170" height="80" colorscheme="light" stream="false" header="true" show_faces="false"></fb:like-box>
Obviously, you would replace 'ListenToEnglish' with the name of your own fan page, and you might want to play around with the other attributes so that the box displays nicely on your site. NB You do not need the <script..></script> tags which the Facebook Like Box wizard gives you - provided that you have checked the 'social plugins' tag on your Facebook Plugin page, PodHawk will load the Javascript call automatically. I wanted a relatively small Like Box with no faces. Unfortunately, this meant that it did not display the number of "likes" which my fan page had collected. So I wrote a small jquery routine and added it to the sidebar template immediately below the code for the Like Box:
<p id="likes"></p>
<script type="text/javascript">$(document).ready(function() {ldelim}
$.getJSON("http://graph.facebook.com/103806758570?callback=?", function(data) {ldelim}
var l = data.likes + " people<br />like Listen to English";
$('#likes').append(l);
{rdelim});
{rdelim});
</script>
Obviously, you should replace 103806758570 with the id of your own fan page, and use your own fan page name instead of "Listen to English".
Shortcut URLs
The Facebook plugin will redirect a call to http://www.your-podhawk-site/facebook to your Facebook fan page, if you have entered the id of your fan page in the plugin page; otherwise to your Facebook application canvas page, if you have one.
