(Our Stephen Tramer contributed the portion of this article that concerns Facebook authentication in iOS.)

Titanium Mobile 1.6.0 (currently in its release-candidate stage) contains an upgraded Facebook module which uses new authentication features on both Android and iOS as well as a new set of methods to retrieve and submit data. Our new API documentation won’t get generated and put up on the site until 1.6.0 actually ships, but until then you can peruse the “raw” version of the docs in our Github repository. Some sample code is included therein as well as in the latest KitchenSink Facebook examples (search for “facebook” when you get there).

Authentication and Authorization

Our iOS and Android implementations both use Facebook’s OAuth 2.0 authentication scheme, as Facebook has deprecated all other forms of authentication. You don’t have to worry about any OAuth magic: we’re using Facebook’s official SDK for both iOS and Android, and it handles all that for us. You just need to either use our module’s Titanium.Facebook.authorize() method or you plop our Facebook LoginButton (Titanium.Facebook.createLoginButton()) on to your view and, when the user clicks it, we’ll handle calling authorize for you. Either way, you also need to set Titanium.Facebook.appid to your Facebook application id before initiating authorization. Also, if you need more than basic permissions, be sure to set the Titanium.Facebook.permissions property to an array of the permissions you need.

Android authentication looks pretty much the same as it always did: it pops up a dialog with a WebView that loads a facebook.com login page. In fact, this dialog comes entirely from Facebook’s own Android SDK, upon which we’ve built our module. As an alternative to this dialog, we also support Facebook’s “Single-Sign-On” (SSO), which will use the official, native Facebook Android application — if it’s installed — to walk the user through authorizing your application. You can read more about SSO in Facebook’s own mobile apps guide. We support SSO in both Android and iOS, however in our Android implementation we turn off SSO by default because things get a bit hairy if you don’t setup your Facebook app (not your mobile app, your Facebook app) perfectly to support SSO. If you’re sure everything is setup correctly and you want to enable SSO in your Titanium Android app, set Titanium.Facebook.forceDialogAuth to false (it is true by default, meaning it forces the dialog-based login fields rather than SSO via the Facebook phone app.)

iOS Facebook authentication in Titanium requires a bit more setup for devices that support multi-tasking. If the official iOS Facebook app is available on the device then authentication will occur via that app; this is the “Single-Sign-On” mentioned earlier. Otherwise, Safari is used. Either way, the authentication is done externally of your app, and is now entirely managed by Facebook. This means that your app will lose control of user interactions through the Facebook login process, but will immediately be reactivated upon the completion of the login process, at which time your login listeners will be fired. (Note that iOS devices that don’t support multi-tasking — and any device running a pre-4.0 OS — will automatically do authentication the “classic” way, via a window that appears inside your app.)

Because the iOS Facebook login process requires some additional information about how to restart your app from the Facebook application or Safari, you will need to make some changes to your tiapp.xml (or Info.plist) in addition to the changes to your app to match with the new API (more on that later). In particular:

Note that this property is ONLY to tell the Facebook authentication process
how to restart your app: It does not tell the Titanium framework what your
app ID is. You will still need to set the Titanium.Facebook.appid property.

If you use Info.plist:

You’ll need to edit the CFBundleURLSchemes array to include the URL that
Facebook uses to restart your app after login is completed:

New Facebook API Methods

Beyond the changes to authentication discussed above, we’ve also gutted most of our old Titanium.Facebook methods and replaced them with APIs that better match Facebook’s most current native SDKs. If you’re familiar with modern Facebook mobile development outside of Titanium, then you know that there are generally three approaches to getting or submitting data from/to Facebook:

Graph API, which is what Facebook very much wants you to use instead of their…

REST API, which they now refer to as the “Old REST API”: a nice hint that you should be using the Graph API!

Dialogs, which are web-based dialog windows emanating from facebook.com.

Titanium now has analogs for each of these:

Use Titanium.Facebook.requestWithGraphPath(...) for Graph API calls.

Use Titanium.Facebook.request(...) for Old REST API calls.

Use Titanium.Facebook.dialog(...) to display official Facebook dialog windows.

The old Titanium.Facebook methods publishStream, query and execute are gone, but you can easily reproduce their behavior with our new methods. For example, the old query method performed FQL queries for you; you can do the same today with Titanium.Facebook.request("fql.query" ...) — see our KitchenSink example. Similarly, the fuctionality of the old publishStream method can be achieved via Titanium.Facebook.dialog("feed", ...) or, if you wish to publish directly without a dialog, use Titanium.Facebook.requestWithGraphPath("me/feed", ...) such as in the following code sample (a variation of which is also in KitchenSink):

We expect our changes will lead to better integration of Facebook functionality with your Titanium-based applications. By more closely following the official Facebook mobile SDKs, we believe that we’ve made it easier for you to take what you learn from Facebook’s own documentation and apply it in Titanium.