Push Notifications

This section deals with the functions for pushing notifications to devices.

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 these games to notify their users when events occur.

When the operating system delivers a local or remote push notification and the target application is not running in the foreground, it presents the notification to the user in the form of a banner. If there is a notification alert and the user taps on it, then the game is launched and an Asynchronous Push Event is called where you can check the callback string that you specify and resolve the push based on its value. If the application is running in the foreground when the notification is delivered, the application will still receive an Asynchronous Push Event, but the user will get no message displayed unless you create it yourself.

There are a few differences to note between supported platforms:

Local Notifications

A local push notification is local to the device that the game is installed on, and requires no backend server. 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 following functions are available for local notifications:

  1. push_local_notification
  2. push_get_first_local_notification
  3. push_get_next_local_notification
  4. push_cancel_local_notification

NOTE: This function is limited to the iOS and Android target modules. on Android you will need to have installed the Google Play Services Extension and have enabled push notifications in the Android Social Global Game Settings.

Remote Notifications

Remote notification messages are sent by a server to a service provided by the device platform App Store, and this then forwards those messages onto all the devices on which your application is installed. This is supported by GameMaker: Studio on the iOS and Android target modules.

There are no functions in GameMaker: Studio to deal with remote notifications, as they must all be generated by your server and handled by the respective App Stores. However, once set up correctly, GameMaker: Studio games will receive these notifications, which can then be dealt with in the Asynchronous Push Event, as you would a local notification.

For all available platforms, once you have done the necessary set-up, when the game is run on a device it will register that device with the platforms push notification service. This will trigger an Asynchronous Push Notification Event, and the ds_map key "type" will have the value "register" as well as a new key, "reg_id", containing the registration id (or an error message in the "error" key, if "status" is 0). You must then send this registration id to your server, and every device that your game is installed on will have a different registration id. Your server must maintain a list of ids for registered devices, as when when you send a push notification message from your server, you use the registration ids to send the message to the registered devices.

Please note that there is no guarantee that remote push notifications will be delivered, and that the allowed data payload is fairly small. This varies between platforms, but iOS is particularly limited - the apple service only delivers the most recent notification, which must be selected by the recipient for the payload data to be delivered to your async event, and these notifications have a mximum payload size of 256bytes. Typically a remote push notification would just indicate that new data is available from your server for example.

NOTE: Android requires that you add the GCM Sender ID into the Global Game Settings for the platform. This is the Project Number that is assigned when you create your Google Play API Project.

For further details on how to go about setting up a server, as well as information specific to the available platforms, please see the following pages on the YoYo Games Knowledge Base:

NOTE: Implementing the server-side is entirely up to the end user, and YoYo Games do not provide any support for that side of things, other than basic set-up information available from their Knowledge Base.

Back: Reference
© Copyright YoYo Games Ltd. 2018 All Rights Reserved