The Facebook module is used for connecting your application with Facebook. This module supports the following features:

• Logging in to Facebook and authorizing your application
• Requesting read and publish permissions
• Refreshing existing permission
• Making requests through the Facebook Graph API using the requestWithGraphPath method
• Posting web and native share dialogs
• Posting send request dialogs
• Like button

Note that the min SDK for this module is 5.0.0.GA and later. You do not need to download or unpack it. Edit the modules section of your tiapp.xml file to include this module:

<modules>
    <module platform="android">facebook</module>
    <module platform="iphone">facebook</module>
</modules>

Also you will need a Facebook App ID ready. To create a Facebook App ID, go to the Facebook Developer App: developers.facebook.com/apps

On the iOS platform, add the following property to the <ios><plist><dict> section in tiapp.xml:

<key>FacebookAppID</key>
<string>1234567891011</string>
<key>FacebookDisplayName</key>
<string>SomeName</string>

where SomeName is exactly as appears in the Facebook developer settings page

Also make sure you have a URL Scheme in tiapp.xml that looks like fb1234567891010. See Facebook docs for details on this. Add an entry to <ios><plist><dict> that looks like this, modify it for your app:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>com.appcelerator.kitchensink</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>kitchensink</string>
            <string>fb134793934930</string>
        </array>
    </dict>
</array>

To define a url scheme suffix for multiple apps sharing the same facebook app ID, simply add the suffix (in lower case and must start with a letter) to the relevant string under the CFBundleURLSchemes key. In this example, it will look like fb134793934930foo if you are adding the suffix foo. This will also require additional configurations in the facebook dashboard, see https://developers.facebook.com/docs/ios/troubleshooting#sharedappid for details.

To enable the use of Facebook dialogs (e.g., Login, Share), you also need to include the following key and values in tiapp.xml to handle the switching in and out of your app:

<key>LSApplicationQueriesSchemes</key>
    <array>
        <string>fbapi</string>
        <string>fb-messenger-api</string>
        <string>fbauth2</string>
        <string>fbshareextension</string>
    </array>

For iOS9 and titanium 5.0.0.GA and above, App Transport Security is disabled by default. If you choose to enable it, you have to set the following keys and values in tiapp.xml:

<key>NSAppTransportSecurity</key>
    <dict>
        <key>NSExceptionDomains</key>
            <dict>
                <key>facebook.com</key>
                    <dict>
                        <key>NSIncludesSubdomains</key> <true/>        
                        <key>NSExceptionRequiresForwardSecrecy</key> <false/>
                    </dict>
                <key>fbcdn.net</key>
                    <dict>
                        <key>NSIncludesSubdomains</key> <true/>
                        <key>NSExceptionRequiresForwardSecrecy</key>  <false/>
                    </dict>
                <key>akamaihd.net</key>
                    <dict>
                        <key>NSIncludesSubdomains</key> <true/>
                        <key>NSExceptionRequiresForwardSecrecy</key> <false/>
                    </dict>
            </dict>
    </dict>

On the android platform, in tiapp.xml or AndroidManifest.xml you must declare the following inside the <application> node

<activity android:name="com.facebook.LoginActivity" android:theme="@android:style/Theme.Translucent.NoTitleBar" android:label="YourAppName"/>
<activity android:name="com.facebook.FacebookActivity" android:theme="@android:style/Theme.Translucent.NoTitleBar" android:label="YourAppName" android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation" />

You must also reference the string containing your Facebook app ID, inside the <application> node as well:

<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/app_id"/>

The app id goes into the the file /platform/android/res/values/strings.xml, where you should define

<resources><string name="app_id">1234567890123456</string></resources>

where the number is of course the app ID. The app ID is not set programmatically.

Facebook requires you to add the Key Hash of the Android app in order for you to use the module. Steps to get the Key Hash as follows. Alternatively, if you do not have the correct Key Hash on the Android App, the App will give an error message when you login with the Key Hash of the App which you can then copy.

If you are using Titanium SDK 5.0.2.GA, use the path as follows. On OS X, run:

keytool -exportcert -alias androiddebugkey -keystore ~/Library/Application\ Support/Titanium/mobilesdk/osx/5.0.2.GA/dev_keystore | openssl sha1 -binary | openssl base64

