- Select ref document -

Facebook API documentation

version 1.2.149

Functions and constants for interacting with Facebook APIs.

Functions

Constants

facebook.AUDIENCE_EVERYONE

publish permission to reach everyone

facebook.AUDIENCE_FRIENDS

publish permission to reach user friends

facebook.AUDIENCE_NONE

publish permission to reach no audience

facebook.AUDIENCE_ONLYME

publish permission to reach only me (private to current user)

facebook.EVENT_ACHIEVED_LEVEL

log this event when a person achieves specific levels you define within your application, business, or organization

facebook.EVENT_ADDED_PAYMENT_INFO

log this event when the user has entered their payment info

facebook.EVENT_ADDED_TO_CART

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

facebook.EVENT_ADDED_TO_WISHLIST

log this event when the user has added an item to their wish list

facebook.EVENT_COMPLETED_REGISTRATION

log this event when a user has completed registration with the app

facebook.EVENT_COMPLETED_TUTORIAL

log this event when the user has completed a tutorial in the app

facebook.EVENT_INITIATED_CHECKOUT

log this event when the user has entered the checkout process

facebook.EVENT_PURCHASED

Log this event when the user has completed a purchase.

facebook.EVENT_RATED

log this event when the user has rated an item in the app

facebook.EVENT_SEARCHED

log this event when a user has performed a search within the app

facebook.EVENT_SPENT_CREDITS

log this event when the user has spent app credits

facebook.EVENT_TIME_BETWEEN_SESSIONS

log this event when measuring the time between user sessions

facebook.EVENT_UNLOCKED_ACHIEVEMENT

log this event when the user has unlocked an achievement in the app

facebook.EVENT_VIEWED_CONTENT

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

facebook.GAMEREQUEST_ACTIONTYPE_ASKFOR

game request action type "askfor" for "apprequests" dialog

facebook.GAMEREQUEST_ACTIONTYPE_NONE

game request action type "none" for "apprequests" dialog

facebook.GAMEREQUEST_ACTIONTYPE_SEND

game request action type "send" for "apprequests" dialog

facebook.GAMEREQUEST_ACTIONTYPE_TURN

game request action type "turn" for "apprequests" dialog

facebook.GAMEREQUEST_FILTER_APPNONUSERS

game request filter type "app_non_users" for "apprequests" dialog

facebook.GAMEREQUEST_FILTER_APPUSERS

game request filter type "app_users" for "apprequests" dialog

facebook.GAMEREQUEST_FILTER_NONE

game request filter type "none" for "apprequests" dialog

facebook.PARAM_CONTENT_ID

parameter key used to specify an ID for the content being logged about

facebook.PARAM_CONTENT_TYPE

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

facebook.PARAM_CURRENCY

parameter key used to specify currency used with logged event

facebook.PARAM_DESCRIPTION

parameter key used to specify a description appropriate to the event being logged

facebook.PARAM_LEVEL

parameter key used to specify the level achieved

facebook.PARAM_MAX_RATING_VALUE

parameter key used to specify the maximum rating available

facebook.PARAM_NUM_ITEMS

parameter key used to specify how many items are being processed

facebook.PARAM_PAYMENT_INFO_AVAILABLE

parameter key used to specify whether payment info is available

facebook.PARAM_REGISTRATION_METHOD

parameter key used to specify method user has used to register for the app

facebook.PARAM_SEARCH_STRING

parameter key used to specify user search string

facebook.PARAM_SOURCE_APPLICATION

parameter key used to specify source application package

facebook.PARAM_SUCCESS

parameter key used to specify activity success

facebook.STATE_CLOSED_LOGIN_FAILED

the Facebook login session has closed because login failed

facebook.STATE_OPEN

the Facebook login session is open

Functions

facebook.access_token

facebook.access_token()

This function returns the currently stored access token after a previous sucessful login. If it returns nil no access token exists and you need to perform a login to get the wanted permissions.

Returns

token

string the access token or nil if the user is not logged in

token

string the access token or nil if the user is not logged in

Examples

Get the current access token, then use it to perform a graph API request.

local function get_name_callback(self, id, response)
    -- do something with the response
end

function init(self)
    -- assuming we are already logged in.
    local token = facebook.access_token()
    if token then
        local url = "https://graph.facebook.com/me/?access_token=".. token
        http.request(url, "GET", get_name_callback)
    end
end

facebook.disable_event_usage

facebook.disable_event_usage()

This function will disable event usage for Facebook Analytics which means that Facebook won't be able to use event data for ad-tracking. Events will still be sent to Facebook for insights.

Event usage cannot be controlled and is always enabled for the Facebook Canvas platform, therefore this function has no effect on Facebook Canvas.

