Implementing Facebook

Including the Plugin

As with all Corona plugins, you must include the Facebook plugin within the plugins table of build.settings:

settings = {

    plugins =
    {
        ["plugin.facebook.v4"] =
        {
            publisherId = "com.coronalabs"
        },
    },
}

Then, you must require() the plugin in any module where you need to access its methods and properties:

local facebook = require( "plugin.facebook.v4" )

User Experience

The user experience for different components of the Facebook plugin vary depending on the presence of a native Facebook app. In many cases, if a native Facebook app is on the device, operations like logging in or presenting the Share Dialog may try to redirect the heavy lifting to the Facebook app. The cases where a redirect to the Facebook app occurs has changed a lot throughout the history of the Facebook SDK, so your app should be prepared for a Facebook operation to suspend and then resume your app after the Facebook operation completes.

iOS Requirements

If your app is for iOS, you must include specific aspects within your build.settings file to ensure that the native Facebook app functions properly. Please see the plugin documentation for details.

settings = {

    iphone =
    {
        plist =
        {
            FacebookUrlSchemeSuffix = "suffix",
            ["URL types"] = 
            {
                item = 
                {
                    ["URL Schemes"] = { ["Item 0"] = "fbXXXXXXXXXXsuffix" },  -- Replace XXXXXXXXXX with your Facebook App ID
                },
            },
            
            MinimumOSVersion = "8.0",
            UIApplicationExitsOnSuspend = false,
            FacebookAppID = "XXXXXXXXXX",  -- Replace XXXXXXXXXX with your Facebook App ID
            CFBundleURLTypes =
            {
                { CFBundleURLSchemes = { "fbXXXXXXXXXXsuffix", } }  -- Replace XXXXXXXXXX with your Facebook App ID
            },
        }
    }
}

Android Requirements

On Android, Facebook uses your app Package Name, for example com.yoursite.yourapp. To ensure that the native Facebook app functions properly, you must provide Facebook's portal with two important pieces of information — these include the Class Name of com.ansca.corona.CoronaActivity and the Key Hash gathered from the keystore you built your app with. These are discussed in the Facebook Portal Setup guide.

Furthermore, the Facebook v4 plugin needs to know about your unique Facebook App ID (facebookAppId):

settings = 
{
    android =
    {
        facebookAppId = "XXXXXXXXXX",  -- Replace XXXXXXXXXX with your Facebook App ID
    },
}

Logging In/Out

Logging in to Facebook is accomplished through facebook.login(). If you didn't already set a listener function via facebook.setFBConnectListener(), you can set it by passing the listener reference as the first argument to facebook.login()

Secondly, you can request an array of permissions. Both read-only and publishable permissions can be specified, with some caveats which are outlined in the facebook.login() documentation.

Putting these two aspects together, a login call might look like this:

facebook.login( facebookListener, { "email", "user_birthday" } )

Logging the user out is even easier. To disconnect the app from Facebook's services, simply call facebook.logout(). Note, however, that this does not log the device's user out of Facebook entirely — if the user is logged into Facebook through a native Facebook app or the device's browser, they will remain logged in via those means.

facebook.logout()

Facebook Listener

All Facebook requests will call the listener function you passed to facebook-v4.login() or set via facebook.setFBConnectListener(). For example:

local json = require( "json" )

local function facebookListener( event )

    print( "event.name:" .. event.name )  -- "fbconnect"
    print( "isError: " .. tostring( event.isError ) )
    print( "didComplete: " .. tostring( event.didComplete ) )
    print( "event.type:" .. event.type )  -- "session", "request", or "dialog"

    -- event.type of "session" covers various login/logout events
    if ( "session" == event.type ) then
        -- event.phase may be "login", "loginFailed", "loginCancelled", or "logout"
        if ( "login" == event.phase ) then
            local access_token = event.token
            -- Code for tasks following a successful login
        end

    -- event.type of "request" handles calls to various Graph API functionalities
    elseif ( "request" == event.type ) then
        if not event.isError then
            local response = json.decode( event.response )
            -- Process response data here
        end

    -- event.type of "dialog" indicates standard popup boxes that can be displayed
    elseif ( "dialog" == event.type ) then
        print( "dialog", event.response )
        -- Handle dialog results here
    end
end

Making Requests

To make different Graph API requests, use the facebook.request() call. By default, this call makes HTTP GET requests to Facebook. If you wish to use another method, set the second parameter (httpMethod) to a value outlined in the facebook.request() documentation.

facebook.request( path [, httpMethod] [, params] )

The only required parameter is path which is based on the Facebook Graph API path. This will typically be the REST object that you want to access. For example, the following command will retrieve the latest posts from the user's account feed:

facebook.request( "me/feed" )

Some Graph API calls also require parameters to be passed to facebook.request(). This is done via the optional params table, for instance:

facebook.request( "me/feed", "POST", { message="Hello Facebook" } )

To upload a photo to your Facebook photo album, the params table can be filled in based on the standard Graph API parameters found here:

local attachment = {
    caption = "Corona icon file",
    url = "http://www.coronalabs.com/links/demo/Corona90x90.png",
}
facebook.request( "me/photos", "POST", attachment )

When facebook.request() calls complete, your Facebook listener function will be called with an event.type of "request". Facebook generally returns your data as event.response, a JSON-encoded table of data. To convert this into a Lua table, call json.decode(), remembering to first require() the JSON library:

local json = require( "json" )

local data = json.decode( event.response )

To learn more about which requests, parameters, and data Facebook provides, please see the Facebook Graph API documentation.

Using Dialogs

Facebook requires that some tasks be done through dialogs they control. To use a dialog, call the facebook.showDialog() function:

facebook.showDialog( action, params )

For this call, the action parameter specifies the dialog type:

• The Share Dialog displays the Facebook dialog for sharing content. For example, if you wanted to post a link to your Facebook wall and send a message along with it, you could do something like:

facebook.showDialog( "link",
    {
        name = "Implementing Facebook with Corona",
        link = "https://docs.coronalabs.com/guide/social/usingFacebook/index.html"
    })

• The Game Request Dialog displays a native view which allows the user to send game requests to their choice of friends. For instance:

facebook.showDialog( "requests",
    { 
        message = "You should download this game!",
        filter = "APP_NON_USERS"
    })

Observe how the params argument is a table of key/value pairs which gets passed to the Facebook API call. The keys that you pass correspond to specific options which are available for the dialog. See the facebook.showDialog() documentation for details.

Published Installs

While not part of the Graph API, Published Installs is a way for apps to participate in Facebook's mobile ad campaign which can report (to Facebook) that the app has been installed. This process is simple and there is no callback information or need to call facebook.login() — just call facebook.publishInstall():

facebook.publishInstall()