Local/Push Notifications

Overview

Corona SDK 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.

Usage Notes

To use push notifications, remember the following points:

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

2. You must configure your app and devices so that Apple and/or Google recognizes them. Apple/Google will send the actual messages out to devices.

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

4. 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.

5. Another option to handle push notifications on iOS is EasyAPNS. This is a PHP/MySQL setup that registers devices in your own database and allows you to send push notifications from your own server. Please visit www.easyapns.com for more information.

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.

settings =
{
    plugins =
    {
        ["plugin.notifications"] =
        {
            publisherId = "com.coronalabs"
        },
    },      
}

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

local notifications = require( "plugin.notifications" )

iOS Setup

Much of the iOS configuration for push notifications is done within the Apple Developer portal. Please refer to the guide for details.

In addition, you must include a notification table in the config.lua file (guide) to enable various features for push notifications. This tells the system which of the alert types you plan to use.

application = 
{
    content =
    {
        width = 320,
        height = 480,
        scale = "letterbox",
        xAlign = "center",
        yAlign = "center"
    },

    notification = 
    {
        iphone =
        {
            types = { "badge", "sound", "alert" }
        }
    }
}

Android Setup

Android also requires some additional configuration for push notifications. In the config.lua file (guide), add a notification table as follows. When you register with the Google GCM service, you'll get the projectNumber value needed for the google table.

application = 
{
    content =
    {
        width = 320,
        height = 480,
        scale = "letterbox",
        xAlign = "center",
        yAlign = "center"
    },
          
    notification = 
    {
        google =
        {
            projectNumber = "3982849975315"
        },
    }
}

In addition, you must include the following permissions in the build.settings file (guide). Failure to include these entries will cause your push notifications to fail.

settings
{
    android =
    {
        permissions =
        {
            { name = ".permission.C2D_MESSAGE", protectionLevel = "signature" },
        },
        usesPermissions =
        {
            "android.permission.INTERNET",
            "android.permission.GET_ACCOUNTS",
            "android.permission.RECEIVE_BOOT_COMPLETED",
            "com.google.android.c2dm.permission.RECEIVE",
            ".permission.C2D_MESSAGE",
        },
    },
}

Managing Local Notifications

To schedule a local notification, use the notifications.scheduleNotification() function and specify the time of the future event in one of two formats:

• Number of seconds from the call time when the notification should be delivered.
• Time specified in Coordinated Universal Time (UTC).

The UTC option 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 timezone) instead of UTC.

You should also pass an options table containing any 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) — 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. This option is not supported on Android.

• 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.

local function notificationListener( event )

    if ( event.type == "remote" ) then
        --handle the push notification

    elseif ( event.type == "local" ) then
        --handle the local notification
    end
end

--The notification Runtime listener should be handled from within "main.lua"
Runtime:addEventListener( "notification", notificationListener )

local launchArgs = ...

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

-- Decrement the badge number by 1
local function notificationListener( event )

    if ( event.type == "local" ) then
        -- Handle the local notification
        local badge_num = native.getProperty( "applicationIconBadgeNumber" )
        badge_num = badge_num - 1
        native.setProperty( "applicationIconBadgeNumber", badge_num )

    elseif ( event.type == "remote" ) then
        -- Handle the push notification
        if ( event.badge and event.badge > 0 ) then 
            native.setProperty( "applicationIconBadgeNumber", event.badge - 1 )
        end
    end
end

-- Or clear the badge entirely
native.setProperty( "applicationIconBadgeNumber", 0 )

Remote Registration

For push notifications, your app must register with the push provider's servers (Apple and Google). Corona handles the registration process for you in the background. Because you'll typically use a service to send push requests to the Apple and Google servers, that service needs to know about your app and device. Once registered, Corona will trigger the "remoteRegistration" notification event.

To accommodate this, add an additional condition to your notification listener:

local function notificationListener( event )

    if ( event.type == "remote" ) then
        --handle the push notification

    elseif ( event.type == "remoteRegistration" ) then 
        --code to register your device with the service
    end
end

--The notification Runtime listener should be handled from within "main.lua"
Runtime:addEventListener( "notification", notificationListener )

Enterprise Usage

settings = 
{
    iphone =
    {
        plist =
        {
            CoronaDelegates = { "CoronaNotificationsDelegate" }
        },
    },
}

./CoronaEnterprise/Corona/android/lib/Corona/res

from fileTree(dir: "$coronaEnterpriseAndroidLibDir/res", exclude: '**/corona_statusbar_icon_default.png')