local_notifications

Local Notifications

This module contains functionality for working with local push notifications.

Functions

These are the functions in this module:

• LocalPushNotification_Create
• LocalPushNotification_Cancel
• LocalPushNotification_iOS_Permission_Request
• LocalPushNotification_iOS_Permission_Status
• LocalPushNotification_Create_Ext

Constants

These are the constants used with local notifications:

• LocalPushNotification_iOS_Permission

---

Back To Top

LocalPushNotification_Create

This function creates a local push notification to be delivered some time in the future.

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 Push Notification Async Event.

Syntax:

LocalPushNotification_Create(uid, seconds, title, message, data)

Argument	Type	Description
uid	String	The ID of the notification
seconds	Real	The number of seconds after which to display the notification
title	String	The notification title
message	String	The notification message
data	String	The notification data

Returns:

Real

Triggers:

Push Notification Async Event

This event is triggered when the push notification is shown.

Key	Type	Description
type	String	The string "Notification_Local"
id	String	The unique ID of the notification
title	String	The notification title
message	String	The notification message
data	String	The notification data

Example:

/// Create Event
LocalPushNotification_Create("notification", 10, "Title", "This is a notification!", "data_goes_here");

In the Create event a local push notification is created. The notification is shown after 10 seconds.

/// Async Push Notification Event
if(async_load[? "type"] == "Notification_Local")
{
    // At this point a notification has been fired.
    // We are now able to access all its parameters.
    show_debug_message("notification_id: " + async_load[? "id"]);
    show_debug_message("notification_title: " + async_load[? "title"]);
    show_debug_message("notification_message: " + async_load[? "message"]);
    show_debug_message("notification_data: " + async_load[? "data"]);
}

When the notification is shown the Push Notification Async Event is also triggered. The details of the notification can be retrieved from the async_load variable.

---

Back To Top

LocalPushNotification_Cancel

This function cancels the previously created local notification with the given unique ID.

Syntax:

LocalPushNotification_Cancel(uid)

Argument	Type	Description
uid	String	The unique ID of the local notification

Returns:

N/A

Example:

LocalPushNotification_Cancel(uid);

---

Back To Top

LocalPushNotification_iOS_Permission_Request

This function requests permissions for sending local push notifications on iOS.

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:

LocalPushNotification_iOS_Permission_Request()

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The string "LocalPushNotification_iOS_Permission_Request"
success	Boolean	Whether the request was successful
value	Boolean	Whether the permission was granted (true) or denied (false)

Example:

/// Create Event
iOS_permission_status = LocalPushNotification_iOS_Permission_Status_NotDetermined;
if(os_type == os_ios)
{
    LocalPushNotification_iOS_Permission_Request();
}

In the Create event a request to obtain permissions on iOS is made.

/// Async Social Event
switch(async_load[? "type"])
{
    // @triggered by LocalPushNotification_iOS_Permission_Request()
    case "LocalPushNotification_iOS_Permission_Request":

        // Early exit if the request was not successful
        if (!async_load[?"success"]) break;

        // The 'value' key contains either the value: 0 - Permission was denied; 1 - Permission was granted
        if(async_load[?"value"])
        {
            // At this point we know we have been authorized to deliver notifications to the user.
            iOS_permission_status = LocalPushNotification_iOS_Permission_Status_Authorized;
        }
        else
        {
            // At this point we know we have been denied to deliver notifications to the user.
            iOS_permission_status = LocalPushNotification_iOS_Permission_Status_Denied;
        }
        break;

    // Other cases...
}

In the Async Social event the event type is checked. A type of "LocalPushNotification_iOS_Permission_Request" indicates a response to the earlier request. If the request was unsuccesful, further code execution is stopped. If it was successful, the corresponding value of LocalPushNotification_iOS_Permission is assigned to the variable iOS_permission_status.

---

Back To Top

LocalPushNotification_iOS_Permission_Status

This function requests the current permission status regarding local push notifications on iOS.

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:

LocalPushNotification_iOS_Permission_Status()

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The string "LocalPushNotification_iOS_Permission_Status"
value	LocalPushNotification_iOS_Permission	The status of the permission

Example:

