+
+ +

+

Local Notifications

+

This module contains functionality for working with local push notifications.

+

Functions

+

These are the functions in this module:

+ +

Constants

+

These are the constants used with local notifications:

+ +


+
+

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)
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ArgumentTypeDescription
uidStringThe ID of the notification
secondsRealThe number of seconds after which to display the notification
titleStringThe notification title
messageStringThe notification message
dataStringThe notification data
+


+


+


+

Returns:

+
+

Real

+
+


+

Triggers:

+
+

Push Notification Async Event

+
+

This event is triggered when the push notification is shown.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyTypeDescription
typeStringThe string "Notification_Local"
idStringThe unique ID of the notification
titleStringThe notification title
messageStringThe notification message
dataStringThe 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)
+
+ + + + + + + + + + + + + + + +
ArgumentTypeDescription
uidStringThe 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

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
KeyTypeDescription
typeStringThe string "LocalPushNotification_iOS_Permission_Request"
successBooleanWhether the request was successful
valueBooleanWhether 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

+
+ + + + + + + + + + + + + + + + + + + + +
KeyTypeDescription
typeStringThe string "LocalPushNotification_iOS_Permission_Status"
valueLocalPushNotification_iOS_PermissionThe 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)
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ArgumentTypeDescription
uidStringThe ID of the notification
secondsRealThe number of seconds after which to display the notification
titleStringThe notification title
messageStringThe notification message
dataStringExtra data to include with the notification (can be retrieved in the async_load in the async event)
filenameStringThe 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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyTypeDescription
typeStringThe string "Notification_Local"
idStringThe unique ID of the notification
titleStringThe notification title
messageStringThe notification message
dataStringThe 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:

+ +


+ + + + + + + + + + + + + + + + + + + + + +
MemberDescription
LocalPushNotification_iOS_Permission_Status_AuthorizedAuthorized to deliver notifications to the user
LocalPushNotification_iOS_Permission_Status_DeniedDenied authorization to deliver notifications to the user
LocalPushNotification_iOS_Permission_Status_NotDeterminedNot determined if we're autorized to deliver notifications. The request for the permission still needs to be made.
+


+ +
+