defold/extension-facebook/facebook
Functions and constants for interacting with Facebook APIs
- GitHub: defold/extension-facebook — pinned to
9.0.2(released while Defold 1.13.1 was current)- Pick a release from defold/extension-facebook releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as facebook from "facebook"
- Pick a release from defold/extension-facebook releases and add its Source code (zip) URL (or a packaged
Functions
facebook.login_with_permissions(permissions: table, audience: number, callback: function)facebook.login_with_tracking_preference(login_tracking: number, permissions: table, crypto_nonce: string, callback: function)facebook.logout()facebook.set_default_audience()facebook.get_current_authentication_token(): stringfacebook.get_current_profile(): tablefacebook.init()facebook.access_token(): stringfacebook.permissions(): tablefacebook.post_event(event: number | string, value: number, params?: table)facebook.enable_event_usage()facebook.disable_event_usage()facebook.enable_advertiser_tracking()facebook.disable_advertiser_tracking()facebook.show_dialog(dialog: string, param: table, callback: function)facebook.get_version(): stringfacebook.deferred_deep_link(callback: function)
facebook.login_with_permissions(permissions: table, audience: number, callback: function)
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. A comprehensive list of permissions can be found in the Facebook permissions documentation, as well as in their guide to best practices for login management.
Log in to Facebook with a set of publish permissions
local permissions = {"publish_actions"}
facebook.login_with_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)Log in to Facebook with a set of read permissions
local permissions = {"public_profile", "email", "user_friends"}
facebook.login_with_read_permissions(permissions, facebook.AUDIENCE_EVERYONE, 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)Parameters
permissions:table— table with the requested publish permission strings.audience:number— The audience that should be able to see the publications. Can be any offacebook.AUDIENCE_NONEfacebook.AUDIENCE_ONLYMEfacebook.AUDIENCE_FRIENDSfacebook.AUDIENCE_EVERYONE
callback:function— Callback function that is executed when the permission request dialog is closed.self:object— The context of the calling scriptdata:table— A table that contains the response
facebook.login_with_tracking_preference(login_tracking: number, permissions: table, crypto_nonce: string, callback: function)
iOS ONLY. Login to Facebook and request a set of permissions. Allows developers to signal that a login is limited in terms of tracking users. 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. A comprehensive list of permissions can be found in the Facebook permissions documentation, as well as in their guide to best practices for login management. For Limited Login the list of permissions can be found in the Permissions in Limited Login documentation.
Log in to Facebook with a set of publish permissions
local permissions = {"publish_actions"}
facebook.login_with_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)Log in to Facebook with a set of read permissions
local permissions = {"public_profile", "email", "user_friends"}
facebook.login_with_tracking_preference(facebook.LOGIN_TRACKING_LIMITED, permissions, "customcryptononce", 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)Parameters
login_tracking:number— The tracking type for the login. Can be any offacebook.LOGIN_TRACKING_LIMITEDfacebook.LOGIN_TRACKING_ENABLED
permissions:table— table with the requested publish permission strings.crypto_nonce:string— Nonce that the configuration was created with. A unique nonce will be used if none is provided to the factory method.callback:function— Callback function that is executed when the permission request dialog is closed.self:object— The context of the calling scriptdata:table— A table that contains the response
facebook.logout()
Logout from Facebook
facebook.set_default_audience()
iOS ONLY. The audience that should be able to see the publications. Should be called before facebook.login_with_tracking_preference(); Can be any of
facebook.AUDIENCE_NONEfacebook.AUDIENCE_ONLYMEfacebook.AUDIENCE_FRIENDSfacebook.AUDIENCE_EVERYONE
facebook.get_current_authentication_token(): string
iOS ONLY. Get the current AuthenticationToken. This function returns the currently stored authentication token after a previous successful login. If it returns nil no access token exists and you need to perform a login to get the wanted permissions.
Returns
authentication_token:string— the authentication token or nil if the user is not logged in
facebook.get_current_profile(): table
iOS ONLY. Get the users FBSDKProfile.currentProfile. Reading From Profile Helper Class
Returns
current_profile:table— After your application receives the logged-in user’s authentication token, you can use this function to read information that user has granted to your application.
facebook.init()
Initialize Facebook SDK (if facebook.autoinit is 0 in game.project)
facebook.access_token(): string
Get the current Facebook access token. This function returns the currently stored access token after a previous successful login. If it returns nil no access token exists and you need to perform a login to get the wanted permissions.
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
endReturns
token:string— the access token or nil if the user is not logged in
facebook.permissions(): table
Get the currently granted permissions. This function returns a table with all the currently granted permission strings.
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
endReturns
permissions:table— The permissions
facebook.post_event(event: number | string, value: number, params?: table)
Post an event to Facebook Analytics This function will post an event to Facebook Analytics where it can be used in the Facebook Insights system.
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)Parameters
event:number | 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
facebook.enable_event_usage()
Enable event usage with Facebook Analytics 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.disable_event_usage()
Disable event usage with Facebook Analytics 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_advertiser_tracking()
Enable advertiser tracking This function will set AdvertiserTrackingEnabled (the 'ATE' flag) to true on iOS, to inform Audience Network to use the data to deliver personalized ads for users on iOS 14 and above.
facebook.disable_advertiser_tracking()
Disable advertiser tracking This function will set AdvertiserTrackingEnabled (the 'ATE' flag) to false on iOS, to inform Audience Network not to use the data to deliver personalized ads for users on iOS 14 and above.
facebook.show_dialog(dialog: string, param: table, callback: function)
Show facebook web dialog
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
- [type:string]
title - [type:string]
message - [type:number]
action_type - [type:number]
filters - [type:string]
data - [type:string]
object_id - [type:table]
suggestions - [type:table]
recipients - [type:string]
to
On success, the "result" table parameter passed to the callback function will include the following fields
- [type:string]
request_id - [type:table]
to
"feed"
The Feed Dialog allows people to publish individual stories to their timeline.
- [type:string]
caption - [type:string]
description - [type:string]
picture - [type:string]
link - [type:table]
people_ids - [type:string]
place_id - [type:string]
ref
On success, the "result" table parameter passed to the callback function will include the following fields
- [type:string]
post_id
"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.
- [type:string]
url - [type:string]
preview_imageDetails for each parameter
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)
endParameters
dialog:string— Dialog to show"apprequests""feed""appinvite"
param:table— table with dialog parameterscallback:function— Callback function that is called when the dialog is closed.self:object— The context of the calling scriptresult:table— table with dialog specific results. See above.error:table— Error message. If there is no error,errorisnil.
facebook.get_version(): string
Get the version of the Facebook SDK used by the extension.
Returns
version:string— The Facebook SDK version
facebook.deferred_deep_link(callback: function)
Allows receiving deferred deep link URL and parameters. More info about Referred Deep Links
Show a dialog allowing the user to share a post to their timeline
local function deferred_deep_link_callback(self, result, error)
if error then
print(error.error)
else
pprint(result)
end
end
function init(self)
facebook.deferred_deep_link(deferred_deep_link_callback)
endParameters
callback:function— Callback function that is called when information is ready.self:object— The context of the calling scriptresult:table— table with a deferred deep link informationref:string— ref for this App Link.extras:table— the full set of arguments for this app link. Properties like target uri & ref are typically picked out of this set of arguments.target_url:string— target uri for this App Link.
error:table— Error message. If there is no error,errorisnil.
Constants
facebook.STATE_OPEN
The Facebook login session is open
facebook.STATE_CLOSED_LOGIN_FAILED
The Facebook login session has closed because login failed
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_ASKFOR
Game request action type "askfor" for "apprequests" dialog
facebook.GAMEREQUEST_ACTIONTYPE_TURN
Game request action type "turn" for "apprequests" dialog
facebook.GAMEREQUEST_FILTER_NONE
Game request filter type "none" for "apprequests" dialog
facebook.GAMEREQUEST_FILTER_APPUSERS
Game request filter type "app_users" for "apprequests" dialog
facebook.GAMEREQUEST_FILTER_APPNONUSERS
Game request filter type "app_non_users" for "apprequests" dialog
facebook.EVENT_ACHIEVED_LEVEL
Log this event when the user has achieved a level
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 The value_to_sum passed to facebook.post_event should be the item's price.
facebook.EVENT_ADDED_TO_WISHLIST
Log this event when the user has added an item to their wish list The value_to_sum passed to facebook.post_event should be the item's price.
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 The value_to_sum passed to facebook.post_event should be the total price in the cart.
facebook.EVENT_PURCHASED
Log this event when the user has completed a purchase. The value_to_sum passed to facebook.post_event should be the numeric rating.
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 The value_to_sum passed to facebook.post_event should be the number of credits spent.
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.PARAM_CONTENT_ID
Parameter key used to specify an ID for the content being logged about The parameter key could be an EAN, article identifier, etc., depending on the nature of the app.
facebook.PARAM_CONTENT_TYPE
Parameter key used to specify a generic content type/family for the logged event The key is an arbitrary type/family (e.g. "music", "photo", "video") depending on the nature of the app.
facebook.PARAM_CURRENCY
Parameter key used to specify currency used with logged event Use a currency value key, e.g. "USD", "EUR", "GBP" etc. See See ISO-4217 for specific values.
facebook.PARAM_DESCRIPTION
Parameter key used to specify a description appropriate to the event being logged 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
Parameter key used to specify the level achieved
facebook.PARAM_MAX_RATING_VALUE
Parameter key used to specify the maximum rating available Set to specify the max rating available for the facebook.EVENT_RATED event. E.g., "5" or "10".
facebook.PARAM_NUM_ITEMS
Parameter key used to specify how many items are being processed 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
Parameter key used to specify whether payment info is available Set to specify if payment info is available for the facebook.EVENT_INITIATED_CHECKOUT event.
facebook.PARAM_REGISTRATION_METHOD
Parameter key used to specify method user has used to register for the app Set to specify what registation method a user used for the app, e.g. "Facebook", "email", "Twitter", etc.
facebook.PARAM_SEARCH_STRING
Parameter key used to specify user search string Set this to the the string that the user provided for a search operation.
facebook.PARAM_SOURCE_APPLICATION
Parameter key used to specify source application package
facebook.PARAM_SUCCESS
Parameter key used to specify activity success Set this key to indicate whether the activity being logged about was successful or not.
facebook.AUDIENCE_NONE
Publish permission to reach no audience
facebook.AUDIENCE_ONLYME
Publish permission to reach only me (private to current user)
facebook.AUDIENCE_FRIENDS
Publish permission to reach user friends
facebook.AUDIENCE_EVERYONE
Publish permission to reach everyone
facebook.LOGIN_TRACKING_LIMITED
Login tracking Limited
facebook.LOGIN_TRACKING_ENABLED
Login tracking enabled