/// Create Event
iOS_permission_status = LocalPushNotification_iOS_Permission_Status_NotDetermined;
if(os_type == os_ios)
{
    LocalPushNotification_iOS_Permission_Status();
}

In the Create event a variable is first set to store the permission status on iOS. It is assigned the constant LocalPushNotification_iOS_Permission_Status_NotDetermined to indicate that the status hasn't been determined yet. In case the os_type equals os_ios, an asynchronous request is made to retrieve the permission.

/// Async Social Event
switch(async_load[? "type"])
{
    // @triggered by LocalPushNotification_iOS_Permission_Status()
    case "LocalPushNotification_iOS_Permission_Status":
        iOS_permission_status =  async_load[? "value"];
        switch(iOS_permission_status)
        {
            case LocalPushNotification_iOS_Permission_Status_Authorized:
                // At this point we know we have been authorized to deliver notifications to the user.
                break;
            case LocalPushNotification_iOS_Permission_Status_Denied:
                // At this point we know we have been denided to deliver notifications to the user.
                break;
            case LocalPushNotification_iOS_Permission_Status_NotDetermined:
                // At this point we know we haven't requested for permissions just yet
                // We use this logic to request for the permission the function below doesn't return
                // any value but triggers an Async Push Notification Event of the same 'type' value.
                LocalPushNotification_iOS_Permission_Request();
                break;
        }

    // Other cases ...

In the Async Social event the event type is checked. When it is the string "LocalPushNotification_iOS_Permission_Status" this means it's a response to the request sent earlier. async_load's value member is then assigned to iOS_permission_status and the value is then checked. If the permission status is still undetermined, a request for permissions is sent using LocalPushNotification_iOS_Permission_Request.

---

Back To Top

LocalPushNotification_Create_Ext

This function creates a local push notification which can have an icon image on it.

The function allows you to provide a custom icon image to display on the notification. You can save any sprite from GameMaker to a PNG file using the sprite_save function and pass the resulting file as the filename parameter.

Note

This function can only be used on Android.

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 Push Notification Async Event.

Syntax:

LocalPushNotification_Create_Ext(uid, seconds, title, message, data, filename)

Argument	Type	Description
uid	String	The ID of the notification
seconds	Real	The number of seconds after which to display the notification
title	String	The notification title
message	String	The notification message
data	String	Extra data to include with the notification (can be retrieved in the async_load in the async event)
filename	String	The path to a custom icon image to display on the notification

Returns:

Real

Triggers:

Push Notification Async Event

This event is triggered when the push notification is shown.

Key	Type	Description
type	String	The string "Notification_Local"
id	String	The unique ID of the notification
title	String	The notification title
message	String	The notification message
data	String	The notification data

Example:

/// Create Event
icon_sprite = sprite_duplicate(spr_notification);
sprite_save(icon_sprite, 0, "icon.png");
sprite_delete(icon_sprite);
LocalPushNotification_Create_Ext("notification", 10, "Title", "This is a notification!", "data_goes_here", "icon.png");

In the Create event a local push notification is created. The notification is shown after 10 seconds.

/// Async Push Notification Event
if(async_load[? "type"] == "Notification_Local")
{
    // At this point a notification has been fired.
    // We are now able to access all its parameters.
    show_debug_message("notification_id: " + async_load[? "id"]);
    show_debug_message("notification_title: " + async_load[? "title"]);
    show_debug_message("notification_message: " + async_load[? "message"]);
    show_debug_message("notification_data: " + async_load[? "data"]);
}

When the notification is shown the Push Notification Async Event is also triggered. The details of the notification can be retrieved from the async_load variable.

---

Back To Top

LocalPushNotification_iOS_Permission

This set of constants holds the possible values for the permission on iOS.

These constants are referenced by the following functions:

• LocalPushNotification_iOS_Permission_Status

Member	Description
LocalPushNotification_iOS_Permission_Status_Authorized	Authorized to deliver notifications to the user
LocalPushNotification_iOS_Permission_Status_Denied	Denied authorization to deliver notifications to the user
LocalPushNotification_iOS_Permission_Status_NotDetermined	Not determined if we're autorized to deliver notifications. The request for the permission still needs to be made.