facebook.enable_event_usage

facebook.enable_event_usage()

This function will enable event usage for Facebook Analytics which means that Facebook will be able to use event data for ad-tracking.

Event usage cannot be controlled and is always enabled for the Facebook Canvas platform, therefore this function has no effect on Facebook Canvas.

facebook.login_with_publish_permissions

facebook.login_with_publish_permissions(permissions, audience, callback)

Login to Facebook and request a set of publish permissions. The user is prompted to authorize the application using the login dialog of the specific platform. Even if the user is already logged in to Facebook this function can still be used to request additional publish permissions.

Note that this function cannot be used to request read permissions. If the application requires both publish and read permissions, individual calls to both login_with_publish_permissions and login_with_read_permissions has to be made.

A comprehensive list of permissions can be found in the Facebook documentation, as well as a guide to best practises for login management.

Parameters

permissions

table Table with the requested publish permission strings.

audience

constant | number The audience that should be able to see the publications.

  • facebook.AUDIENCE_NONE
  • facebook.AUDIENCE_ONLYME
  • facebook.AUDIENCE_FRIENDS
  • facebook.AUDIENCE_EVERYONE
callback

function(self, data) Callback function that is executed when the permission request dialog is closed.

self
object The context of the calling script
data
table A table that contains the response
permissions

table Table with the requested publish permission strings.

audience

constant | number The audience that should be able to see the publications.

  • facebook.AUDIENCE_NONE
  • facebook.AUDIENCE_ONLYME
  • facebook.AUDIENCE_FRIENDS
  • facebook.AUDIENCE_EVERYONE
callback

function(self, data) Callback function that is executed when the permission request dialog is closed.

self
object The context of the calling script
data
table A table that contains the response

Examples

Log in to Facebook with a set of publish permissions:

local permissions = {"publish_actions"}
facebook.login_with_publish_permissions(permissions, facebook.AUDIENCE_FRIENDS, function(self, data)
    if (data.status == facebook.STATE_OPEN and data.error == nil) then
        print("Successfully logged into Facebook")
        pprint(facebook.permissions())
    else
        print("Failed to get permissions (" .. data.status .. ")")
        pprint(data)
    end
end)

facebook.login_with_read_permissions

facebook.login_with_read_permissions(permissions, callback)

Login to Facebook and request a set of read permissions. The user is prompted to authorize the application using the login dialog of the specific platform. Even if the user is already logged in to Facebook this function can still be used to request additional read permissions.

Note that this function cannot be used to request publish permissions. If the application requires both read and publish permissions, individual calls to both login_with_publish_permissions and login_with_read_permissions has to be made.

A comprehensive list of permissions can be found in the Facebook documentation, as well as a guide to best practises for login management.

Parameters

permissions

table Table with the requested read permission strings.

callback

function(self, data) callback function that is executed when the permission request dialog is closed.

self
object The context of the calling script
data
table A table that contains the response
permissions

table Table with the requested read permission strings.

callback

function(self, data) callback function that is executed when the permission request dialog is closed.

self
object The context of the calling script
data
table A table that contains the response

Examples

Log in to Facebook with a set of read permissions:

local permissions = {"public_profile", "email", "user_friends"}
facebook.login_with_read_permissions(permissions, function(self, data)
    if (data.status == facebook.STATE_OPEN and data.error == nil) then
        print("Successfully logged into Facebook")
        pprint(facebook.permissions())
    else
        print("Failed to get permissions (" .. data.status .. ")")
        pprint(data)
    end
end)

facebook.logout

facebook.logout()

Logout from Facebook.

facebook.permissions

facebook.permissions()

This function returns a table with all the currently granted permission strings.

Returns

permissions

table the permissions

permissions

table the permissions

Examples

Check the currently granted permissions for a particular permission:

for _,permission in ipairs(facebook.permissions()) do
    if permission == "user_likes" then
        -- "user_likes" granted...
        break
    end
end

facebook.post_event

facebook.post_event(event, value, [params])

This function will post an event to Facebook Analytics where it can be used in the Facebook Insights system.

Parameters

event

constant | string An event can either be one of the predefined constants below or a text string which can be used to define a custom event that is registered with Facebook Analytics.

  • facebook.EVENT_ACHIEVED_LEVEL
  • facebook.EVENT_ADDED_PAYMENT_INFO
  • facebook.EVENT_ADDED_TO_CART
  • facebook.EVENT_ADDED_TO_WISHLIST
  • facebook.EVENT_COMPLETED_REGISTRATION
  • facebook.EVENT_COMPLETED_TUTORIAL
  • facebook.EVENT_INITIATED_CHECKOUT
  • facebook.EVENT_PURCHASED
  • facebook.EVENT_RATED
  • facebook.EVENT_SEARCHED
  • facebook.EVENT_SPENT_CREDITS
  • facebook.EVENT_TIME_BETWEEN_SESSIONS
  • facebook.EVENT_UNLOCKED_ACHIEVEMENT
  • facebook.EVENT_VIEWED_CONTENT
