# Modules.Facebook

Add-on Facebook module.

Availability

3.1.0

Extends

Titanium.Module

# Overview

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 with either the Modules.Facebook.LoginButton or programatically.
Making requests through the Facebook Graph API using the Modules.Facebook.requestWithGraphPath method.

# Getting Started

To use the Facebook module, you need a Facebook application. To create a Facebook App, go to the Facebook Developer App: developers.facebook.com/apps (opens new window).

Edit the modules section of your tiapp.xml file to include this module:

<modules>
    <!-- Add the appropriate line(s) to your modules section -->
    <module platform="android">facebook</module>
    <module platform="iphone">facebook</module>
</modules>

Instantiate the module with the require('facebook') method, then make subsequent API calls with the new Facebook object.

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

# Additional iOS Setup Steps

For the iOS platform, in the ios plist dict section of your tiapp.xml file, add the following keys:

FacebookAppID key with your Facebook App ID as the string value
FacebookDisplayName key with your Facebook App name (the one from developer.facebook.com) as the string value
CFBundleURLTypes key with a single-element array containing a dict as the value, where the dict contains:
- CFBundleURLName key with the application app ID (same value as the id in the tiapp.xml file) as the string value
- CFBundleURLSchemes key with a single-element array containing the Facebook App ID prefixed with fb as a string value

For example:

<ti:app>
    <ios>
        <plist>
            <dict>
                <key>CFBundleURLTypes</key>
                <array>
                    <dict>
                        <key>CFBundleURLName</key>
                        <!-- Application ID same as the id value in the tiapp.xml file -->
                        <string>APP_ID</string>
                        <key>CFBundleURLSchemes</key>
                        <array>
                            <!-- Prefix the Facebook App ID with 'fb' -->
                            <string>fbFACEBOOK_APP_ID</string>
                        </array>
                    </dict>
                </array>
                <key>FacebookAppID</key>
                <!-- Facebook App ID -->
                <string>FACEBOOK_APP_ID</string>
                <key>FacebookDisplayName</key>
                <!-- Facebook App Name from developer.facebook.com -->
                <string>FACEBOOK_APP_NAME</string>
            </dict>
        </plist>
    </ios>
</ti:app>

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>

If you choose to enable App Transport Security (ATS), you have to set the following keys and values in tiapp.xml <ios> section for facebook module:

<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>

# Additional Android Setup Steps

For the Android platform, you need to:

Add the Facebook Login activity to the Android manifest
Add the Facebook App ID to the Android resources string.xml file
Create a Facebook proxy and associate it with the current active activity

Modify the Android Manifest

Add the Facebook Login activity to the android manifest section of your tiapp.xml file. You may need to add the manifest and application elements.

<ti:app>
    <android xmlns:android="http://schemas.android.com/apk/res/android">
        <manifest>
            <application>
                <activity android:name="com.facebook.FacebookActivity" 
                          android:theme="@android:style/Theme.Translucent.NoTitleBar" 
                          android:label="YourAppName" 
                          android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation" />
                <meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id"/>

                <provider android:name="com.facebook.FacebookContentProvider"
                          android:authorities="com.facebook.app.FacebookContentProvider<YOUR_APP_ID>"
                          android:exported="true" />
            </application>
        </manifest>
    </android>
<ti:app>

Add the Facebook App ID to Android Resources

Add a string element to the /platform/android/res/values/strings.xml file with the name attribute set to facebook_app_id and the node text set to your Facebook App ID. Create the file if it does not exist.

<resources>
    <string name="facebook_app_id">FACEBOOK_APP_ID</string>
</resources>

Generate the Key Hashes

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.

Use the following command to generate and receive the key-hashpath of your app. To do do, replace <sdk-version> with your SDK-version and run:

keytool -exportcert -alias androiddebugkey -keystore ~/Library/Application\ Support/Titanium/mobilesdk/osx/<sdk-version>/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 <project>/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

Create a Facebook Proxy

Use the Modules.Facebook.createActivityWorker method to create a Facebook proxy. Pass the method a dictionary with the lifecycleContainer property set to the current active instance of a standalone Window (window not contained in a tab group) or TabGroup. Create the proxy before calling the open() method on either the window or tab group.

The Facebook module needs to hook into the lifecycle events of the current active activity in order to synchronize its state between various activities in the application, for example, to update the label of the Login button when the user logs in or out of Facebook.

Attach the proxy to the Window or TabGroup object, so it does not get garbage collected.

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

# Module API Usage

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

Call Modules.Facebook.authorize to prompt the user to login and authorize the application. Before calling this method, set the Modules.Facebook.permissions property if additional permissions are needed.

Which approach you take depends on your UI and how central Facebook is to your application.

