本地/推送通知

概述

Solar2D 支持两种类型的通知：本地和推送。两种通知类型的目的都是为了在应用程序不在前台运行时通知用户某些事情——例如，消息或即将到来的约会。本地通知和推送通知之间的本质区别很简单：

• 本地通知由应用程序在本地安排，并由同一设备传送。

• 推送通知由远程服务器（其提供商）发送，该服务器将这些通知发送到安装了该应用程序的设备。

使用说明

要使用推送通知，请记住以下几点：

• 应用程序必须支持注册过程，并且必须支持传入消息。

• 您必须配置您的应用程序和设备，以便 Apple 和/或 Google 能够识别它们。

• 如果使用 iOS/Apple，您的应用程序无法直接向其服务器发送推送请求。

• 我们建议您使用第三方服务向 Apple 或 Google 发送推送请求，然后由它们将请求转发到设备。该服务可以是专门从事推送通知的公司，例如 OneSignal、PushWoosh 或 Airship。

应用交互

应用程序如何响应通知取决于其状态：

• 未运行 - 应用程序已按设计退出、用户决定、重新启动等。在这种状态下，如果用户与通知交互，操作系统将启动应用程序。有关通知事件的信息将使用“启动参数”传递给应用程序。应用程序应监视这些参数并做出相应的反应，例如，显示闹钟的“稍后提醒”按钮，或者如果它有 URL，则打开 native.newWebView()。但是请注意，如果用户直接点击其图标启动应用程序，则不会显示通知。

• 后台运行 - 应用程序正在运行，但它不是活动的应用程序。在这种状态下，如果用户通过在显示通知时在解锁屏幕上滑动或在通知中心点击通知来与通知交互，操作系统会将应用程序置于前台并使其处于活动状态。此时，应用程序将接收通知事件，但不会接收启动参数。

• 前台运行 - 应用程序处于活动状态，并且用户当前正在与其交互。在这种状态下，应用程序将接收通知事件。

项目设置

要使用 通知 插件，请在 `build.settings` 的 `plugins` 表中添加一个条目。添加后，构建服务器将在构建阶段集成该插件。

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

在此 `build.settings` 文件中，还要包含 `minSdkVersion` 16 或更高版本。有关设置最低 SDK 版本的更多信息，请参阅此处。

settings =
{
    android =
    {
        minSdkVersion = "16",
    },
}

然后，在使用通知函数的代码模块中，只需按如下方式 `require()` 该库：

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

iOS 设置

推送通知的大部分 iOS 配置都在 Apple Developer 门户网站中完成。此外，您必须在 `config.lua` 的`notification` → `iphone` → `types`表中指定您的应用程序将使用哪些类型的通知。

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

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

Android 设置

Android 也需要对推送通知进行一些额外的配置：

1. 将 Firebase 控制台中提供的 `google-services.json` 复制到与 `main.lua` 并列的项目根目录中。

2. 在 `build.settings` 的 `android` 表中添加一个额外的 `useGoogleServicesJson` 条目。添加后，构建服务器将从 JSON 文件中读取设置，并在构建阶段将它们集成到您的应用程序中。

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

安排本地通知

要安排本地通知，请使用 notifications.scheduleNotification() 函数，并使用以下两种格式之一指定未来事件的时间：

1. 从调用时间算起应传送通知的秒数。

2. 以协调世界时 (UTC) 指定的时间。这应该是 `os.date("!*t")` 返回的时间表。请注意，一个常见的错误是忘记感叹号并传递 `"*t"` 而不是 `"!*t"`——这将以本地时间（您的时区）而不是 UTC 返回时间结构。

您还应传递一个包含以下任何参数的 `options` 表：

• `alert`（字符串）——要向用户显示的通知消息。如果应用程序当前未运行，系统警报将显示此消息。

• `badge`（数字）——此选项仅在 iOS 上受支持，它指示在计划的通知触发时应用程序图标上显示的徽章编号。这将替换上次应用的徽章编号。设置为 `0` 可省略徽章编号。

• `sound`（字符串）——system.ResourceDirectory 中要在计划的通知触发时播放的声音文件的名称。仅当应用当前不在前台运行时才会播放此声音。在 iOS 上，可以播放的声音种类有限制（有关更多详细信息，请参阅 Apple 的文档）。

• `custom`（表）——将随通知事件一起传送的表。这允许您传递带有通知的自定义信息。

处理通知事件

根据 Solar2D 事件/侦听器模型，如果您的应用程序在前台或后台运行并且收到通知，您将收到一个 notification 事件。您有责任初始化系统并设置侦听器函数来处理这些事件。请查看以下框架，然后阅读下面的详细小节。

local function notificationListener( event )

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

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

    end
end

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 badgeNum = native.getProperty( "applicationIconBadgeNumber" )
        if ( badgeNum > 0 ) then
            badgeNum = badgeNum - 1
            native.setProperty( "applicationIconBadgeNumber", badgeNum )
        end

    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

native.setProperty( "applicationIconBadgeNumber", 0 )

远程注册 (iOS)

在 iOS 上，当您准备好请求用户允许推送通知的权限时，您应该调用 notifications.registerForPushNotifications()。这将显示一个弹出窗口，询问用户是否要启用推送通知。建议您仅在需要时才请求此权限，而不是在应用程序启动时。

notifications.registerForPushNotifications( { useFCM=true } )

调用 notifications.registerForPushNotifications() 将触发向您的通知侦听器函数发送远程注册事件。为了适应这种情况，添加一个附加条件

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

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

    end
end