general

General

Initialization, session state, and the shared result types every other module's callbacks use.

Functions

Initialization and session state.

• fb_initialize
• fb_ready
• fb_status
• fb_is_logged_in
• fb_user_id
• fb_access_token
• fb_logout
• fb_reset_pending

Structs

Shared data types used across every module.

• FacebookResult
• FacebookNamedValue

Constants

Session state and the synchronous error codes.

• FacebookLoginStatus
• FacebookOperationStatus
• FacebookError

---

Back To Top

fb_initialize

Initializes Meta's Facebook SDK using the App ID, Display Name and Client Token you filled into the extension's options (see Extension Options). Call this once, before any other function in this extension - everything else fails with FacebookError.NotInitialized until it has completed successfully.

Calling it again once the SDK is already up is safe: the callback fires immediately with a success result and nothing is re-initialized.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Callback.

Syntax:

fb_initialize(callback)

Argument	Type	Description
callback	Function	The function to call once initialization completes or fails.

Returns:

FacebookError

FacebookError.Ok if the request was accepted, or FacebookError.ActivityNull if the game's activity is not available yet. The callback does not fire when a value other than Ok is returned.

Triggers:

Callback

Fires once, when the SDK finishes starting up (or fails to). This callback takes a single argument - there is no payload.

Key	Type	Description
result	FacebookResult	The initialization outcome. A failure here usually means the App ID or Client Token option was left empty.

Example:

var _error = fb_initialize(function(_result)
{
    if (_result.success)
        show_debug_message("Facebook SDK initialized.");
    else
        show_debug_message("Facebook initialization failed: " + (_result.error_message ?? "Unknown error."));
});

if (_error != FacebookError.Ok)
    show_debug_message("Facebook initialization rejected: " + string(_error));

---

Back To Top

fb_ready

Returns whether fb_initialize has completed successfully and the SDK is ready to take calls. This is about the SDK, not about the user - see fb_is_logged_in for that.

Syntax:

fb_ready()

Returns:

Boolean

true once the SDK is initialized, false otherwise.

Example:

if (!fb_ready())
{
    show_debug_message("Facebook SDK is not initialized yet.");
    exit;
}

---

Back To Top

fb_status

Returns the current login status as a FacebookLoginStatus value. Unlike fb_is_logged_in, this also tells you whether a login is currently in flight, which is what you want if you are guarding a login button against a double tap.

The status is reconciled against the live access token every time you read it: a session that has expired or been revoked outside the game reports Idle rather than staying Authorised.

Syntax:

fb_status()

Returns:

FacebookLoginStatus

The current login status.

Example:

if (fb_status() == FacebookLoginStatus.Processing)
{
    show_debug_message("A Facebook login request is already running.");
    exit;
}

---

Back To Top

fb_is_logged_in

Returns whether there is a live, unexpired Facebook access token for the current user. This is the check to make before fb_graph_request or fb_refresh_access_token.

Syntax:

fb_is_logged_in()

Returns:

Boolean

true if a user is logged in with an active token, false otherwise.

---

Back To Top

fb_user_id

Returns the Facebook user ID of the currently logged-in user. This is an app-scoped ID - the same person has a different ID in each app, so it is only meaningful to your own app and your own backend.

Syntax:

fb_user_id()

Returns:

String

The app-scoped user ID, or an empty string if no user is logged in.

---

Back To Top

fb_access_token

Returns the raw access token string for the current session, for cases where your own backend needs to verify the user against Meta's servers.

Warning

An access token is a credential. Never log it, never display it, and only ever send it over HTTPS to a server you control.

Syntax:

fb_access_token()

Returns:

String

The access token, or an empty string if no user is logged in.

---

Back To Top

fb_logout

Clears the current access token and logs the user out of Facebook within this app. It does not sign them out of the Facebook app or of their browser.

A login that is still in flight is deliberately left alone - its callback still fires normally, and fb_status keeps reporting Processing until it does. Use fb_reset_pending if you need to abandon it instead.

Syntax:

fb_logout()

Returns:

N/A

---

Back To Top

fb_reset_pending

Abandons any login or share request that is still waiting on the user, immediately firing each held callback with a FacebookResult whose status is FacebookOperationStatus.Cancelled and whose payload argument is undefined.

