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

1. 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 into the fb.html and fb-s.html page between the body tags

You can also download Qwidget-FB-Template.zip which contains a template of both files.

n the Qwidget's URL, replace the color with facebook and the XXXXX with your 5 digit  institution id as in the example below:

.../crs/qwidgetV4/js/qwidget.bootstrap.js?&langcode=10&instid=00001&skin=facebook&size=fill


For fb-s.html replace http with https to avoid the ‘page contains both secure and unsecure items’ warning

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
At this point you can 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 an option for Developer App that will take you to https://developers.facebook.com/

 

Click on Apps 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 an option for Developer App that will take you to https://developers.facebook.com/

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 2nd 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.  
QP_Logo_Tag_C_3C_MD