value

number a numeric value for the event. This should represent the value of the event, such as the level achieved, price for an item or number of orcs killed.

[params]

table optional table with parameters and their values. A key in the table can either be one of the predefined constants below or a text which can be used to define a custom parameter.

  • facebook.PARAM_CONTENT_ID
  • facebook.PARAM_CONTENT_TYPE
  • facebook.PARAM_CURRENCY
  • facebook.PARAM_DESCRIPTION
  • facebook.PARAM_LEVEL
  • facebook.PARAM_MAX_RATING_VALUE
  • facebook.PARAM_NUM_ITEMS
  • facebook.PARAM_PAYMENT_INFO_AVAILABLE
  • facebook.PARAM_REGISTRATION_METHOD
  • facebook.PARAM_SEARCH_STRING
  • facebook.PARAM_SOURCE_APPLICATION
  • facebook.PARAM_SUCCESS
event

constant | string An event can either be one of the predefined constants below or a text string which can be used to define a custom event that is registered with Facebook Analytics.

  • facebook.EVENT_ACHIEVED_LEVEL
  • facebook.EVENT_ADDED_PAYMENT_INFO
  • facebook.EVENT_ADDED_TO_CART
  • facebook.EVENT_ADDED_TO_WISHLIST
  • facebook.EVENT_COMPLETED_REGISTRATION
  • facebook.EVENT_COMPLETED_TUTORIAL
  • facebook.EVENT_INITIATED_CHECKOUT
  • facebook.EVENT_PURCHASED
  • facebook.EVENT_RATED
  • facebook.EVENT_SEARCHED
  • facebook.EVENT_SPENT_CREDITS
  • facebook.EVENT_TIME_BETWEEN_SESSIONS
  • facebook.EVENT_UNLOCKED_ACHIEVEMENT
  • facebook.EVENT_VIEWED_CONTENT
value

number a numeric value for the event. This should represent the value of the event, such as the level achieved, price for an item or number of orcs killed.

[params]

table optional table with parameters and their values. A key in the table can either be one of the predefined constants below or a text which can be used to define a custom parameter.

  • facebook.PARAM_CONTENT_ID
  • facebook.PARAM_CONTENT_TYPE
  • facebook.PARAM_CURRENCY
  • facebook.PARAM_DESCRIPTION
  • facebook.PARAM_LEVEL
  • facebook.PARAM_MAX_RATING_VALUE
  • facebook.PARAM_NUM_ITEMS
  • facebook.PARAM_PAYMENT_INFO_AVAILABLE
  • facebook.PARAM_REGISTRATION_METHOD
  • facebook.PARAM_SEARCH_STRING
  • facebook.PARAM_SOURCE_APPLICATION
  • facebook.PARAM_SUCCESS

Examples

Post a spent credits event to Facebook Analytics:

params = {[facebook.PARAM_LEVEL] = 30, [facebook.PARAM_NUM_ITEMS] = 2}
facebook.post_event(facebook.EVENT_SPENT_CREDITS, 25, params)

facebook.show_dialog

facebook.show_dialog(dialog, param, callback)

Display a Facebook web dialog of the type specified in the dialog parameter. The param table should be set up according to the requirements of each dialog type. Note that some parameters are mandatory. Below is the list of available dialogs and where to find Facebook's developer documentation on parameters and response data.

"apprequests"

Shows a Game Request dialog. Game Requests allows players to invite their friends to play a game. Available parameters:

  • string title
  • string message
  • number action_type
  • number filters
  • string data
  • string object_id
  • table suggestions
  • table recipients
  • string to

On success, the "result" table parameter passed to the callback function will include the following fields:

  • string request_id
  • table to

Details for each parameter: https://developers.facebook.com/docs/games/services/gamerequests/v2.6#dialogparameters

"feed"

The Feed Dialog allows people to publish individual stories to their timeline.

  • string caption
  • string description
  • string picture
  • string link
  • table people_ids
  • string place_id
  • string ref

On success, the "result" table parameter passed to the callback function will include the following fields:

  • string post_id

Details for each parameter: https://developers.facebook.com/docs/sharing/reference/feed-dialog/v2.6#params

"appinvite"

The App Invite dialog is available only on iOS and Android. Note that the url parameter corresponds to the appLinkURL (iOS) and setAppLinkUrl (Android) properties.

  • string url
  • string preview_image