You would also require, to fill up the Google Play Package Name which is the Application ID and the Class Name which is the Application ID followed by the Application Name concatenated with the word Activity. Example, an App called Kitchensink with Application ID of com.appcelerator.kitchensink will have the Class Name as com.appcelerator.kitchensink.KitchensinkActivity. Alternatively, you can check the Class Name in /build/android/AndroidManifest.xml which is generated when you build the project. The launcher activity is the Class Name of the Application.

For more info, please see https://developers.facebook.com/docs/android/getting-started

Unlike iOS, where the entire app is active in memory, in Android only a single Activity is active at any time. In Titanium, an Activity corresponds to a standalone (i.e. not a Tab window) Ti.UI.Window or Ti.UI.TabGroup. The Facebook SDK contains tools to synchronize state between the various activities in the app, and this module implements that functionality, but for this to work we need to tell the module which is the currently active Activity. Thus the following is required:

All Windows/TabGroup in your app must create a proxy, e.g. :

win1.fbProxy = fb.createActivityWorker({lifecycleContainer: win1});

where fb is the required module. We must pass to the proxy the Ti.UI.Window or Ti.UI.TabGroup that will be using the proxy, so that the proxy can attach itself to the window's or tabgroup's activity. The proxy object must be created prior to calling open() on the window or tabgroup in order to make sure the Activity onCreate event is captured correctly. This proxy has no APIs (new since version 3.20.05), its sole function is to signal the Facebook SDK for the various Activity transitions. So just create it and attach it to the window/tabgroup.

To use Facebook, a user must log in to Facebook and explicitly authorize the application to perform certain actions, such as accessing profile information or posting status messages.

There are two ways to initiate the login process:

Create a Facebook LoginButton to allow the user to log in if desired. You can also add either readPermissions or publishPermissions, otherwise the default is request for public_profile. Doing so will let the LoginButton request for permissions when logging in. Note that Facebook does not support setting both parameters at the same time to the LoginButton. For a complete list of permissions, see the official Facebook Permissions Reference.

    var fb = require('facebook');
    fb.initialize();
    var loginButton = fb.createLoginButton({
        readPermissions: ['read_stream','email']
    });

Call authorize to prompt the user to login and authorize the application. This method can be considered if you prefer to use custom UI instead of the loginButton.

    var fb = require('facebook');
    fb.permissions = ['email'];
    fb.initialize(); 
    facebook.authorize();

Which approach you take depends on your UI and how central Facebook is to your application. Both approaches fire a login event.

For a complete list of permissions, see the official Facebook Permissions Reference.

requestNewReadPermissions

var fb = require('facebook');
fb.requestNewReadPermissions(['read_stream','user_hometown', etc...], function(e){
    if(e.success){
        fb.requestWithGraphPath(...);
    } else if (e.cancelled){
        ....
    } else {
        Ti.API.debug('Failed authorization due to: ' + e.error);
    }
});

requestNewPublishPermissions

You must use the audience constants from the module, either AUDIENCE_NONE, AUDIENCE_ONLY_ME, AUDIENCE_FRIENDS, or AUDIENCE_EVERYONE. Note that it is not an error for the user to 'Skip' your requested permissions, so you should check the module's permissions property following the call.

var fb = require('facebook');
fb.requestNewPublishPermissions(['read_stream','user_hometown', etc...], fb.AUDIENCE_FRIENDS, function(e){
    if(e.success){
        fb.requestWithGraphPath(...);
    } else if (e.cancelled){
    ....
    } else {
        Ti.API.debug('Failed authorization due to: ' + e.error);
    }
});

Facebook now grants total control over granted permissions, and if the user modified the permissions outside of your app your cached token may not be updated. To get the current permissions from Facebook's servers you can call fb.refreshPermissionsFromServer(). You may listen for the tokenUpdated event to be notified of this operation's successful completion.

The Facebook Graph API is the preferred method for getting information about a user's friends, news feed, and so on. Each object in the Facebook social graph is represented by a graph API object, such as a user, photo, or status message. The Graph API allows you to make requests on behalf of the user, such as posting a picture or status message. Use the requestWithGraphPath method to make a request to the Graph API.

