Two-Minute Tutorial 5 Part 2

TMT5 Part 2 Add the Facebook Plugin to an App

This advanced Two-Minute Tutorial (TMT5P2) shows how to add the Facebook plugin to your PhoneGap for Android AppLaud app featuring:

  • Cordova 2.0.0 (or latest Cordova release)
  • Apache Cordova Facebook Connect Plugin
  • Facebook Android SDK
  • Hackbook for Android – Social Graph App
  • Inspired by Steve Gill’s video demo PhoneGap Facebook Plugin for Android

Prerequisites

  • Installation of the latest MDS AppLaud plugin, see Get Started
  • Complete of TMT0 or equivalent (create project, edit files, run app on device)
  • Github account / installation on dev host

 

Prep

  • Download Cordova 2.0.0 (or latest Cordova release)
  • Register App with Facebook
  • Clone and Initialize Facebook Connect from Github
  • Jump to Prep Help for help completing steps
Completion of the Prep material before starting will make this tutorial go more smoothly. Although there are many steps and details, adding Facebook to your app is not difficult using this plugin. Using Hackbook as the demo app helps log in flow and provides example code.
You may want to view Steve Gill’s PhoneGap + Facebook video but it is not required. This tutorial is based on his video, with changes for AppLaud-based projects and also to use Cordova 2.0.0 (video uses 1.8.1). Skip from 1:16 – 6:20s in the video to save time, as it demonstrates steps to create a PhoneGap / Android project (AppLaud does all that for you during project creation with the wizard).

1. Create AppLaud Project with Cordova 2.0.0

In the first window of the project creation wizard, select the two items as shown below. Browse to the top level of the downloaded, unzipped Cordova 2.0.0 (or later versions) and use it instead of the built-in versions of Cordova. All files, libs and resources for Cordova 2.0.0 will be added to the project for you.

At writing time, the latest version of AppLaud offers as built-in Cordova 1.4.1, 1.5.0, 1.6.1 and 1.9.0. However, as shown above, any version of Cordova may be downloaded to your local computer and used during project creation.

Finish creating the project as normal. The example in this tutorial names the project fbdroid

2. Register Facebook Plugin in Project’s xml file

Open the new project’s res/xml/config.xml file in the editor. Add the following line inside the plugins element:

<plugin name=”org.apache.cordova.facebook.Connect” value=”org.apache.cordova.facebook.ConnectPlugin” />

Important: With Cordova 2.0.0+ the file res/xml/config.xml replaces both res/xml/cordova.xml and res/xml/plugins.xml.

3. Add Facebook SDK Source and Resources

You must complete Prep: Clone and Initialize Facebook Connect for the following. This step adds the Facebook Android SDK and Resources to your project.

Open your computer’s Finder or file browser and go to the directory:

<your-local-git>/phonegap-plugin-facebook-connect/lib/facebook-android-sdk/facebook

Select and copy the res and src directories. See example below.

Right click on the fbdroid project and paste the items into your project. Select “No” when asked to overwrite contents. Verify the project has a new package, com.facebook.android, in the src directory as shown below.

4. Add PhoneGap Plugin for Android

This step adds the PhoneGap Facebook Connect Plugin to your project.

Open your computer’s Finder or file browser and go to the directory:
<your-local-git>/phonegap-plugin-facebook-connect/native/android/
Select and copy the src directory. See example below.

Right click on the fbdroid project and paste the item into your project. Verify the project has a new package, org.apache.cordova.facebook, in the src directory as shown below.

Important: You must have three packages in your project as shown above:

  • Facebook SDK (com.facebook.android)
  • Facebook Connect Plugin (org.apache.cordova.facebook)
  • Your project’s package (com.mds.fbdroid in the example)

If you don’t, you may have pasted them into the wrong directory in your project. Now is a good time to try again!

5. Add Facebook Plugin and Connect JavaScript

Copy these two JavaScript files into the project’s /assets/www directory:

<your-local-git>/phonegap-plugin-facebook-connect/lib/facebook_js_sdk.js
<your-local-git>/phonegap-plugin-facebook-connect/www/cdv-plugin-fb-connect.js

