facebook.* (v4)

Type Library
Revision 2017.3179
Keywords Facebook
Platforms Android, iOS
See also Facebook Portal Setup (guide)
Implementing Facebook (guide)

This documentation is for the Facebook v4 plugin. We strongly recommend that you modify your code to use the Facebook v4a plugin, an updated asynchronous version which includes a new facebook.init() API.

Overview

The Facebook plugin provides a set of APIs for accessing the Facebook social network. The functions allow a user to login/logout, post messages and images, retrieve the status of users, send game invites, and more.

Important

Your app must work properly with single-sign-on (SSO). Please read the Facebook Portal Setup guide for more information on how to implement single-sign-on in your Facebook-enabled apps.

Registration

Developing for Facebook requires that you register in the Facebook Developer Portal.

Syntax

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

Functions

Properties

Events

Project Settings

To use this plugin, add an entry into the plugins table of build.settings. When added, the build server will integrate the plugin during the build phase.

settings = {

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

iOS

If your app is for iOS, you must also include the following code in build.settings to ensure that the native Facebook app functions properly:

settings = {

    iphone =
    {
        plist =
        {
            UIApplicationExitsOnSuspend = false,
            FacebookAppID = "XXXXXXXXXX",  -- Replace XXXXXXXXXX with your Facebook App ID
            CFBundleURLTypes =
            {
                { CFBundleURLSchemes = { "fbXXXXXXXXXX", } }  -- Replace XXXXXXXXXX with your Facebook App ID
            },
            -- Whitelist Facebook apps
            LSApplicationQueriesSchemes =
            {
                "fb",  -- Needed for the facebook-v4.isFacebookAppEnabled() API
                "fbapi",
                "fbauth2",
                "fb-messenger-api",
                "fbshareextension"
            },
        },
    },
}

Notice that there are several critical parts which must be specified:

  • UIApplicationExitsOnSuspend — To ensure that Facebook can resume your app properly, you must include UIApplicationExitsOnSuspend = false. If you've set this parameter to true for some other reason, you must revert it to false (default).

  • FacebookAppID — Set this key to FacebookAppID = "XXXXXXXXXX" and replace XXXXXXXXXX with your unique Facebook App ID.

  • CFBundleURLTypes — The CFBundleURLTypes table must be declared exactly as shown and it must include a table named CFBundleURLSchemes. Inside this, include your Facebook App ID and prefix it with fb. Thus, if your App ID is 1234567890, you should specify: "fb1234567890".

  • LSApplicationQueriesSchemes — This table of whitelisted URL schemes ensures that your app and the Facebook SDK run properly together.

Android

If your app is for Android, you must also include a Facebook App ID in build.settings:

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

For Android, the following permissions/features are automatically added when using this plugin:

  • "android.permission.INTERNET"

Corona Native

iOS

If you're using Corona Native for iOS, you should ensure that the following static libraries are linked:

  • libBolts.a

  • libFBSDKCoreKit.a

  • libFBSDKLoginKit.a

  • libFBSDKShareKit.a

  • libfacebook.a

In addition, you'll need to add several properties to your Info.plist. Open the file in an external text editor and add the following XML code into it:

<key>UIApplicationExitsOnSuspend</key>
<false/>
<key>FacebookAppID</key>
<!-- Replace XXXXXXXXXX with your Facebook App ID -->
<string>XXXXXXXXXX</string>
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <!-- Replace XXXXXXXXXX with your Facebook App ID -->
            <string>fbXXXXXXXXXX</string>
        </array>
    </dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>fb</string>
    <string>fbapi</string>
    <string>fbauth2</string>
    <string>fb-messenger-api</string>
    <string>fbshareextension</string>
</array>
<key>CoronaDelegates</key>
<array>
    <string>CoronaFacebookDelegate</string>
</array>

This has all of the same critical pieces as the build.settings additions for non-Corona Native implementation, plus the addition of the CoronaDelegates key with CoronaFacebookDelegate in its array. This allows Facebook login to work as well as suspending/resuming your app while Facebook is active.

Android

If you're using Corona Native for Android, there are several configuration changes you'll need to make to your Android Studio project. Be sure to follow this procedure carefully as even minor mistakes can result in debugging headaches.

  1. Locate the plugin binaries package that accommodates your build of Corona Native and copy only the "plugin.facebook.v4.jar" file into your project's "libs" directory.
Note

The rest of the binaries in the Facebook plugin package will be copied/rebuilt for you later when the Facebook SDK is linked to your Android Studio project.

  1. Add the following permission to your AndroidManifest.xml:
<uses-permission android:name="android.permission.INTERNET"/>
  1. In the application element of your AndroidManifest.xml, add a meta-data tag containing your Facebook App ID.
<!-- Replace XXXXXXXXXX with your Facebook App ID -->
<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="\ XXXXXXXXXX"/>
Note

Since your Facebook App ID is a number that needs to be converted to a string for Android, the \ in the assignment of android:value is required.

  1. Similarly, add a meta-data tag containing the Display Name as posted in the Facebook Developer Portal. This can be found under SettingsBasicDisplay Name.
<!-- Replace XXXXXXXXXX with your Facebook Display Name from the Facebook Developer Portal -->
<meta-data android:name="com.facebook.sdk.ApplicationName" android:value="XXXXXXXXXX"/>
Note

The ApplicationName meta-data tag is required for using the Share Dialog.

  1. Next, add the following activities to your AndroidManifest.xml:
<activity android:name="com.facebook.FacebookActivity"
        android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation"
        android:theme="@android:style/Theme.Translucent.NoTitleBar" />
<activity android:name="plugin.facebook.v4.FacebookFragmentActivity"
        android:theme="@android:style/Theme.NoTitleBar.Fullscreen" 
        android:configChanges="keyboardHidden|screenSize|orientation"/>
  1. Download Corona's fork of the Facebook SDK for Android available here.
Important

Since Facebook v4 uses a modified version of the Facebook SDK on Android, it's important that you make a library reference to the version of the Facebook SDK that is provided on GitHub.

  1. Link in the source code for the Facebook SDK via FileNewImport Module in Android Studio. Once you're at the New Module screen, select the [...] button next to the Source Directory field and browse to the downloaded Facebook SDK noted in the step above.

  2. Find the facebook directory in the downloaded Facebook SDK. Confirm selection of that Gradle project and then click Finish on the New Module screen to import the Facebook SDK as a module for your Corona Native project.

  3. In the downloaded Facebook SDK, locate the gradle.properties file in the root directory and copy its contents to your Android Studio project's gradle.properties file.

  4. Back in Android Studio, open the build.gradle (Module: app) file and add this line to the bottom of the dependencies block:

compile project(':facebook')