Notifications (local and Firebase)

Type Library
Revision Release 2024.3703
Keywords notification, notifications
Platforms Android, iOS
See also Local/Push Notifications (guide)

Overview

This plugin provides access to local notifications and Firebase push notifications.

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 this plugin. 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 this plugin.

Important

To use Firebase notifications on iOS make sure to include plugin.notifications.v2.firebase plugin in your build.settings. This plugin is identical to the plugin.notifications.v2 and also includes libraries required to operate notification through Firebase on iOS. Note you that to use Firebase for iOS you need to configure your Firebase project with the necessary Apple Push Notfication Auth or Keys, Read More Here.

Syntax

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

Functions

Project Settings

To use this 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.v2"] =
        {
            publisherId = "com.coronalabs"
        },
    },
}

Or use plugin.notifications.v2.firebase if you plan to use Firebase on iOS.

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

iOS

If your app is for iOS, you must specify what types of notifications your app will use within the notification → iphone → types table of config.lua:

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

Additionally, if you want to use Google Firebase Cloud Messaging (FCM) for push notifications, follow these steps:

  1. Copy GoogleService-Info.plist, provided in the Firebase console, to your Corona project's root directory alongside main.lua.

  2. Add the following entries to the iphone → plist table of build.settings:

settings =
{
    iphone =
    {
        plist =
        {
            UIBackgroundModes = { "remote-notification" },
            FirebaseAppDelegateProxyEnabled = false,
        },
    },
}

Android

If your app is for Android, you must follow these additional steps to ensure that Firebase notifications function properly:

  1. Copy google-services.json, provided in the Firebase console, to your Corona project's root directory alongside main.lua.

  2. 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,
    },
}

Solar2D Native

iOS

If you're using Solar2D Native for iOS, you'll need to add a reference to the CoronaNotificationsDelegate in your Info.plist as follows:

  1. Add an entry to your Info.plist called "CoronaDelegates" and make it of type Array.

  2. Add an entry to the CoronaDelegates array and call it "CoronaNotificationsDelegate". Ensure this is of type String.

Android

When developing natively for Android, Google wants all icons in the project's res directory. This is important because Google's Android build process generates code, creating a R.java file containing unique integer IDs to every resource that your project and its libraries contain. The IDs are needed to access these resources, including the notification icons.

When developing with Solar2D Native, you must override Corona's notification icon resources as follows:

  1. First, you should become familiar with how Android handles resources by reading Google's official documentation.

  2. Inspect the Corona library's resource directory (./Native/Corona/android/lib/Corona/res/). In this directory, every drawable directory contains a file named corona_statusbar_icon_default.png. This is the image file to override. Note that this action should be an "override" and not a replacement — you should not modify the contents of the Corona library directory!

  3. To override these notification image files with your own, you need to set up the Android project with the same drawable directories under your res directory. Add each IconNotification*.png icon to its respective drawable directory by resolution and version (see here). You also must rename these files to corona_statusbar_icon_default.png.

  4. Make a small change to the copyCoronaResources task of build.gradle (Module: app) to ignore the notification icons provided in the Corona library project. Do this by replacing the from fileTree(...) line with the following:

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