# Manage Read and Write Permissions

In order to read or write content to a user's Facebook page, you need to request permission from the user. You can either request permissions when the user authorizes your application or request permissions on the fly.

Before the user logs in and authorizes the application, you can request permissions for the application to use by either: Setting the Modules.Facebook.permissions property if you are using authorize() method to have the user login and authorize the application.

For a complete list of permissions, see the official Facebook Permissions Reference (opens new window)

Refresh Application Permissions

Since the user can selectively turn application permissions on and off from their Facebook page, the application may need to refresh its granted permissions.

To refresh the application's permissions, call the Modules.Facebook.refreshPermissionsFromServer method, then listen for the Modules.Facebook.tokenUpdated event to be notified when permissions are updated.

fb.addEventListener('tokenUpdated', function (e) {
    Ti.API.info('Updated permissions: ' + JSON.stringify(fb.permissions));
});
fb.refreshPermissionsFromServer();

The Share dialog prompts a person to publish an individual story or an Open Graph story to their timeline. This does not require the user to authorize your app or any extended permissions, so it is the easiest way to enable sharing.

Pass either method parameters you want to add to the post, such as a link or hashtag, or to share the user's status, do not pass any parameters to the methods. Note: The link parameter is required by the Facebook SDK.

To monitor if the share request succeeded or not, listen to the Modules.Facebook.shareCompleted event.

fb.addEventListener('shareCompleted', function (e) {
    if (e.success) {
        Ti.API.info('Share request succeeded.');
    } else {
        Ti.API.warn('Failed to share.');
    }
});

fb.presentShareDialog({
    link: 'https://appcelerator.com/',
    hashtag: 'codestrong'
});

For details on the Share dialog, see the official Facebook Share Dialogs documentation (opens new window).

# Game Requests Dialog

To send a game request to a user, call the Modules.Facebook.presentSendRequestDialog method and pass the method a dictionary with the message property set the message you want to send the invited user. Optional: You can set the title property with a title string. You can also set the data property with a dictionary of custom parameters. If you want to preselect users to send invite to, you can set the to property with string of values that are facebook ids seperated by comma.

To monitor if the request succeeded or not, listen to the Modules.Facebook.requestDialogCompleted event.

fb.addEventListener('requestDialogCompleted', function (e) {
    if (e.success) {
        Ti.API.info('request succeeded.');
    } else {
        Ti.API.warn('Failed to share.');
    }
});

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

For details on game request dialogs see the official Facebook Request Dialogs documentation (opens new window).

# Messenger Button

The Messenger button provides a quick mechanism for users to share content to the Facebook Messenger. A click on the button can share the content to multiple users.

To create a Messenger button, call the createMessengerButton() method and pass the "mode" and "style" properties:

var messengerButton = fb.createMessengerButton({
    mode: fb.MESSENGER_BUTTON_MODE_RECTANGULAR
    style: fb.MESSENGER_BUTTON_STYLE_BLUE
});
win.add(messengerButton);

For more information, see the MessengerButton API reference.

The Ti.Facecebook iOS version 10.0.0 and later supports the loginTracking property in the Modules.Facebook.LoginButton.loginTracking and as a top-level property Modules.Facebook.loginTracking. You can choose between the two constants Modules.Facebook.LOGIN_TRACKING_ENABLED (default) and Modules.Facebook.LOGIN_TRACKING_LIMITED.

For more information, see the Login Tracking API reference (opens new window) and review the constants above.

# Examples

# Authorize

Shows official Facebook dialog for logging in the user and prompting the user to approve your requested permissions. Listen for the module's Modules.Facebook.login event to determine whether the request succeeded.

