facebook.* (v4a)

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

This documentation is for the Facebook v4a plugin, an updated version of the v4 plugin. This updated version is asynchronous and includes a new facebook.init() API which gives you a chance to define a specific function that will be called when initialization completes.

Facebook now requires you to include a Client Token from your App Page (Under App Settings>Advanced>Security), (see Project Settings for where to put the Token)

To utilize this version, you should update your build.settings to include "plugin.facebook.v4a" (see Project Settings), require "plugin.facebook.v4a" in all Lua modules which use Facebook (see Syntax), and integrate facebook.init() into your existing project code.

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.v4a" )

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.v4a"] =
        {
            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 =
        {
            FacebookAppID = "XXXXXXXXXX",  -- Replace XXXXXXXXXX with your Facebook App ID
            CFBundleURLTypes =
            {
                { CFBundleURLSchemes = { "fbXXXXXXXXXX", } }  -- Replace XXXXXXXXXX with your Facebook App ID
            },
            FacebookClientToken = "YYYYYYYYYYYYYY",  -- Replace YYYYYYYYYYYYYY with your Facebook Client Token
            -- Whitelist Facebook apps
            LSApplicationQueriesSchemes =
            {
                "fb",  -- Needed for the facebook-v4a.isFacebookAppEnabled() API
                "fbapi",
                "fbauth2",
                "fb-messenger-api",
                "fbshareextension"
            },
        },
    },
}

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

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

  • FacebookClientToken — Set this key to FacebookClientToken = "YYYYYYYYYYYYYY" and replace YYYYYYYYYYYYYY with your unique Facebook Client Token.

  • 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
        applicationChildElements =
        {
            -- Array of strings
            [[
                <provider android:authorities="com.facebook.app.FacebookContentProviderXXXXXXXXXX"
                          android:name="com.facebook.FacebookContentProvider" android:exported="true"/>
            ]],
                        [[
                <meta-data android:name="com.facebook.sdk.ClientToken" android:value="YYYYYYYYYYYYYYYYYYYYY"/>
            ]],
        }, -- Replace XXXXXXXXXX with your Facebook App ID and YYYYYYYYYYYYYYYYYYYYY with Facebook Client Token
    },
}
Note

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

  • "android.permission.INTERNET"

Solar2D Native

iOS

If you're using Solar2D 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>FacebookAppID</key>
<!-- Replace XXXXXXXXXX with your Facebook App ID -->
<string>XXXXXXXXXX</string>
<key>FacebookClientToken</key>
<!-- Replace YYYYYYYYYYYYYYYYYYYYY with your Facebook Client Token -->
<string>YYYYYYYYYYYYYYYYYYYYY</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-Solar2D 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 Solar2D 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 Solar2D Native and copy only the "plugin.facebook.v4a.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 and Facebook Client Token.
<!-- Replace XXXXXXXXXX with your Facebook App ID -->
<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="\ XXXXXXXXXX"/>
<!-- Replace XXXXXXXXXX with your Facebook ClientToken-->
<meta-data android:name="com.facebook.sdk.ClientToken" 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 Settings → Basic → Display 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.v4a.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 File → New → Import 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 Solar2D 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')