Adding a QuestionPoint Qwidget to Facebook

Introduction

This page will walk you through the process of creating a Facebook application that will make your QuestionPoint Qwidget available to Facebook users.

Below are the directions for building a basic Facebook IFrame application using an HTML page as well as a more advanced IFrame application using the Facebook PHP API.

Basic

Advanced

Advantages

1. No need to install/update PHP on your web server

2. No need to install/update JSON on your web server

3. Only need basic HTML skills to create, edit and maintain

1. Can integrate your application with other elements of the Facebook API

2. Facebook users can bookmark your app

3. Your app can have its own public page

Limitations

You will not be able to access the advanced Facebook features that require use of the Facebook API

1. Higher web server requirements

2. Advanced web development skills if you wish to use the rest of the Facebook API

NOTE: In order to build a Facebook application you must accept the Facebook application terms and conditions. It is up to your library to review and agree to the Facebook terms and conditions.

Where to get help

If you have any problems with this guide, please contact qpanalysts@oclc.org

Support for the Facebook Apps and the Facebook API is handled at http://developers.facebook.com

Directions for building a Basic Qwidget for Facebook

Things you'll need

1. A Facebook Account

2. A Facebook Public Page for your Library (see http://www.facebook.com/note.php?note_id=68842278095 to get started)

3. Access to a web server that supports HTTP where you can create, edit and host a .html file. This web server also needs to allow a POST to a file with an .html extension. If the web server does not support POSTs to .html files, your application will return a 405 error.

4. Access to a web server that supports HTTPS where you can host your .html file.

NOTE: As of October 2011, BOTH #3 and #4 are required by Facebookin order to build a Qwidget for a Facebook page

FACEBOOK NOW OFFERS AN APP HOSTING SERVICE CALLED HEROKU. PLEASE REFER TO HTTPS://DEVELOPERS.FACEBOOK.COM/BLOG/POST/558/

FOR MORE INFORMATION. NOTE: IF YOU USE THIS OPTION WE WILL ONLY BE ABLE TO HELP YOU WITH THE QWIDGET CODE. YOU WILL NEED TO WORK WITH HEROKU REGARDING THE SERVER AND APP SETUP.

Step 1 Creating the HTML files

Open your HTML editor of choice and create two html files. Name one fb.html and the other fb-s.html
Paste the qwidget code snippet below into the fb.html and fb-s.html page between the body tags Note: See the TIPs section for other things you can add to your fb.html and fb-s.html files Be sure to replace XXXXX with your 5 digit institution id For fb-s.html replace http with https to avoid the ‘page contains both secure and unsecure items’ warning NOTE: This code is NOT the same code as the qwidget code used to place on your library website, copied from the Admin module in QuestionPoint. It has a skin that was developed specifically for Facebook. You can also download this template from http://www5.oclc.org/questionpoint/fb/fb.zip
lSee the TIPs section for other things you can add to your fb.html and fb-s.html files
After creating fb.html, place it on an HTTP based web server where Facebook can access it.
Place fb-s.html on a HTTPS based web server where Facebook can access it.
Please contact your Web Administrator or IT department for your web site’s procedures. Once fb.html and fb-s.html are placed on the web servers, confirm that you can see the qwidget on both pages when you visit the URLs outside of your library’s network. You will use these URLs when you create your app
Begin the Facebook application building process, using the Facebook Developer tools

Step 2 Access the Facebook Developer Application

Log into Facebook
Click on the Search box at the top of the page
Enter Developer in the search box. You will given two suggestions in a drop down box
Click on App from the Developer page
On the Developer page, click on “Create New App”
On the Create Application page fill out the App Name and agree to the Facebook Terms on the Essential Information page Note that the application name can not have the word Facebook in it or contain terms that Facebook holds trademark on. The application name will appear on the application’s Facebook page that will be created once the build process is complete. The application namespace can only contain lower case letters
Fill out and submit the CAPTCHA check

Step 3 Build the App using Developer

This is the Facebook Developer App Interface

Add your Icon by clicking on the Picture at the top

Be sure your file is 16x16 pixels s and less than 5 MB in file size

Add your App Display Name

This will be the name displayed on the application

Add the App Namespace

This will be the unique name of the app and will be used for the canvas page.

It must be more than 7 characters. If you filled it in during setup, you won’t have to add it here

Add your Contact email

This will be the emailaddress used for contacting the developer

Add your App Domain name

Add the domain name that your app will be coming from.

For example, if you enter oclc.org it will cover *.oclc.org

Hosting URL

Only used if you decide to host your app with one of Facebook partners

Sandbox Mode

Set to Enabled until you are ready for others to see it

Click on the App on Facebook Checkmark and fill out the fields

Add the URL path to the Canvas URL box.

For example: if your URL is http://www.mylibrary.org/facebook-qwidget/fb.html then enter http://www.mylibrary.org/facebook-qwidget/

Add the URL path to fb-s.html to the Secure Canvas URL box

For example: if your URL is https://www.mylibrary.org/facebook-qwidget/fb-s.html then enter https://www.mylibrary.org/facebook-qwidget/

Canvas Width and Height should both be set to Fluid

Click on the Page Tab checkmark and fill out the fields

Page Tab Name: This will be the tab name for your app
Page Tab URL: Add the URL path to fb.html to the Page Tab URL.
Secure Page Tab URL: Add the URL path to fb-s.html to the Secure Page Tab URL.
Page Tab Edit URL: Leave this blank

Change the Page Tab icon

Page Tab Image is new and critical.

Select the width you would like then click change.

The dimensionsare 111x74 pixels

Click Save Changes

Click on Advanced in the left column

Add the description to appear in your user’s news feed for your app (if you decide to use the Facebook API)

Add your contact information and Privacy Policy URL

Note that Privacy Policy URL is a new feature and is required.

When complete click Save Changes

Step 4 Adding your App to your Page

Once completed, you will want to “Add” your application to your Facebook page

Load your App’s install link While logged into Facebook with the account as the editor of the page you wish to add the app to, enter this URL in your browser’s address bar , using the information from you app settings: https://www.facebook.com/dialog/pagetab?app_id=YOUR_APP_ID&next=YOUR_URL YOUR_APP_ID and YOUR_URL can be found in your app settings For example: https://www.facebook.com/dialog/pagetab?app_id= 104560596168612&next=https://capricalibrary.org/questionpoint/fb.html
Open the URL in a web browser This will open the following dialog: Click the “Choose Facebook Pages” drop down to select the page you wish to install the App and click “Add Page Tab”
A link to the Qwidget will appear in the Tabs listed on your page’s Tab Row
If you would like to add your app to the Facebook App Center, please visit https://developers.facebook.com/docs/appcenter/guidelines/

Directions for building an Advanced Qwidget for Facebook

Step 1 Create both a secure and unsecure directory on your web server

You will need to create two directories that will contain the following files once completed:

- index.php

- base_facebook.php and facebook.php (which can be downloaded from https://github.com/facebook/php-sdk/)

One directory can be on a standardweb server that uses HTTP (unsecure)

The secure directory needs to be hosted on a server that supports HTTPS (secure)

Both directories will need to be publicly accessible with its contents allowed to be listed so that Facebook can access the files

For example if you put the files in a directory called fb_qwidget you’ll have two paths that will look like this:

Unsecure = http://mylibrary.org/fb_qwidget/

Secure = https://mylibrary.org/fb_qwidget/

Step 2 Creating index.php

If you have not already done so, download the Facebook PHP Client library from https://github.com/facebook/php-sdk/. As of this writing, the current version is 3.1.1. It will be a compressed file in either a zip or a tar.gz format. Ask the administrator of your web server which version they prefer.

Click on the Download button

Select the highest numbered version (it will be at the top of the list) and download that file to your computer. At this writing the name of the file is facebook-php-sdk-v3.1.1-0-g9513f08.zip

Work with the administrator of your web server to create two directories

- one unsecured called fb that has execute privileges to host your file

- one secured call db that has execute privileges to host your file

Open facebook-php-sdk-v3.1.1-0-g9513f08.zip

Click on the src folder

Move base_facebook.php and facebook.php to both secure and unsecure version of your fb directory

Click on examples

Move example.php to both secure and unsecure version of the fb directory

Rename example.php to index.php on both the secure and unsecure version of the fb directory

Using an editor open each version of the index.php and make the changes detailed in the next steps

Around line 22, replace the appID with your App ID from your Application Page

Around line 23, replace the secret with your App Secret from your Application Page

Around line 59, change the page title php-sdk

Remove everything between the tags

Between the body tags, add your qwidget’s code and any other content you wish to add

You can add other HTML and Facebook elements such as text, graphics and tables to index.php. Your Canvas is 760 pixels wide. If you go over this amount, your app will display a horizontal scrollbar

Save and close index.php

Step 3 Access the Facebook Developer Application

Log into Facebook

Click on the Search box at the top of the page

Enter Developer in the search box.

You will given two suggestions in a drop down box

Click on App from the Developer page

On the Developer page, click on “Create New App”

On the Create Application page fill out the App Name and agree to the Facebook Terms on the Essential Information page

Note that the application name can not have the word Facebook in it or contain terms that Facebook holds trademark on.

The application name will appear on the application’s Facebook page that will be created once the build process is complete.

The application namespace can only contain lower case letters

Fill out and submit the CAPTCHA check

Step 4 Filling out the Developer Application’s Essential Information page

On the Create Application page fill out the Application Name and agree to the Facebook Terms on the Essential Information page

Note that the application name can not have the word Facebook in it or contain terms that Facebook holds trademark on.

The application name will appear on the application’s Facebook page that will be created once the build process is complete.

Fill out and submit the CAPTCHA check

Step 5 Creating the Facebook Application Page

This is the Facebook Developer App Interface

Add your description: Add things like hours of availability and information about your library

Add your Icon by clicking on Icon image

When you click the Change your icon link, you will be taken to the icon upload page in a 2^nd window.

Icons are 16x16 pixels and less than 5mb in size

Check your app display name

This will be the name displayed on the application and has been auto-filled for you when you completed step 5.2

Add the App Namespace

This will be the unique name of the app and will be used for the canvas page.

It must be more than 7 characters

Add your Contact email

This will be the email address used for contacting the developer

Add your App Domain name

Add the domain name that your app will be coming from.

For example, if you enter oclc.org it will cover *.oclc.org

Hosting URL

Only used if you decide to host your app with one of Facebook partners

Sandbox Mode

Set to Enable until you are ready for users to use your Qwidget

Click on the App on Facebook check and fill out the fields

Add the URL to fb.html from step 3 to the Canvas URL box.

Add the URL to fb-s.html from step 3 to the Secure Canvas URL box

Click on the Page Tab check and fill out the fields

Page Tab Name: This will be the tab name for your app

Page Tab URL: Add the URL to fb.html from step 3 to the Page Tab URL.

Secure Page Tab URL: Add the URL to fb-s.html from step 3 to the Secure Page Tab URL.

Page Tab Edit URL: Leave this blank

Change the Page Tab icon

Page Tab Image is new and critical.

Select the width you would like then click change.

The dimensionsare 111x74 pixels

CLICK ON SAVE CHANGES

Click on Advanced

Add the description that you wish to appear in your user’s news feed for your app (if you decide to use the Facebook API)

Add your contact information and Privacy Policy URL

Note that Privacy Policy URL is a new feature and is required.

On the Application page, copy the App ID and the App Secret as you will need these values when you create your index.php file in step five.

Step 6 Creating the Facebook Application

Log into Facebook
Go back to the Developer appcliation
Click on the link for your application from the “Recently Viewed” list
Click on “Edit Settings”
Canvas page: Enter the name for your application. It needs to be over seven (7) characters.
Canvas URL: This is the path to your PHP file. Be sure to add a / at the end of the URL Example: http://www5.oclc.org/questionpoint/fb/
Secure Canvas URL: This is the path to your secure PHP file. Be sure to add a / at the end of the URL Example: https://www5.oclc.org/questionpoint/fb/
Click on Advanced and look for the Canvas settings section
Canvas Type: Set to IFrame
Canvas Width: set to fixed
Canvas Height: Set to Fluid
Social Discovery: Set to Enabled
Bookmark URL: Leave blank
Tab URL: Enter the URL path to your unsecure index.php page here. Example: http://www5.oclc.org/questionpoint/fb/
Secure Tab URL: Leave this blank Enter the URL path to your secure index.php page here. Example: https://www5.oclc.org/questionpoint/fb/
Edit URL: Leave this blank
6.1 When complete click Save Changes. When you click Save Changes you will be taken to your application’s developer page. You can use the links on the right of this page to make any changes or corrections to your application

Step 7 Installing your App to your page

Load your App’s install link While logged into Facebook with the account as the editor of the page you wish to add the app to, enter this URL you’re your browser’s address bar https://www.facebook.com/dialog/pagetab?app_id=YOUR_APP_ID&next=YOUR_URL YOUR_APP_ID and YOUR_URL can be found in your app settings For example: https://www.facebook.com/dialog/pagetab?app_id= 104560596168612&next=https://capricalibrary.org/questionpoint/fb.html
Open the URL from the last step in a web browser This will open the following dialog: Click the Choose Facebook Pages drop down to select the page on which you wish to install the App, and click “Add Page Tab”.
A link to the Qwidget will now appear in the Tabs listed on your page’s Tab Row
If you would like to add your app to the Facebook App Center, please visit https://developers.facebook.com/docs/appcenter/guidelines/

Step 8 (optional) Setting your App as the default landing tab

You can set the Qwidet to be the default tab that opens when someone lands on your page by following these steps.

Click on Account
Click on Use Facebook as Page
Click on "Switch" for the page you want to edit
Click “Edit Info” at the top of the page
Click on Manage Permissions
Change “Default Landing Tab” to match the App you want to use
Click on "Save Changes"
"View Page" Note that as a Page Admin, your default view will be the page’s wall.

Tips and Tricks

Tips

You can add other HTML elements such as text, graphics and tables to your fb.html and fb-s.html page. As in this example:

Documentation