This is a recovery hatch, not part of the normal flow. It exists for the case where the user dismissed Meta's login or share screen in a way the SDK never reported back, leaving fb_login or fb_dialog rejecting every later call with LoginInProgress or ShareInProgress.

Note

This does not log the user out and does not close anything on screen - it only releases the callbacks this extension is holding.

Syntax:

fb_reset_pending()

Returns:

N/A

---

Back To Top

FacebookLoginStatus

The state of the current login session, as reported by fb_status. Extension-owned - Meta's SDK exposes the access token rather than a status value.

These constants are referenced by the following functions:

• fb_status

Member	Description
Idle	No login is in progress and no user is logged in.
Processing	A fb_login request is currently waiting on the user.
Failed	The last login or token refresh attempt failed.
Authorised	A user is logged in with a live access token.

---

Back To Top

FacebookOperationStatus

The named outcome carried by FacebookResult.status. Extension-owned - Meta models these three outcomes as three separate callback methods rather than as a value.

These constants are referenced by the following structs:

• FacebookResult

Member	Description
Success	The operation completed successfully.
Cancelled	The user dismissed the login or share screen. Not an error, and FacebookResult.error_message is absent in this case.
Error	The operation failed. See FacebookResult.error_message.

---

Back To Top

FacebookError

Extension-defined codes returned synchronously by every function that can reject a call before it reaches Meta's SDK. These are not Meta error codes - a failure that came back from Meta arrives asynchronously in FacebookResult instead.

When one of these is returned (anything other than Ok), the callback you passed is never called, so this return value is the only place a pre-flight failure is reported.

These constants are referenced by the following functions:

• fb_initialize
• fb_set_event_data_usage_limited
• fb_login
• fb_refresh_access_token
• fb_graph_request
• fb_dialog

Member	Description
Ok	The call was accepted.
NotInitialized	fb_initialize has not completed successfully yet.
ActivityNull	The game's activity/view is not available yet (too early in the app lifecycle).
NotLoggedIn	The call needs a live access token and there is none - log in first with fb_login.
InvalidArgument	An argument was empty or malformed (an empty Graph path, a link URL with no scheme).
LoginInProgress	A fb_login request is already waiting on the user. Wait for its callback, or abandon it with fb_reset_pending.
ShareInProgress	A fb_dialog request is already waiting on the user. Wait for its callback, or abandon it with fb_reset_pending.

---

Back To Top

FacebookNamedValue

A single name/value pair, used wherever Meta's SDK takes an arbitrary string-keyed parameter: fb_graph_request query parameters, and the custom parameters of fb_send_custom_event and fb_send_purchase.

The struct carries both a string and a number slot, and use_number selects which one is actually sent - the unused slot is ignored. This is a generated extension record, so it is created with an empty constructor and every field is assigned afterwards.

This struct is referenced by the following functions:

• fb_send_custom_event
• fb_send_purchase
• fb_graph_request

Member	Type	Description
name	String	The parameter name. A pair with an empty name is skipped.
string_value	String	The value to send when use_number is false.
number_value	Real	The value to send when use_number is true.
use_number	Boolean	Whether to send number_value (true) or string_value (false).

---

Back To Top

FacebookResult

The uniform outcome record delivered as the first argument of every asynchronous callback in this extension. Check success before trusting anything else in the callback - the optional payload argument that follows it is only meaningful on success.

error_message and sdk_error_code are both absent on success, and error_message is also absent when the user simply cancelled (status is FacebookOperationStatus.Cancelled). sdk_error_code carries Meta's own numeric error code verbatim, and only appears when the failure came back from Meta's SDK - a call this extension rejected before ever reaching Meta reports itself through the synchronous FacebookError return value instead, and never fires a callback at all.

This struct is referenced by the following functions:

• fb_initialize
• fb_login
• fb_refresh_access_token
• fb_graph_request
• fb_dialog

Member	Type	Description
success	Boolean	Whether the operation succeeded.
status	FacebookOperationStatus	The named outcome - succeeded, cancelled by the user, or failed.
error_message	String	Meta's own error message. Only present on failure, and not on a user cancellation.
sdk_error_code	Real	Meta's raw error code. Only present when the failure came from Meta's SDK (for example a Graph API error number).

---