For details on each of the Graph API objects and the supported operations, see the official Facebook Graph API documentation. Note: fql is no longer supported by Facebook beginning April 2015, so this module does not support fql. This module supports Facebook Graph API v2.2 and above.

Example 1:

    var fb = require('facebook');
    fb.requestWithGraphPath('me/groups', {}, 'GET',  function(r)
    {
        if (!r.success) {
            if (r.error) {
                alert(r.error);
            } else {
                alert("call was unsuccessful");
            }
            return;
        }
        var result = JSON.parse(r.result).data;
    }

Example 2:

    var fb = require('facebook');
    fb.requestWithGraphPath('me/picture', {'redirect': 'false'}, 'GET',  function(r)
    {
        if (!r.success) {
            if (r.error) {
                alert(r.error);
            } else {
                alert("call was unsuccessful");
            }
            return;
        }
        var result = JSON.parse(r.result)
    }

You don't need permissions. You can either use presentShareDialog which requires facebook app to be preinstalled, or presentWebStareDialog that uses the web browser instead. Both approaches fire a shareCompleted event. To share a user's status just call fb.share({}); To share a link call fb.share({url: 'http://example.com' }); To share more information, example:

    var fb = require('facebook');
    fb.presentShareDialog({
        link: 'https://appcelerator.com/',
        title: 'great product',
        description: 'Titanium is a great product',
        picture: 'http://www.appcelerator.com/wp-content/uploads/scale_triangle1.png'
    });

Sends an application request. Fires a sendRequestCompleted event. You can optionally include a title key with the title string, or customized parameters in the data dictionary. To preselect users to send the invite to, you can optionally add a to key with a string of values containing the facebook ids, seperated by commas. See below for example. See official Facebook Dialogs documentation for more details.

    var fb = require('facebook');
    fb.presentSendRequestDialog({
        message: 'Go to https://appcelerator.com/',
        title: 'Invitation to Appcelerator',
        recipients: ['123456789', '123456788'],
        data: {
            badge_of_awesomeness: '1',
            social_karma: '5'
        }
    });

We can create a Like button just like any other view, with specific parameters documented in Facebook docs. Note there is no completion callback or event, and Facebook policies state "If you use the Like button on iOS or Android, don’t collect or use any information from it."

var likeButton = fb.createLikeButton({
    objectId: "https://www.facebook.com/appcelerator", // URL or Facebook ID
    foregroundColor: "white", // A color in Titanium format - see Facebook docs
    likeViewStyle: 'box_count', // standard, button, box_count - see FB docs
    auxiliaryViewPosition: 'inline', // bottom, inline, top - see FB docs
    horizontalAlignment: 'left', // center, left, right - see FB docs,
    soundEnabled: true // boolean, iOS only
});
win.add(likeButton);

• Note that the FBSDKCoreKit.framework, FBSDKLoginKit.framework, FBSDKShareKit.framework directory is the prebuilt Facebook SDK directly downloaded from Facebook, zero modifications.
• Facebook is moving away from the native iOS login, and towards login through the Facebook app. The default behavior of this module is the same as in the Facebook SDK: app login with a fallback to webview. The advantages of the app login are: user control over individual permissions, and a uniform login experience over iOS, Android, and web.
• AppEvents are automatically logged. Check out the app Insights on Facebook. We can also log custom events for Insights.
• Choose to use LogInButton, rather than a customized UI, since it's directly from facebook and it's easier in maintaining facebook sessions.

The error handling adheres to the new Facebook guideline for events such as login, shareCompleted and requestSendCompleted. Here is how to handle login events:

    var fb = require('facebook');
    fb.addEventListener('login',function(e) {
        // You *will* get this event if loggedIn == false below
        // Make sure to handle all possible cases of this event
        if (e.success) {
            alert('login from uid: '+e.uid+', name: '+JSON.parse(e.data).name);
            label.text = 'Logged In = ' + fb.loggedIn;
        }
        else if (e.cancelled) {
            // user cancelled 
            alert('cancelled');
        }
        else {
            alert(e.error);         
        }
    });
    fb.addEventListener('logout', function(e) {
        alert('logged out');
        label.text = 'Logged In = ' + fb.loggedIn;
    });