No need to edit index.html yet as the next step adds a new index.html.

6. Add Hackbook Example App

This step adds the Hackbook Example App to your project, replacing the Minimal PhoneGap Project contents added at creation time.

Copy the entire contents of the HackBook directory into /assets/www:

<your-local-git>/phonegap-plugin-facebook-connect/example/HackBook/

One way is to select and copy the entire contents of the directory using your host’s file manager as shown below:

Paste these files and directories into /assets/www and answer “Yes” to overwrite index.html.

Open index.html in the Editor and change the version of Cordova to 2.0.0:

<script src=”cordova-2.0.0.js”></script>

7. Fix Errors in Java Code

If you’ve done everything right up to now, you will have errors reported in the Java code. If you don’t, select Project > clean… to rebuild the project and show the errors.

Open com.facebook.android.FbDialog.java. Add the import line as shown below. The example shows the app package as com.mds.fbdroid – use your app’s package and name here.

At the time of writing this tutorial, the connect plugin has not been updated to work with Cordova 2.0.0. If you see an error in org.apache.cordova.facebook.ConnectPlugin.java, it is likely related to a reference to Activity in Java. Locate the error, and replace (Activity)me.ctx with cordova.getActivity(). The example code below shows examples old (error) and new code:

// OLD: me.facebook.authorize((Activity)me.ctx, me.permissions, …    me.facebook.authorize(cordova.getActivity(), me.permissions, …

8. Add Facebook App ID

This step adds your Facebook App ID. Open assets/www/index.html to see the Hackbook html. Locate the line near the end starting with FB.init and replace appid with the App ID you got from the Prep step. The ID is used as a string so keep it in quotes.

FB.init({ appId: “appid” …

9. Run App and Log In

Run the app on a device. Successful addition of Facebook SDK, Connect Plugin and the Hackbook app will show the Hackbook login screen shown at the start of this tutorial. Tap the Login button in the upper right corner and log in with your Facebook credentials.

An example of the Allow screen is shown here. Note that the name of the app you registered with Facebook will appear on this page in place of the tutorial app’s name AppLaud TMT5 P2.

The Hackbook App provides many examples and different ways of using Facebook in your social app. Refer to the Hackbook code in assets/www/ to learn how to access Facebook.

Prep Details

Download Cordova 2.0.0

Get Cordova 2.0.0 (or latest version) from phonegap.com and unzip it. The plugin code used at the time of this writing needs one change (explained during tutorial) to work with Cordova 2.0.0. It has not been tested with earlier versions of Cordova. It is expected to work with versions greater than 2.0.0, possibly without needing the changes mentioned.
Register App with Facebook

Register as a developer at developers.facebook.com/apps. Create an app and go to the Apps tab (at very top) on your developer page. Click on the Edit App button and find the section “Select how your app integrates with Facebook”. Enable the configuration for Android SSO (your page may look different than below) and provide a key hash as described next.

Facebook provides instructions on generating an Android Key Hash here. If you have Android tools in your path on your host machine, it may be as simple as running the following command and entering password “android” as shown below.

 

$ keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64
Enter keystore password: android
<android key hash will be output here>

On the app’s main page, find the App ID (example: orange field below) needed in step 8. The name of my app is “AppLaud TMT5 P2”.

Clone and Initialize Facebook Connect from Github

You must have a github.com account and be able to clone repos. Help for github fork/clone : https://help.github.com/articles/fork-a-repo.

After forking and cloning, init the submodule with the following command:

$ cd <your plugin repo directory>

$ git submodule update –init

You should see output similar to this:

libby@nirvana:~/git/phonegap-plugin-facebook-connect$ git submodule update –init
Submodule ‘lib/facebook-android-sdk’ (git://github.com/facebook/facebook-android-sdk.git) registered for path ‘lib/facebook-android-sdk’
Submodule ‘lib/facebook-ios-sdk’ (git://github.com/facebook/facebook-ios-sdk.git) registered for path ‘lib/facebook-ios-sdk’
Cloning into lib/facebook-android-sdk…
remote: Counting objects: 1781, done…