Skip to content

cloud_messaging

Jump to bottom
Francisco Dias edited this page Aug 23, 2024 · 4 revisions

Cloud Messaging

Using Firebase Cloud Messaging you can notify an app client that a new email or other data is available to be synced. You can send notification messages to drive user re-engagement and retention. For use cases such as instant messaging, a message can transfer a payload of up to 4000 bytes to an app client. Check the official page for more information.

Setup

Before starting to use any Firebase extensions, you are required to follow some initial configuration steps. However if you've already done these for any of the other modules you can skip this configuration section and go straight to using the API functions.

Functions

The following functions are provided for working with the Firebase Cloud Messaging extension:


Back To Top

FirebaseCloudMessaging_DeleteToken

This function deletes the FCM registration token for this Firebase project. Note that if auto-init is enabled, a new token will be generated the next time the app is started. Disable auto-init (using the function FirebaseCloudMessaging_SetAutoInitEnabled) to avoid this behaviour.

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 Social Async Event.


Syntax:

FirebaseCloudMessaging_DeleteToken()



Returns:

N/A


Triggers:

Social Async Event

Key Type Description
type String The constant "FirebaseCloudMessaging_DeleteToken"
success Boolean Whether or not the function task succeeded.

Example:

FirebaseCloudMessaging_DeleteToken()

In the code above we request for the FCM token to be deleted. The function callback can be caught inside a Social Async Event.

if(async_load[?"type"] == "FirebaseCloudMessaging_DeleteToken")
{
    if(async_load[?"success"])
    {
       show_debug_message("FCM token deleted");
    }
}

The code above matches the response against the correct event type, and provides a success message if success is true.



Back To Top

FirebaseCloudMessaging_GetToken

Requests the FCM registration token for this Firebase project. This sends information about the application and the device where it's running to the Firebase backend. See FirebaseCloudMessaging_DeleteToken for information on deleting the token.

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 Social Async Event.


Syntax:

FirebaseCloudMessaging_GetToken()



Returns:

N/A


Triggers:

Social Async Event

Key Type Description
type String The constant "FirebaseCloudMessaging_GetToken"
success Boolean Whether or not the function task succeeded.
value String The FCM registration token.

Example:

FirebaseCloudMessaging_GetToken();

In the code above we request for the current FCM token. The function callback can be caught inside a Social Async Event.

if(async_load[?"type"] == "FirebaseCloudMessaging_GetToken")
{
    if(async_load[?"success"])
    {
        global.fcmToken = async_load[? "value"];
    }
}

The code above matches the response against the correct event type, and if the tasks succeeds it stores the token value into a global variable (global.fcmToken).



Back To Top

FirebaseCloudMessaging_IsAutoInitEnabled

Returns whether FCM auto-initialization is enabled or disabled.


Syntax:

FirebaseCloudMessaging_IsAutoInitEnabled()



Returns:

Boolean


Example:

if (FirebaseCloudMessaging_IsAutoInitEnabled())
{
    FirebaseCloudMessaging_SetAutoInitEnabled(false);
}

The code above checks if auto-initialization is enabled and if it is it disables it (using FirebaseCloudMessaging_SetAutoInitEnabled).



Back To Top

FirebaseCloudMessaging_SetAutoInitEnabled

Enables or disables auto-initialization of Firebase Cloud Messaging.

When enabled, Firebase Cloud Messaging generates a registration token on app startup if there is no valid one (see FirebaseCloudMessaging_GetToken) and periodically sends data to the Firebase backend to validate the token. This setting is persistent across app restarts.

Note

By default, Firebase Cloud Messaging auto-initialization is enabled.


Syntax:

FirebaseCloudMessaging_SetAutoInitEnabled(enabled)
Argument Type Description
enabled Boolean Whether auto-initialization should be turned on or off.



Returns:

N/A


Example:

if (FirebaseCloudMessaging_IsAutoInitEnabled())
{
    FirebaseCloudMessaging_SetAutoInitEnabled(false);
}

The code above checks if auto-initialization is enabled (using the FirebaseCloudMessaging_IsAutoInitEnabled function) and if it is disables it.



Back To Top

FirebaseCloudMessaging_SubscribeToTopic

Subscribes the user to the given topic in the background. The subscription operation is persistent and will keep retrying until it is successful. This uses the FCM registration token to identify the app instance, generating one if it does not exist (see FirebaseCloudMessaging_GetToken), which periodically sends data to the Firebase backend when auto-init is enabled. To delete the data, delete the token (see FirebaseCloudMessaging_DeleteToken).

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 Social Async Event.


Syntax:

FirebaseCloudMessaging_SubscribeToTopic(topic)
Argument Type Description
topic String The name of the topic to subscribe to.



Returns:

N/A


Triggers:

Social Async Event

Key Type Description
type String The constant "FirebaseCloudMessaging_SubscribeToTopic"
success Boolean Whether or not the function task succeeded.
value String The name of topic subscription requested.

Example:

FirebaseCloudMessaging_SubscribeToTopic("my_awesome_topic");

In the code above we request a subscription to a topic ("my_awesome topic"). The function callback can be caught inside a Social Async Event.

if(async_load[?"type"] == "FirebaseCloudMessaging_SubscribeToTopic")
{
    var _topic = async_load[? "topic"];

    if(async_load[?"success"])
    {
        show_debug_message("Subscription to " + _topic + " SUCCEEDED");
    }
    else
    {
        show_debug_message("Subscription to " + _topic + " FAILED");
    }
}

The code above matches the response against the correct event type, and if the tasks succeeds it stores the topic value in a local variable (_topic) and logs the success of the operation.



Back To Top

FirebaseCloudMessaging_UnsubscribeFromTopic

Unsubscribes from a previously subscribed topic (see FirebaseCloudMessaging_SubscribeToTopic) in the background. The unsubscribe operation is persistent and will keep retrying until it is completed.

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 Social Async Event.


Syntax:

FirebaseCloudMessaging_UnsubscribeFromTopic(topic)
Argument Type Description
topic String The name of the topic to unsubscribe from.



Returns:

N/A


Triggers:

Social Async Event

Key Type Description
type String The constant "FirebaseCloudMessaging_UnsubscribeFromTopic"
success Boolean Whether or not the function task succeeded.
value String The name of topic subscription requested.

Example:

FirebaseCloudMessaging_UnsubscribeFromTopic("my_awesome_topic");

In the code above we request for the subscription to the topic "my_awesome topic" to be canceled. The function callback can be caught inside a Social Async Event.

if(async_load[?"type"] == "FirebaseCloudMessaging_UnsubscribeFromTopic")
{
    var _topic = async_load[? "topic"];

    if(async_load[?"success"])
    {
        show_debug_message("Subscription removed successfully");
    }
    else
    {
        show_debug_message("Subscription could not be removed");
    }
}

The code above matches the response against the correct event type, and if the tasks succeeds it stores the topic value in a local variable (_topic) and logs the success of the operation.



GameMaker 2024

Clone this wiki locally