Android: Local Push Notifications

Mark Alexander
  • 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 Google Push Notifications extension.

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

 

Google Push Notifications Extension

Local push notifications require you to have added the Google Push Notifications 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). Once you have installed the extension, you can start to code your notifications.

Note that the user does not need to be logged in to Google Play or have the Services extension for the game to use this service. 

 

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 date and time for the notification and it will be displayed to the user if the game is not currently running. 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... and 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 whatever.

The function for sending a push notification requires that you give it a fire time, a title, a message and a "payload" - data in the form of a string. The notification will be fired off when the given time is reached, 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 would look something like this:

var fireTime = date_inc_day(date_current_datetime(), 1);
var data = "daily_reward";
push_local_notification(fireTime, "Ahoy!", "Catch The Haggis Has A Present", data);

You can also 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\GooglePushNotificationsExtension\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 call back from push notifications on the device OS, either from a local source using the function push_local_notification(), or from a remote source (ie: your server). 

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 special variable async_load. This DS map always has the following keys:

"type": Value can be "local" for a device local notification, "remote" for a remote notification, or "register" for remote notification registration.

"status": Value will be 1 for success or 0 for an error.

There may be additional key entries based on the "type" returned and the "status" value. For "status", if an error (0) has been returned, then you will also have the following key:

"error": Contains details of the error received.

If the "status" value is 1 (ie: no errors) then the DS map will contain the following additional values, depending on the value of the "type" key:

"data": If the "type" received was "local" or "remote", then this key will hold the string payload that you defined when you called the notification function.

When you write your code for parsing the call back 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 fireTime = date_inc_day(date_current_datetime(), 1);
var data = "daily_reward";
push_local_notification(fireTime, "Ahoy!", "Catch The Haggis Has A Present", data);

This will set a timer to "push" a notification to the device when one day has passed. When the day is up, if 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. Note that 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 = ds_map_find_value(async_load, "type");
var status = ds_map_find_value(async_load, "status");
if status == 0
    {
    // error of some kind
    var error = ds_map_find_value(async_load, "error");
    show_debug_message("error=" + string(error));
    }
else
    {
    if type == "register"
        {
        // This is not required for Android, but is included should you
        // be creating cross-platform games
        global.reg_id = ds_map_find_value(async_load, "reg_id");
        }
    else
        {
        var data = ds_map_find_value(async_load, "data");
        if data == "daily_reward"
            {
            global.Gold += 1000;
            }
        }
    }

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.

 

 

 

Related articles