Defold Facebook documentation

This extension allows you to interact with Facebook’s game connectivity features in a uniform way for games on iOS, Android and HTML5. The Defold Facebook extension brings the various platform specific Facebook APIs under a unified set of functions that work the same on iOS, Android and HTML5 (through Facebook Canvas). To get started with Facebook connectivity in your games, you need a Facebook account.

Installation

To use this library in your Defold project, add the following URL to your game.project dependencies:

https://github.com/defold/extension-facebook/archive/master.zip

We recommend using a link to a zip file of a specific release.

Registering as a Facebook developer

To develop for Facebook you must sign up as a Facebook developer. This allows you to create Facebook applications that your Defold game can communicate with.

  • Head over to Facebook for developers
  • Log in with your Facebook account.
  • Follow the instructions to register and verify your developer account.

Register as a developer  developer

Creating a Facebook app

The next step is to create a Facebook application. The My Apps menu in the corner lists your apps, and there is an option to Add a New App.

Add new app

You are presented with a selection of target platforms. Click basic setup to skip the wizards.

Most information provided through the wizards is irrelevant when developing on Defold. In particular, you usually don’t need to edit Info.plist or AndroidManifest.xml yourself. Defold does that work for you.

Add new app platform

You can easily add, remove and change platform settings in the app dashboard. You are now asked to name your app and select Display Name, Namespace and Category. Again, these can all be edited in the app dashboard. When you have gone through this, Facebook creates an app with a unique app identifier for you. The App ID is not possible to change since it identifies this specific app.

New app id

App dashboard settings

Click the Settings tab. Notice the numerical App ID. That identifier needs to go into the project settings of your Defold game. Open the game.project file from the Assets pane and scroll to the Facebook section and add the App ID to the Appid field.

game.project settings

Next, in the Advanced section of the Settings tab on the Facebook app page, scroll to the Security section and copy the Client token. Go back to the game.project file and add this to the Clienttoken field.

Now, back in the Settings tab on the Facebook app page, click + Add Platform to add a new platform to the app. Each platform has a set of settings to fill in.

Select platform

iOS

For iOS you need to specify the game’s bundle_identifier as specified in game.project.

iOS settings

Android

For Android you need to specify a Google Play Package Name, which is the game’s package identifier specified in game.project. You should also generate hashes of the certificate(s) you use and enter them into the Key Hashes field. Follow the instructions in the Facebook Developer pages to generate the hashes.

Android settings

Facebook Canvas

For HTML5 games, the process is a bit different. Facebook needs access to your game content from somewhere. There are two options:

Facebook Canvas settings

  1. Use Facebook’s Simple Application Hosting. Click Yes to select managed hosting. Select uploaded assets to open the hosted asset manager.

    Simple hosting

    Select that you want to host a “HTML5 Bundle”:

    HTML5 bundle

    Compress your HTML5 bundle into a .7z or .zip archive and upload it to Facebook. Make sure to click Push to production to start serving the game.

  2. The alternative to Facebook hosting is to upload a HTML5 bundle of your game to some server of your choice that serves the game through HTTPS. Set the Secure Canvas URL to the URL of your game.

The game now works through the Facebook URL provided as Canvas Page.

Testing the setup

The following basic test can be used to see if things are set up properly.

  1. Create a new game object and attach a script component with a new script file to it.
  2. Enter the following code in the script file (this requires the use of Facebook extension v.2 or later):
local function get_me_callback(self, id, response)
    -- The response table includes all the response data
    pprint(response)
end

local function fb_login(self, data)
    if data.status == facebook.STATE_OPEN then
        -- Logged in ok. Let's try reading some "me" data through the
        -- HTTP graph API.
        local token = facebook.access_token()
        local url = "https://graph.facebook.com/me/?access_token=" .. token
        http.request(url, "GET", get_me_callback)
    elseif data.status == facebook.STATE_CLOSED_LOGIN_FAILED then
        -- Do something to indicate that login failed
    end
    if data.error then
        -- An error occurred
    else
        -- No error
    end
end

function init(self)
    -- Log in with read permissions.
    local permissions = { "public_profile", "email" }
    facebook.login_with_permissions(permissions, facebook.AUDIENCE_EVERYONE, fb_login)
end

Running this simple test should display something like the following in the console:

DEBUG:SCRIPT:
{
  status = 200,
  headers = {
    connection = keep-alive,
    date = Fri, 04 Nov 2016 13:54:33 GMT,
    etag = "0725a4f703fe6af27da183cfec0bb22637e331e0",
    access-control-allow-origin = *,
    content-length = 53,
    expires = Sat, 01 Jan 2000 00:00:00 GMT,
    content-type = text/javascript; charset=UTF-8,
    x-fb-debug = Pr1qUssb8Xa3x3r1t913hHMdefh69DSYYV5vcxeOB7O33mcfShIw+r7BoLpn147I2wzLF2CZRTpnR3/VYOtFpA==,
    facebook-api-version = v2.5,
    cache-control = private, no-cache, no-store, must-revalidate,
    pragma = no-cache,
    x-fb-trace-id = F03S5dtsdaS,
    x-fb-rev = 2664414,
  }
  response = {"name":"Max de Fold ","id":"14159265358979323"},
}
  • The full Defold Facebook API is documented on the extension GitHub page.
  • The Facebook Graph API is documented here: https://developers.facebook.com/docs/graph-api

Deferred Facebook SDK initialization

The Facebook SDK must be initialized before any of the functions of the SDK can be used. The default behaviour is for the Facebook SDK to be automatically initialized on startup. If manual Facebook SDK initialization is preferred then set the facebook.autoinit property to 0 in game.project and call facebook.init() to initialize the SDK.

Facebook Analytics

Facebook Analytics allows you as a developer to get aggregated demographics and rich insights, like how many people launch your app, how often people make purchases and many other interactions.

Setup

Before you can use Facebook Analytics you need to create a Facebook app and add the App ID to game.project as described above. Next step is to add the Analytics product to your Facebook app:

Add Facebook Analytics

Once you have added the Facebook Analytics product to your Facebook app you can optionally configure the Analytics settings. Refer to the Facebook Developer documentation for more information about the different settings:

Add Facebook Analytics

Usage

When you have Facebook Analytics added to your Facebook app you can immediately start using it from your application by posting analytics events:

function init(self)
    -- post a spent credits event
    local params = { [facebook.PARAM_LEVEL] = 30, [facebook.PARAM_NUM_ITEMS] = 2 }
    facebook.post_event(facebook.EVENT_SPENT_CREDITS, 25, params)

    -- post a custom event
    local level = 19
    local params = { kills = 23, gold = 4, xp = 890 }
    facebook.post_event("level_completed", level, params)
end

Available predefined events and parameters can be seen in the Facebook extension API reference. These should correlate to the Standard Events and Parameters from the Facebook developer documentation.

The Facebook SDK used by Defold will also automatically generate several events, such as app install and app launch. Refer to the Auto-logged events in the Facebook developer documentation.

Once you have sent some events they will show up in the Facebook Analytics dashboard, accessible from your Facebook app page via the View Analytics button:

Add Facebook Analytics

Events are accessed from the Events option on the from the Facebook Analytics page:

Add Facebook Analytics

Sharing events with Facebook

You can opt to share generated events with Facebook for improved ad-tracking. This is done via the enable_event_usage() and disable_event_usage() functions. The default setting is according to the Facebook SDK documentation to not share events.

Source code

The source code is available on GitHub

API reference

API Reference - facebook