var fb = require('facebook');
fb.initialize();
fb.addEventListener('login', function (e) {
    if (e.success) {
        alert('Logged in with User ID: ' + 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.authorize();

# Logout

Logout the user and forget the authorization token. The Modules.Facebook.logout event is fired after the user is logged out.

fb.addEventListener('logout', function (e) {
    alert('Logged out');
});
fb.logout();

# Authorize/Logout Using the Facebook LoginButton

You can use the the native Facebook Modules.Facebook.LoginButton to allow the user to log in as required. The button updates its state automatically depending on whether the user is logged in or not. When the user is logged in, then the button will show "Logout", and vice-versa.

Note that you don't need to set a click listener or anything else on the button. To be notified when the user logs in or out, add event listeners for the Modules.Facebook.login and Modules.Facebook.logout events provided by the Facebook module, as in the example below.

// Don't forget to set your requested permissions, else the login button won't be effective.
var win = Ti.UI.createWindow({ backgroundColor: 'white' });
var fb = require('facebook');

fb.addEventListener('login', function (e) {
    if (e.success) {
        alert('Logged in');
    }
});
fb.addEventListener('logout', function (e) {
    alert('Logged out');
});

if (Ti.Platform.name === 'android') {
    win.fbProxy = fb.createActivityWorker({ lifecycleContainer: win });
}

// Add the button.  Note that it doesn't need a click event listener.
win.add(fb.createLoginButton({
        readPermissions: ['read_stream','email'],
        top: 50
}));

win.open()

# Simple Graph API Call

This example makes a call to the "me" graph path, which represents the current user. The JSON results are simply displayed in an alert. This example assumes the user is already logged in. You can check this with Modules.Facebook.loggedIn.

fb.requestWithGraphPath('me', {}, 'GET', function (e) {
    if (e.success) {
        alert(e.result);
    } else if (e.error) {
        alert(e.error);
    } else {
        alert('Unknown response');
    }
});

# Post a Photo Using the Graph API from the Gallery.

This example posts a photo to the user's account using the Graph API. This requires the "publish_actions" permission.

var b1 = Ti.UI.createButton({
    title: 'Upload Photo from Gallery with Graph API'
});

b1.addEventListener('click', function () {
    Titanium.Media.openPhotoGallery({
        success: function (event) {
            b1.title = 'Uploading Photo...';
            var data = { picture: event.media };
            // If publish_actions permission is not granted, request it
            if (fb.permissions.indexOf('publish_actions') === -1) {
                fb.requestNewPublishPermissions(['publish_actions'], fb.AUDIENCE_FRIENDS, function (e) {
                    if (!e.success) {
                        Ti.API.info('Publish permission error');
                        return;
                    }
                    if (e.cancelled) {
                        Ti.API.info('Publish permission cancelled');
                        return;
                    }
                    
                    Ti.API.info('Permissions: ' + fb.permissions);
                    fb.requestWithGraphPath('me/photos', data, 'POST', showRequestResult);
                });
            } else {
                fb.requestWithGraphPath('me/photos', data, 'POST', showRequestResult);
            }
        },
        error: function (e) {
            Ti.API.error('Error opening photo gallery: ' + e.error);
        }
    });
});

For more information on posting photos, see:

Photo in the Facebook Graph API Reference (opens new window)

# Post a Photo Using the Graph API with an image in resources directory

This example posts a photo to the user's account using the Graph API. This requires the "publish_actions" permission.

var b2 = Ti.UI.createButton({
    title: 'Upload Photo from file with Graph API',
    left: 10, 
    right: 10, 
    top: 90, 
    height: 80
});

b2.addEventListener('click', function () {
    b2.title = 'Uploading Photo...';
    var f = Ti.Filesystem.getFile(Ti.Filesystem.resourcesDirectory, 'images', 'flower.jpg');
    var blob = f.read();
    var data = {
        picture: blob
    };
    // If publish_actions permission is not granted, request it
    if (fb.permissions.indexOf('publish_actions') < 0) {
        fb.requestNewPublishPermissions(['publish_actions'], fb.AUDIENCE_FRIENDS, function (e) {
            if (e.success) {
                Ti.API.info('Permissions: ' + fb.permissions);
                fb.requestWithGraphPath('me/photos', data, 'POST', showRequestResult);
            }
            if (e.error) {
                Ti.API.info('Publish permission error');
            }
            if (e.cancelled) {
                Ti.API.info('Publish permission cancelled');
            }
        });
    } else {
        fb.requestWithGraphPath('me/photos', data, 'POST', showRequestResult);
    }
});

For more information on posting photos, see:

Photo in the Facebook Graph API Reference (opens new window)

This example shows how to show a basic Share Dialog.

var button = Ti.UI.createButton({
    title: 'Share URL with Share Dialog'
});

button.addEventListener('click', function () {
    fb.presentShareDialog({
        link: 'https://appcelerator.com/',
        hashtag: 'codestrong'
    });
});

For more information on Facebook Dialogs, see:

Facebook Share Dialog Reference (opens new window)

This example shows how to share images, GIF's and videos to the Facebook messenger.

var btn = Ti.UI.createButton({
    title: 'Share media to messenger'
});
btn.addEventListener('click', function (e) {
    var media = [
        Ti.UI.createView({ height: 30, width: 30,backgroundColor: '#ff0' }).toImage(), // Image blob
        Ti.Filesystem.getFile(Ti.Filesystem.resourcesDirectory, 'test.gif').read(), // GIF Blob
        Ti.Filesystem.getFile(Ti.Filesystem.resourcesDirectory, 'movie.mp4').read() // Video Blob
    ];

    var options = Ti.UI.createOptionDialog({
        options: ['Photo', 'GIF', 'Video', 'Cancel'],
        cancel: 3
    });
    options.addEventListener('click', function (e) {
        if (e.index == 3) {
            return;
        }
        FB.shareMediaToMessenger({
            media: media[e.index],
            metadata: 'Ti rocks!',
            link: 'https://appcelerator.com',
        });
    });
    options.show();
});

For more information on sharing media to the Facebook Messenger, see:

Facebook Messenger Reference (opens new window)

# Requesting additional permissions

This example shows how to use the requestNewPublishPermissions method to request additional permissions to publish a post to the user's wall.

fb.requestNewPublishPermissions(['publish_actions'], fb.AUDIENCE_FRIENDS, function (e) {
    if (e.success) {
        fb.requestWithGraphPath('me/feed', null, 'POST', showRequestResult);
    } else {
        Ti.API.debug('Failed authorization due to: ' + e.error);
    }
});

# Properties

# accessToken READONLY

Availability

3.1.0

accessToken :String

OAuth token set after a successful authorize.

# accessTokenActive READONLY

Availability

7.4.0

accessTokenActive :Boolean

Returns true if the accessToken is not null AND not expired.

# accessTokenExpired READONLY

Availability

7.4.0

accessTokenExpired :Boolean

Returns whether the accessToken is expired by checking its expirationDate property.

# appID

Availability

3.1.0

appID :String

If not explicitly set, the default will be read from the application's plist (FacebookAppID) which is the recommended way.

Since Titanium SDK 6.2.0, this property also has a getter to return the currently set appID.

# canPresentOpenGraphActionDialog READONLY

Availability

4.0.0

canPresentOpenGraphActionDialog :Boolean

Checks if the device can support the use of the Facebook Open Graph action dialog from the Facebook App.

# expirationDate READONLY

Availability

3.1.0

expirationDate :Date

Time at which the accessToken expires.

# loggedIn READONLY

Availability

3.1.0

loggedIn :Boolean

Indicates if the user is logged in.

# loginTracking

Availability

10.0.0

loginTracking :Number

Gets or sets the desired tracking preference to use for login attempts.

This API can be assigned the following constants:

Default: Modules.Facebook.LOGIN_TRACKING_ENABLED

# permissions

Availability

3.1.0

permissions :Array<String>

Array of permissions to request for your app.

Be sure the permissions you want are set before calling authorize.

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

# iOS Platform Notes

On iOS, do not request any write permissions before calling the authorize() method. Use the requestNewPublishPermissions to request write permissions once the user authorizes the application.

Prior to Release 4.0.0

To use the build-in iOS 6 login, this property cannot contain any of the following: offline_access, publish_actions, publish_stream, publish_checkins, ads_management, create_event, rsvp_event, manage_friendlists, manage_notifications, or manage_pages.

# uid READONLY

Availability

3.1.0

uid :String

Unique user ID returned from Facebook.

# Methods

# authorize

Availability

3.1.0

authorize() → void

Prompts the user to log in (if not already logged in) and authorize your application. You can also use Modules.Facebook.LoginButton to log in.

Be sure to set your required permissions before calling authorize.

A login event is generated to indicate a successful or unsuccessful login attempt.

# iOS Platform Notes

On iOS, do not request any write permissions before calling this method. Use the requestNewPublishPermissions to request write permissions once the user authorizes the application.

Returns

Type: void

# createActivityWorker

Availability

4.0.0

createActivityWorker(parameters) → Titanium.Proxy

Creates a Facebook proxy to hook into the activity of either a standalone Titanium.UI.Window (not inside a TabGroup) or Titanium.UI.TabGroup.

Set the lifecycleContainer property in the dictionary passed to the method to either the current active instance of a Titanium.UI.Window or Titanium.UI.TabGroup in order to monitor the activity's lifecycle events, required by Facebook to synchronize its state between various activities in the application.

The proxy object must be created before calling the open() method on the associated Window or TabGroup.

Parameters

Name	Type	Description
`parameters`	Dictionary<Titanium.Proxy>	Properties to set on a new object, including any defined by Titanium.Proxy except those marked not-creation or read-only. Note: You must set the `lifecycleContainer` property.

Returns

Type: Titanium.Proxy

# createLoginButton

Availability

3.1.0

createLoginButton([parameters]) → Modules.Facebook.LoginButton

Creates and returns an instance of Modules.Facebook.LoginButton.

Parameters

Name	Type	Description
`parameters`	Dictionary<Modules.Facebook.LoginButton>	Properties to set on a new object, including any defined by Modules.Facebook.LoginButton except those marked not-creation or read-only.

Returns

Type: Modules.Facebook.LoginButton

# fetchDeferredAppLink

Availability

5.4.0

fetchDeferredAppLink(callback) → void

Fetch the deferred app link

Deferred deep linking allows you to send people to a custom view after they installed your app via the app store.

Parameters

Name	Type	Description
`callback`	Callback<FacebookDeferredAppLinkResponse>	Callback to invoke when the request completes.

Returns

Type: void

# initialize

Availability

4.0.0

initialize() → void

Loads a cached Facebook session if available, then fires the login event.

Be sure to set your login and logout event listeners before calling initialize.

**Note: This method needs to be called before calling authorize in order to be handle the auth-flow correctly. Otherwise, you might see a white screen without any response.

Returns

Type: void

# logCustomEvent

Availability

4.0.0

logCustomEvent(event[, valueToSum[, params]]) → void

Logs a custom event to Facebook.

From the Facebook API Reference:

Events are not sent immediately when logged. They're cached and flushed out to the Facebook servers in a number of situations:

when an event count threshold is passed (currently 100 logged events).
when a time threshold is passed (currently 15 seconds).
when an app has gone to background and is then brought back to the foreground.

Some things to note when logging events:

There is a limit on the number of unique event names an app can use, on the order of 300.
Event names must be between 2 and 40 characters and must consist of alphanumeric characters, _, - or spaces.

Parameters

Name	Type	Description
`event`	String	Arbitrary string to log as an event.
`valueToSum`	Number	An arbitrary number that can represent any value (e.g., a price or a quantity). When reported, all of the valueToSum properties will be summed together in Facebook Analytics for Apps (since 5.4.0).
`params`	Object	A dictionary object containing optional parameters (since 5.4.0).

Returns

Type: void

# logout

Availability

3.1.0

logout() → void

Clears the OAuth accessToken and logs out the user.

Returns

Type: void

# logPurchase

Availability

5.2.0

logPurchase(amount, currency[, parameters]) → void

Log a purchase of the specified amount, in the specified currency.

Parameters

Name	Type	Description
`amount`	Number	Purchase amount to be logged, as expressed in the specified currency. This value will be rounded to the thousandths place (e.g., 12.34567 becomes 12.346).
`currency`	String	Currency, is denoted as, e.g. "USD", "EUR", "GBP". See ISO-4217 for specific values.
`parameters`	Object	A dictionary object containing optional parameters (since 8.0.0 in android and since 7.0.0 in ios).

Returns

Type: void

# logPushNotificationOpen

Availability

6.1.0

logPushNotificationOpen(payload[, action]) → void

Log an app event that tracks that the application was open via Push Notification.

Parameters

Name	Type	Description
`payload`	Dictionary	Notification payload received via in the push-notification callback.
`action`	String	Name of the action that was taken.

Returns

Type: void

# presentPhotoShareDialog

Availability

7.4.0

presentPhotoShareDialog(params) → void

Opens a Facebook photo share dialog.

Note: The images parameter is required by the Facebook SDK.

Android Note: In order to share images on Android, the Facebook app needs to be installed and the "content provider" settings in your Android manifest needs to be configured:

<provider android:name="com.facebook.FacebookContentProvider"
          android:authorities="com.facebook.app.FacebookContentProvider<YOUR_APP_ID>"
          android:exported="true" />

Listen for the shareCompleted to be notified if the attempt was successful or not.

Parameters

Name	Type	Description
`params`	SharePhotoContentParams	A dictionary object containing the required and optional parameters.

Returns

Type: void

# presentSendRequestDialog

Availability

4.0.0

presentSendRequestDialog(params) → void

Opens an App Request dialog.

A requestDialogCompleted event is generated to indicate if the request attempt was successful or unsuccessful, and the resultURL.

Parameters

Name	Type	Description
`params`	RequestDialogParams	A dictionary object containing parameters.

Returns

Type: void

# presentShareDialog

Availability

4.0.0

presentShareDialog(params) → void

Opens a Facebook link share dialog.

Note: The link parameter is required by the Facebook SDK.

Listen for the shareCompleted to be notified if the attempt was successful or not.

Parameters

Name	Type	Description
`params`	ShareLinkContentParams	A dictionary object containing the required and optional parameters.

Returns

Type: void

# refreshPermissionsFromServer

Availability

4.0.0

refreshPermissionsFromServer() → void

Makes a request to Facebook to get the latest permissions granted.

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.

Listen for the tokenUpdated event to be notified if the attempt was successful.

Returns

Type: void

# requestNewPublishPermissions DEPRECATED

Availability

4.0.0

requestNewPublishPermissions(permissions, audience, callback) → void

DEPRECATED SINCE 8.2.0

Request all permissions via the permissions property before calling authorize.

Makes a request to Facebook for additional write permissions.

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.

Parameters

Name	Type	Description
`permissions`	Array<String>	Array of additional permissions to request. For a complete list of permissions, see the official Facebook Permissions Reference
`audience`	Number	The extent of the visibility write permissions will have.
`callback`	Callback<FacebookPermissionResponse>	Callback to invoke when the request completes.

Returns

Type: void

# requestNewReadPermissions DEPRECATED

Availability

4.0.0

requestNewReadPermissions(permissions, callback) → void

DEPRECATED SINCE 8.2.0

Request all permissions via the permissions property before calling authorize.

Makes a request to Facebook for additional read permissions.

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.

Parameters

Name	Type	Description
`permissions`	Array<String>	Array of additional permissions to request. For a complete list of permissions, see the official Facebook Permissions Reference
`callback`	Callback<FacebookPermissionResponse>	Callback to invoke when the request completes.

Returns

Type: void

# requestWithGraphPath

Availability

3.1.0

requestWithGraphPath(path, params, httpMethod, callback) → void

Makes a Facebook Graph API request.

If the request requires user authorization, the user must be logged in, and your app must be authorized to make the request. You can check the loggedIn property to determine if the user is logged in.

Every Facebook object has an associated path. For example, "me" requests information about the current user.

For a complete list of Graph API methods, parameters and return types, see the official Facebook Graph API documentation.

Parameters

Name	Type	Description
`path`	String	Graph API path to request.
`params`	Dictionary	A dictionary object for setting parameters required by the call, if any.
`httpMethod`	String	The HTTP method (GET/POST/DELETE) to use for the call.
`callback`	Callback<FacebookGraphResponse>	Callback to invoke when the request completes.

Returns

Type: void

# setCurrentAccessToken

Availability

6.2.0

setCurrentAccessToken(params) → void

Set a new access token for using Facebook services.

Parameters

Name	Type	Description
`params`	CurrentAccessTokenParams	A dictionary object containing required and optional parameters. Note: There is an open issue in the native Facebook SDK causing the appID from not being updated although specified in the parameters. You can use the appID setter to change the appID inside your app.

Returns

Type: void

# setPushNotificationsDeviceToken

Availability

6.1.0

setPushNotificationsDeviceToken(deviceToken) → void

Sets a device token to register the current application installation for push notifications.

Parameters

Name	Type	Description
`deviceToken`	String	Device-token received when registering for push-notifications.

Returns

Type: void

# Events

Availability

3.1.0

Fired at session login.

Properties

Name	Type	Description
success	Boolean	Indicates if the user was logged in successfully. Returns `true` if request succeeded, `false` otherwise.
cancelled	Number	Indicates if the user canceled the login request by closing the dialog.
error	String	Error message, if any returned. Will be undefined if `success` is `true`.
code	Number	Error code. Error code will be 0 if `success` is `true`, nonzero otherwise. If the error was generated by the operating system, that system's error value is used. Otherwise, this value will be -1.
uid	String	User ID returned by Facebook if the login was successful.
data	String	Data returned by Facebook when we query for the UID (using graph path "me") after a successful login. Data is in JSON format, and includes information such as user name, locale and gender.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# logout

Availability

3.1.0

Fired at session logout.

# requestDialogCompleted

Availability

4.0.2

Fired when the Send Request dialog is closed.

Properties

Name	Type	Description
success	Boolean	Returns `true` if request succeeded, `false` otherwise.
cancelled	Number	Indicates if the user canceled the request by closing the dialog.
error	String	Error message, if any returned. Will be undefined if `success` is `true`.
data	Dictionary	data returned by Facebook. See Facebook reference for details.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# shareCompleted

Availability

4.0.0

Fired when the Share dialog or Web Share dialog is closed.

Properties

Name	Type	Description
success	Boolean	Returns `true` if request succeeded, `false` otherwise.
cancelled	Number	Indicates if the user canceled the request by closing the dialog.
error	String	Error message, if any returned. Will be undefined if `success` is `true`.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# inviteCompleted

Availability

5.4.0

Fired when the Invite dialog is closed.

Properties

Name	Type	Description
success	Boolean	Returns `true` if request succeeded, `false` otherwise.
cancelled	Number	Indicates if the user canceled the request by closing the dialog.
error	String	Error message, if any returned. Will be undefined if `success` is `true`.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# tokenUpdated

Availability

4.0.0

Fired when refreshPermissionsFromServer is completed.

# Constants

# ACTION_TYPE_ASK_FOR

Availability

5.0.0

ACTION_TYPE_ASK_FOR :Number

The user is asking for an object from friends.

Use to set the actionType with presentSendRequestDialog

# ACTION_TYPE_NONE

Availability

5.0.0

ACTION_TYPE_NONE :Number

No action type.

Use to set the actionType with presentSendRequestDialog

# ACTION_TYPE_SEND

Availability

5.0.0

ACTION_TYPE_SEND :Number

The user is sending an object to the friends.

Use to set the actionType with presentSendRequestDialog

# ACTION_TYPE_TURN

Availability

5.0.0

ACTION_TYPE_TURN :Number

It is the turn of the friends to play against the user in a match.

Use to set the actionType with presentSendRequestDialog

# AUDIENCE_EVERYONE

Availability

4.0.0

AUDIENCE_EVERYONE :Number

Published content is visible to all Facebook users.

Use to set the default audience with either audience or requestNewPublishPermissions.

# AUDIENCE_FRIENDS

Availability

4.0.0

AUDIENCE_FRIENDS :Number

Published content is only visible to the user and user's friends.

Use to set the default audience with either audience or requestNewPublishPermissions.

# AUDIENCE_ONLY_ME

Availability

4.0.0

AUDIENCE_ONLY_ME :Number

Published content is only visible to the user.

Use to set the default audience with either audience or requestNewPublishPermissions.

# EVENT_NAME_ADDED_PAYMENT_INFO

Availability

8.0.0

7.0.0

EVENT_NAME_ADDED_PAYMENT_INFO :String

Log this event when the user has entered their payment info.

# EVENT_NAME_ADDED_TO_CART

Availability

8.0.0

7.0.0

EVENT_NAME_ADDED_TO_CART :String

Log this event when the user has added an item to their cart.

# EVENT_NAME_COMPLETED_REGISTRATION

Availability

8.0.0

7.0.0

EVENT_NAME_COMPLETED_REGISTRATION :String

Log this event when a user has completed registration with the app.

# EVENT_NAME_INITIATED_CHECKOUT

Availability

8.0.0

7.0.0

EVENT_NAME_INITIATED_CHECKOUT :String

Log this event when the user has entered the checkout process.

# EVENT_NAME_VIEWED_CONTENT

Availability

8.0.0

7.0.0

EVENT_NAME_VIEWED_CONTENT :String

Log this event when a user has viewed a form of content in the app.

# EVENT_PARAM_CONTENT

Availability

8.0.0

7.0.0

EVENT_PARAM_CONTENT :String

Parameter key used to specify data for the one or more pieces of content being logged about.

# EVENT_PARAM_CONTENT_ID

Availability

8.0.0

7.0.0

EVENT_PARAM_CONTENT_ID :String

Parameter key used to specify an ID for the specific piece of content being logged about.

# EVENT_PARAM_CONTENT_TYPE

Availability

8.0.0

7.0.0

EVENT_PARAM_CONTENT_TYPE :String

Parameter key used to specify a generic content type/family for the logged event.

# EVENT_PARAM_CURRENCY

Availability

8.0.0

7.0.0

EVENT_PARAM_CURRENCY :String

Parameter key used to specify currency used with logged event.

# EVENT_PARAM_NUM_ITEMS

Availability

8.0.0

7.0.0

EVENT_PARAM_NUM_ITEMS :String

Parameter key used to specify how many items are being processed.

# EVENT_PARAM_PAYMENT_INFO_AVAILABLE

Availability

8.0.0

7.0.0

EVENT_PARAM_PAYMENT_INFO_AVAILABLE :String

Parameter key used to specify whether payment info is available.

# FILTER_APP_NON_USERS

Availability

5.0.0

FILTER_APP_NON_USERS :Number

Friends not using the app can be displayed.

Use to set the filter with presentSendRequestDialog

# FILTER_APP_USERS

Availability

5.0.0

FILTER_APP_USERS :Number

Friends using the app can be displayed.

Use to set the filter with presentSendRequestDialog

# FILTER_NONE

Availability

5.0.0

FILTER_NONE :Number

No filter all friends can be displayed.

Use to set the filter with presentSendRequestDialog

Availability

6.1.0

LOGIN_BUTTON_TOOLTIP_BEHAVIOR_AUTOMATIC :Number

The default behavior. The tooltip will only be displayed if the app is eligible (determined by possible server round trip).

Availability

6.1.0

LOGIN_BUTTON_TOOLTIP_BEHAVIOR_DISABLE :Number

Force disable. In this case you can still exert more refined control by manually constructing a new login button.

Availability

6.1.0

LOGIN_BUTTON_TOOLTIP_BEHAVIOR_FORCE_DISPLAY :Number

Force display of the tooltip (typically for UI testing).

Availability

6.1.0

LOGIN_BUTTON_TOOLTIP_STYLE_FRIENDLY_BLUE :Number

Light blue background, white text, faded blue close button.

Availability

6.1.0

LOGIN_BUTTON_TOOLTIP_STYLE_NEUTRAL_GRAY :Number

Dark gray background, white text, light gray close button.

# LOGIN_TRACKING_ENABLED

Availability

10.0.0

LOGIN_TRACKING_ENABLED :Number

Use with loginTracking or the top-level loginTracking property to set the desired tracking preference.

For more information on the differences between LOGIN_TRACKING_ENABLED and LOGIN_TRACKING_LIMITED see: https://developers.facebook.com/docs/facebook-login/ios/limited-login/

# LOGIN_TRACKING_LIMITED

Availability

10.0.0

LOGIN_TRACKING_LIMITED :Number

Use with loginTracking or the top-level loginTracking property to set the desired tracking preference.

For more information on the differences between LOGIN_TRACKING_ENABLED and LOGIN_TRACKING_LIMITED see: https://developers.facebook.com/docs/facebook-login/ios/limited-login/

# MESSENGER_BUTTON_MODE_CIRCULAR

Availability

5.4.0

MESSENGER_BUTTON_MODE_CIRCULAR :Number

Use with MessengerButton.mode to specify the default send button reading "Send".

You can localize the button by localizing "Send" in your strings.xml. Learn more about that topic here.

# MESSENGER_BUTTON_MODE_RECTANGULAR

Availability

5.4.0

MESSENGER_BUTTON_MODE_RECTANGULAR :Number

Use with MessengerButton.mode to specify the default send button reading "Send".

You can localize the button by localizing "Send" in your strings.xml. Learn more about that topic here.

# SHARE_DIALOG_MODE_AUTOMATIC

Availability

6.0.0

SHARE_DIALOG_MODE_AUTOMATIC :Number

Acts with the most appropriate mode that is available.

Use with presentShareDialog.

# SHARE_DIALOG_MODE_BROWSER

Availability

6.0.0

SHARE_DIALOG_MODE_BROWSER :Number

Displays the dialog in Safari.

Use with presentShareDialog.

# SHARE_DIALOG_MODE_FEED_BROWSER

Availability

6.0.0

SHARE_DIALOG_MODE_FEED_BROWSER :Number

Displays the feed dialog in Safari.

Use with presentShareDialog.

# SHARE_DIALOG_MODE_FEED_WEB

Availability

6.0.0

SHARE_DIALOG_MODE_FEED_WEB :Number

Displays the feed dialog in a webview within the app.

Use with presentShareDialog.

# SHARE_DIALOG_MODE_NATIVE

Availability

6.0.0

SHARE_DIALOG_MODE_NATIVE :Number

Displays the dialog in the main native Facebook app.

Use with presentShareDialog.

# SHARE_DIALOG_MODE_SHARE_SHEET

Availability

6.0.0

SHARE_DIALOG_MODE_SHARE_SHEET :Number

Displays the dialog in the iOS integrated share sheet.

Use with presentShareDialog.

# SHARE_DIALOG_MODE_WEB

Availability

6.0.0

SHARE_DIALOG_MODE_WEB :Number

Displays the dialog in a web view within the app.

Use with presentShareDialog.

# Modules.Facebook

# Overview

# Getting Started

# Additional iOS Setup Steps

# Additional Android Setup Steps

# Module API Usage

# Facebook Login and Authorization

# Manage Read and Write Permissions

# Share Dialogs

# Game Requests Dialog

# Messenger Button

# Login Tracking (iOS only)

# Examples

# Authorize

# Logout

# Authorize/Logout Using the Facebook LoginButton

# Simple Graph API Call

# Post a Photo Using the Graph API from the Gallery.

# Post a Photo Using the Graph API with an image in resources directory

# Show a basic Share Dialog

# Share content to the Facebook Messenger

# Requesting additional permissions

# Properties

# accessToken READONLY

# accessTokenActive READONLY

# accessTokenExpired READONLY

# appID

# canPresentOpenGraphActionDialog READONLY

# expirationDate READONLY

# loggedIn READONLY

# loginTracking

# permissions

# iOS Platform Notes

# uid READONLY

# Methods

# authorize

# iOS Platform Notes

Returns

# createActivityWorker

Parameters

Returns

# createLoginButton

Parameters

Returns

# fetchDeferredAppLink

Parameters

Returns

# initialize

Returns

# logCustomEvent

Parameters

Returns

# logout

Returns

# logPurchase

Parameters

Returns

# logPushNotificationOpen

Parameters

Returns

# presentPhotoShareDialog

Parameters

Returns

# presentSendRequestDialog

Parameters

Returns

# presentShareDialog

Parameters

Returns

# refreshPermissionsFromServer

Returns

# requestNewPublishPermissions DEPRECATED

Parameters

Returns

# requestNewReadPermissions DEPRECATED

Parameters

Returns

# requestWithGraphPath

Parameters

Returns