Overview

Corona supports two types of notifications: local and push. The purpose of both notification types is to notify the user about something — a message or an upcoming appointment, for example — when the application isn't running in the foreground. The essential difference between local notifications and push notifications is simple:

Local notifications are scheduled by an app locally and are delivered by the same device.

Push notifications are sent by a remote server (its provider) which sends these notifications to devices on which the app is installed.

Notifications are only supported on iOS and Android, not on macOS desktop, Windows desktop, Apple TV, or Android TV.

Usage Notes

To use push notifications, remember the following points:

The app has to support a registration process and it must support incoming messages.

You must configure your app and devices so that Apple and/or Google recognizes them.

If using iOS/Apple, your app cannot send push requests directly to their servers.

We recommend that you use a third-party service to send push requests to Apple or Google, who in turn sends them onward to devices. That service can be a company like OneSignal, PushWoosh, or Urban Airship that specializes in push notifications.

App Interaction

How an app reacts to notifications depends on its state:

Not running — the app has exited by design, user decision, reboot, etc. In this state, if the user interacts with the notification, the operating system will launch the app. Information about the notification event will be passed to the app using "launch arguments". The app should watch for these and react accordingly, for example, show a "snooze" button for an alarm or open a native.newWebView() if it has a URL. Note, however, that if the user starts the app by tapping directly on its icon, the notification will not be presented.

Backgrounded — the app is running but it's not the active app. In this state, if the user interacts with the notification by swiping on the unlock screen while the notification is showing or tapping on it in the notification center, the operating system will bring the app to the foreground and make it active. At this time, the app will receive the notification event but not receive launch arguments.

Foregrounded — the app is active and the user is currently interacting with it. In this state, the app will receive the notification event.

Project Settings

To use the Notifications plugin, add an entry into the plugins table of build.settings. When added, the build server will integrate the plugin during the build phase.

Then, within the code module which uses notifications functions, simply require() the library as follows:

local notifications = require( "plugin.notifications.v2" )

Important

For Android, all new apps, or existing apps being updated with push notifications for the first time, must use Firebase Cloud Messaging (FCM), supported by the current Notifications plugin (above). If you have a legacy app already configured for Google Cloud Messaging (GCM), it will continue to work indefinitely, but you should continue using the legacy plugin instead of the current notifications plugin.

For iOS, you can either use the Apple Push Notification Service (APNS) or Firebase Cloud Messaging (FCM) for push notifications (see below).

iOS Setup

Much of the iOS configuration for push notifications is done within the Apple Developer portal. In addition, you must specify what types of notifications your app will use within the notification → iphone → types table of config.lua:

Android Setup

Add an additional useGoogleServicesJson entry into the android table of build.settings. When added, the build server will read the settings from the JSON file and integrate them into your app during the build phase.

settings =
{
android =
{
useGoogleServicesJson = true,
},
}

Android Icons

You can set custom notification icons in a Corona project by adding the following files to the root of the project directory, just like custom application icons. Please see Google's official documentation for further details.

Scheduling Local Notifications

Number of seconds from the call time when the notification should be delivered.

Time specified in Coordinated Universal Time (UTC). This should be a time table as returned by os.date("!*t"). Note that a common pitfall is to forget the exclamation point and pass "*t" instead of "!*t" — this will return the time structure in local time (your time zone) instead of UTC.

You should also pass an options table containing any of the following parameters:

alert (string) — The notification message to be displayed to the user. If the application is not currently running, a system alert will display this message.

badge (number) — This option is only supported on iOS and it indicates the badge number to be displayed on the application icon when the scheduled notification triggers. This replaces the last badge number that was applied. Set to 0 to omit the badge number.

sound (string) — Name of the sound file in the system.ResourceDirectory to be played when the scheduled notification triggers. This sound is only played if the app is not currently in the foreground. On iOS, there are limitations on the kinds of sound that can be played (consult Apple's documentation for more details).

custom (table) — A table that will be delivered with the notification event. This allows you to pass custom information with the notification.

Handling Notification Events

In accordance with the Corona event/listener model, if your app is running in either the foreground or background and a notification arrives, you'll receive a notification event. It's your responsibility to initialize the system and set up a listener function to handle these events. Please review the following framework and then read the detailed subsections below.

event.type — A string value of "local" for local notifications or "remote" for push notifications.

Launch Arguments

When the operating system, as the result of an incoming notification, starts your app from an inactive (not running) state, the app receives the data as part of launchArgs instead of triggering a notification event. You can use your notificationListener function to process the launch arguments.

local launchArgs = ...
if ( launchArgs and launchArgs.notification ) then
notificationListener( launchArgs.notification )
end

Important

This launchArgs processing must be in main.lua since it's the code which receives the data.

Notification Badges (iOS)

Notification badges on iOS are easily recognized by a small circle/number overlaying the app icon. If a notification passes a badge value, a badge equal to that value will appear over the app icon.

It's your responsibility to read and set the badge number depending on its previous value. This is accomplished with the native.getProperty() and native.setProperty() functions. In almost every case, when the user opens/handles the notification, you should decrement the badge number by 1 as follows:

Notification Sounds

By default, the device will play a sound when a notification comes in. You can specify a custom sound file in your project to play instead of the default sound. For instance, if you have the file notification.wav inside your app bundle, you can specify the string "notification.wav" as part of the push bundle (if the sending service supports it) and the operating system will play that custom sound instead of the default. In this case, the event.sound entry in the event listener will equal this string.

Remote Registration (iOS)

On iOS, when you're ready to ask the user for permission to allow push notifications, you should call notifications.registerForPushNotifications(). This will show the popup which asks the user if they want to enable push notifications. It's recommended that you only ask for this permission when you need it and not at the startup of your app.