New Facebook Modules

In this guest blog, Mark Mokryn introduced us to his new Facebook modules for Titanium. Appcelerator’s Facebook modules haven’t been updated for a long time, partly because the newer SDKs couldn’t simply be dropped into the Titanium wrapper modules but needed lots of adjustments. Mark just got several PRs accepted for Titanium 3.5.0 to make it easier to use third-part SDKs as-is. But using his private fork of Titanium 3.4.0 you can already use his new modules today! Read on to learn how..

---

Titanium’s Facebook modules are about two years old, and are missing many features developers and users expect from a Facebook-integrated app.
This post will introduce new modules to help you update your app.

Background

In April 2014 Facebook introduced a new login mechanism and Graph API 2.x, which are missing from the Titanium modules.
Other missing features are the Share Dialog, which enables sharing the user experience via the Facebook app, the Like button, App Events, and more.
The new modules enable these features for Titanium apps, and are available for both Android and iOS.

The modules are documented in the READMEs on the repositories, so in this post I will mostly provide an overview of the features as well as points to look out for.
The APIs are similar to those in Titanium’s modules, with the differences noted in the READMEs.

Login Notes

Like the original modules, these modules will also generate a “login” event if the module found a previously active session with Facebook.
An enhancement over this is that the modules allow you to control when this will occur, so you can set up your UI and event listeners prior to this event. Thus, to kick off the module, after setting your login and logout event listeners and requested permissions, call the module’s initialize() method. The login event will not occur before this.

Permissions

Facebook’s new login mechanism provides users full control over which permissions may be granted to your app. The only permission the user cannot turn down when logging in is public_profile. Therefore if you request any additional permissions, it is highly recommended that following the login event you read the module’s permissions property to get the actually granted permissions.

iOS Notes

Following the move to the new login mechanism, Facebook made the default login mechanism to be through the Facebook app, with a webview fallback (for both iOS and Android). You may however decide to use the device Facebook account login (i.e. in iOS settings) as the first option, with a fallback to the Facebook app, and then the webview. The device account login does not allow user control over the requested permissions, which may annoy users who by now are used to this. Additionally, if you request additional permissions with the device account you may also see strange wording presented to the user. Therefore, if you decide to use the device login the module is hard coded to request only the public_profile permission. On iOS this permission also include email and user_friends – unlike the app or webview login. The only advantage of the device login is that it is faster than the Facebook app. If you wish to use the device login as the preferred login method, initialize the module by fb.initialize(true);

Also note that in the case of a user changing her Facebook password, or initially refusing to login with Facebook, recovery from the device login is more complex and will often require the user to enter the iOS Facebook settings.

The iOS module works and is tested with SDK 3.4.0.GA

Install the module locally to your Titanium project, since when you build your project Xcode will look for the Facebook SDK framework in a path relative to your project path ($(SRCROOT) in module.xcconfig). If you want to install the module globally then you will need to change that line to point directly to the folder containing FacebookSDK.framework.

Android Notes

Unlike iOS apps which function as a single “process”, in Android apps use Activities, with only a single Activity running at any time. In Titanium, each standalone Window (i.e. not a Tab Window) or TabGroup corresponds to a unique Activity. Since the Facebook SDK needs to keep track of status as the app transitions between Activities, we need to create a proxy per Window or TabGroup, for example:

Note that it may be needed to attach the proxy to some other object such as the Window (e.g. this example) to prevent it from being garbage collected prior to the Window being closed, as I have seen happen on occasion.

You should create this proxy object for each Activity that needs Facebook functionality, and then use that object to access all the module methods, events, and properties.
Due to this requirement, the Android module requires SDK 3.5.0 which contains new features for Activity lifecycle events. Since 3.5.0 development is not currently stable, you may use my branch off the production 3_4_X branch. You can download this SDK prebuilt here.

App Events

Facebook provides lots of metrics for your app: number of installs, activations, informations on sessions, and more. For iOS you don’t need to do anything besides require the module. For Android, you just need to create Facebook module proxies for each Window or TabGroup. The user does not even need to be logged in with Facebook. Then visit Facebook Insights for your app and browse your data.

You can also create custom events which will be monitored, for example:

Share Dialog

The Share Dialog provides a uniform sharing experience through the Facebook app for both iOS and Android. This is unlike the Share Sheet, for example, which is supported only on iOS and by this module.

It is also more powerful than the Share Sheet, see the Facebook docs for the differences. The details are spelled out in the READMEs, and again this particular API does not require the user to login with your app to Facebook.

Next Steps

I strongly urge any apps using the Facebook modules today to upgrade now, since apps will stop working soon as Facebook removes support for Graph API 1.0. So please try out the modules, and provide feedback. And of course, help in the form of pull requests is always welcome.