Details for each parameter: https://developers.facebook.com/docs/reference/ios/current/class/FBSDKAppInviteContent/

Parameters

dialog

string dialog to show. - "apprequests" - "feed" - "appinvite"

param

table table with dialog parameters

callback

function(self, result, error) callback function that is called when the dialog is closed.

self
object The context of the calling script
result
table Table with dialog specific results. See above.
error
table Error message. If there is no error, error is nil.
dialog

string dialog to show. - "apprequests" - "feed" - "appinvite"

param

table table with dialog parameters

callback

function(self, result, error) callback function that is called when the dialog is closed.

self
object The context of the calling script
result
table Table with dialog specific results. See above.
error
table Error message. If there is no error, error is nil.

Examples

Show a dialog allowing the user to share a post to their timeline:

local function fb_share(self, result, error)
    if error then
        -- something did not go right...
    else
        -- do something sensible
    end
end

function init(self)
    -- assuming we have logged in with publish permissions
    local param = { link = "http://www.mygame.com",picture="http://www.mygame.com/image.jpg" }
    facebook.show_dialog("feed", param, fb_share)
end

Constants

facebook.AUDIENCE_EVERYONE

facebook.AUDIENCE_FRIENDS

facebook.AUDIENCE_NONE

facebook.AUDIENCE_ONLYME

facebook.EVENT_ACHIEVED_LEVEL

facebook.EVENT_ADDED_PAYMENT_INFO

facebook.EVENT_ADDED_TO_CART

The value_to_sum passed to facebook.post_event should be the item's price.

facebook.EVENT_ADDED_TO_WISHLIST

The value_to_sum passed to facebook.post_event should be the item's price.

facebook.EVENT_COMPLETED_REGISTRATION

facebook.EVENT_COMPLETED_TUTORIAL

facebook.EVENT_INITIATED_CHECKOUT

The value_to_sum passed to facebook.post_event should be the total price in the cart.

facebook.EVENT_PURCHASED

facebook.EVENT_RATED

The value_to_sum passed to facebook.post_event should be the numeric rating.

facebook.EVENT_SEARCHED

facebook.EVENT_SPENT_CREDITS

The value_to_sum passed to facebook.post_event should be the number of credits spent.

This event is currently an undocumented event in the Facebook SDK.

facebook.EVENT_TIME_BETWEEN_SESSIONS

facebook.EVENT_UNLOCKED_ACHIEVEMENT

facebook.EVENT_VIEWED_CONTENT

facebook.GAMEREQUEST_ACTIONTYPE_ASKFOR

facebook.GAMEREQUEST_ACTIONTYPE_NONE

facebook.GAMEREQUEST_ACTIONTYPE_SEND

facebook.GAMEREQUEST_ACTIONTYPE_TURN

facebook.GAMEREQUEST_FILTER_APPNONUSERS

facebook.GAMEREQUEST_FILTER_APPUSERS

facebook.GAMEREQUEST_FILTER_NONE

facebook.PARAM_CONTENT_ID

The parameter key could be an EAN, article identifier, etc., depending on the nature of the app.

facebook.PARAM_CONTENT_TYPE

The key is an arbitrary type/family (e.g. "music", "photo", "video") depending on the nature of the app.

facebook.PARAM_CURRENCY

Use a currency value key, e.g. "USD", "EUR", "GBP" etc. See ISO-4217 for specific values.

facebook.PARAM_DESCRIPTION

Use this for app specific event description, for instance the name of the achievement unlocked in the facebook.EVENT_UNLOCKED_ACHIEVEMENT event.

facebook.PARAM_LEVEL

facebook.PARAM_MAX_RATING_VALUE

Set to specify the max rating available for the facebook.EVENT_RATED event. E.g., "5" or "10".

facebook.PARAM_NUM_ITEMS

Set to specify the number of items being processed for an facebook.EVENT_INITIATED_CHECKOUT or facebook.EVENT_PURCHASED event.

facebook.PARAM_PAYMENT_INFO_AVAILABLE

Set to specify if payment info is available for the facebook.EVENT_INITIATED_CHECKOUT event.

facebook.PARAM_REGISTRATION_METHOD

Set to specify what registation method a user used for the app, e.g. "Facebook", "email", "Twitter", etc.

facebook.PARAM_SEARCH_STRING

Set this to the the string that the user provided for a search operation.

facebook.PARAM_SOURCE_APPLICATION

facebook.PARAM_SUCCESS

Set this key to indicate whether the activity being logged about was successful or not.

facebook.STATE_CLOSED_LOGIN_FAILED

facebook.STATE_OPEN