Local Push Notifications on Android & iOS

Gurpreet Singh Matharoo
  • Updated
Follow

On mobile devices, normally only one application can be active in the foreground at any time, but many games and applications operate in a time-based or interconnected environment where events of interest to users can occur when the application is not in the foreground. In these cases, Local and Remote push notifications can allow games to notify their users when the events occur, and also permit the user to start the game from the notification.

These notifications will appear as an icon and a short message at the top of the main screen on the device, and you can use them to promote a special offer, announce updates to your game, or simply invite the user to come and play again if they haven't for a while. However, before you rush off to add these into your game, it's worth noting that many users do not like these notifications, and so you should consider making them an "opt-in/out" feature from the options within your game.

This article shows you how to set up Local Push Notifications for your Android app using the Local Notifications extension.

NOTE: If you want to set up Remote notifications then please see the article Android: Remote Push Notifications Using Firebase (FCM).

 

Local Notifications Extension

Local notifications require you to have added the Firebase Cloud Messaging extension, which you can get from the following Marketplace link:

You need to add the extension to your account and then install it from your Marketplace Library (go to Marketplace > My Library in the GameMaker IDE).

mceclip0.png

This extension contains the Local Notifications extension as a dependency. If you don't want to implement remote notifications, you can delete the Firebase Cloud Messaging extension:

extension_contents.png

The Local Notifications extension also contains iOS-only functions for requesting permission for displaying notifications.

Documentation

The extension comes with a PDF manual, which you can access via Included Files.

mceclip1.png

Click on "Open in Explorer/Finder" to see the Included Files directory and open the Local Notifications PDF.

It is recommended to follow this documentation to learn how the extension works and can be used. The rest of this guide is only meant to be a general overview on usage.

 

Local Notifications

A local push notification is local to the device that the game is installed on, and requires no backend server implementation.

You simply set the number of seconds for the notification to be delayed, and it will be displayed to the user if the game is not running after that many seconds. This type of notification is useful to set "reminders" for the user to play your game again, or to offer a daily reward for playing, etc.

When the user taps the notification, it will launch the game, and pass in a data string which can then be parsed by the game to give a reward, or perform some other specific behaviour on opening the notification.

Creating a Notification

The function for sending a push notification requires that you give it a unique identification string, fire delay, a title, a message and a "payload" - data in the form of a string.

The notification will be fired off when the given seconds have passed, and if the user taps it, then your game will be started and the payload string sent to the Asynchronous Push event where it can be parsed.

The actual code for creating the notification would look something like this:

var uid = "play_again";
var fireDelay = 7200;
var title = "Tired?";
var message = "Refresh with a run of Paneer Planet";
var data = json_stringify({
    scoreToGive: 4000,
    nextNotificationIn: 14400,
});
LocalPushNotification_Create(uid, fireDelay, title, message, data);

This sets the notification to run after 2 hours (7200 seconds). It specifies the UID, fire delay in seconds, title, message, and a data JSON string which is created from a struct. This is only an example, your data string does not have to contain JSON data. If you do specify a JSON string, it should later be converted back into a struct using json_parse().

Notification Icon

You can change the notification icons for your app by modifying the notification_icon.png files in the drawable folders in the extension Android resource folder:

<project folder>\extensions\YYLocalNotifications\AndroidSource\res

Note that Android notification icons should be saved as transparent .png files with the solid pixels representing the area of the icon that will be tinted in either the notification colour or the default system icon colours depending on the situation (this is controlled entirely by the OS). For the exact guidelines see the following article:

You can find a very useful tool for creating notification icons from the following link too:

 

The Asynchronous Push Event

The Push Notification Event is one that is triggered by the callback from push notifications on the device OS, either from a local source using the function LocalPushNotification_Create(), or from a remote source (Firebase). 

This event will be triggered immediately when a remote notification is received on the device while your app is in the foreground. If the app is in the background, then the notification will be shown on the device and clicking on it will take the user back to your app. When that happens, the async event will get triggered on launch.

NOTE: We recommend that you have a single persistent object that is created on game start to deal with all async events.

Either way, it generates a DS map that is exclusive to this event and is stored in the variable async_load. This DS map always has the following keys:

"type": "Notification_Local"
   (This would be "Notification_Remote" when using Firebase for remote notifications)

"id": {string} The notification’s unique identification string.
"title": {string} The notification’s title shown in the OS.
"message": {string} The notification’s body shown in the OS.
"data": {string} The data string passed into the notification creation function.

When you write your code for parsing the callback data, the general workflow is exactly the same for both local and remote notifications. Let's use the example code we posted earlier to illustrate how you would do this:

var uid = "play_again";
var fireDelay = 7200;
var title = "Tired?";
var message = "Refresh with a run of Paneer Planet";
var data = json_stringify({
    scoreToGive: 4000,
    nextNotificationIn: 14400,
});
LocalPushNotification_Create(uid, fireDelay, title, message, data);

This will set a timer to "push" a notification to the device when two hours have passed. When the time is up, and your game is either in the background or not running, a notification will be shown to the user with the given title and message, and then an asynchronous Push Notification Event will be called.

If the game is in the foreground when the time for the notification comes, it will not be shown, but the asynchronous event will still trigger.

In the event itself you would handle the callback something like this:

var type = async_load[? "type"];
if (type == "Notification_Local")
{
    show_debug_message("Notification payload received:");
    show_debug_message(json_parse(async_load[? "data"]));
    show_debug_message("Notification Title: " + async_load[? "title"]);
}

And that's it for Push notifications! Simple to set up but potentially very rewarding for both the developer and the end user, as long as you are careful not to abuse the system.

For further information on the extension, and permission functions for iOS, please read the provided PDF documentation.

 

 

Related articles