v2.0 features - macadmins/nudge GitHub Wiki

Nudge v2.0 is a significant upgrade and includes more than 46 bug fixes and requested features from Mac Admins.

Breaking Changes

  • macOS 11 is now unsupported
    • Please use Nudge 1.x releases for macOS 11
  • Due to implementing markdown support, many of the elements within Nudge may no longer be in bold if you customize them.
    • To work around this please add ** elements to these customizations
    • For example: The mainContentNote value of Important Notes would become **Important Notes**
    • Text Level Markdown
  • The SOFA feed is opt-out, which included the new Unsupported UI. If you do not want the Unsupported UI features, you will need to actively opt-out of these options.

Changed

  • Now built on Swift 5.10, Xcode 15.4 and macOS 14
  • New Xcode Scheme -bundle-mode-profile to test profile logic
    • -bundle-mode has been renamed to -bundle-mode-json
  • You can now pass two formats of strings to requiredInstallationDate
    • 2025-01-01T00:00:00Z for UTC
    • 2025-01-01T00:00:00 for local time
    • If you are using a MDM profile and passing the original Date key, you must change to utilizing String as Apple requires ISO8601 formatted dates
  • You can now pass the strings latest, latest-supported and latest-minor in the requiredMinimumOSVersion key
    • latest: always force latest release and if the machine can't this version, show the new "unsupported device" user interface
    • latest-supported: always get the latest version sofa shows that is supported by this device
    • latest-minor: stay in the current major release and get the latest minor updates available
    • This requires utilizing the SOFA feed features to properly work, which is opt-out by default
    • Nudge will then utilize two date integers to automatically calculate the requiredInstallationDate
      • activelyExploitedCVEsMajorUpgradeSLA under the osVersionRequirement key will default to 14 days
      • activelyExploitedCVEsMinorUpdateSLA under the osVersionRequirement key will default to 14 days
      • nonActivelyExploitedCVEsMajorUpgradeSLA under the osVersionRequirement key will default to 21 days
      • nonActivelyExploitedCVEsMinorUpdateSLA under the osVersionRequirement key will default to 21 days
      • standardMajorUpgradeSLA under the osVersionRequirement key will default to 28 days
      • standardMinorUpdateSLA under the osVersionRequirement key will default to 28 days
      • These dates are calculated against the ReleaseDate key in the SOFA feed, which is UTC formatted. Local timezones will not be supported with the automatic sofa feed unless you use a custom feed and change this value yourself, following ISO-8601 date formats
        • To artificially delay the SOFA nudge events, see the details below for nudgeMajorUpgradeEventLaunchDelay and nudgeMinorUpdateEventLaunchDelay
      • If you'd like to not have nudge events for releases without any known CVEs, please configure the disableNudgeForStandardInstalls key under optionalFeatures to true
  • You can now disable the Days Remaining To Update: item on the left side of the UI.
    • Configure the showDaysRemainingToUpdate key under userInterface to false

Fixed

  • screenshotDisplay view had a bug that may result in the screenshot being partially cut off or zoomable
  • fallbackLanguage would return the wrong language even when specified in the configuration
  • The timer controller logic was utilizing hours remaining vs seconds, which resulted in the elapsedRefreshCycle being used at the final hour of the nudge event vs the imminentRefreshCycle. This has been corrected to calculate the seconds remaining.
  • More descriptive logs when loading json/mdm profile keys
  • Refactor portions of the softwareupdate logic to reduce potential errors
  • Fixed errors when moving to Swift 5.10
  • Fixed wrong requiredInstallationDate calculations when using Non-Gregorian calendars
  • Fixed UI logic when requiredInstallationDate is under an hour and allowLaterDeferralButton is set to false

Added

  • To artificially change the requredInstallationDate thereby giving your users a default grace period for all Nudge events updates, please configure the nudgeMajorUpgradeEventLaunchDelay and nudgeMinorUpdateEventLaunchDelay keys under userExperience in amount of days.
  • A local image path can now be specified for the notification event when Nudge terminates and application
    • Please configure the applicationTerminatedNotificationImagePath key under userInterface
    • Due to limitations within Apple's API, a local path is only supported at this time
  • An admin can now alter the text when Nudge terminates and application
    • Please configure the applicationTerminatedTitleText and applicationTerminatedBodyText keys under the updateElements key in UserInterface
  • Remote URLs can now be used on iconDarkPath, iconLightPath, screenShotDarkPath and screenShotLightPath
    • Please note that these files will be downloaded each time Nudge is ran and there is currently not a way to cache these objects.
    • If these files fail to download, a default company logo will be shown.
  • Actively Exploited CVEs in the left sidebar
    • To disable this item, please configure the showActivelyExploitedCVEs key under userInterface to false
  • An admin can now allow users to move the Nudge window with userExperience key allowMovableWindow
  • To ease testing, you can now pass -disable-random-delay as an argument to ignore the randomDelay key if it is set by a JSON or mobileconfig
  • Basic SwiftUI support for Markdown text options
    • Utilizing Apple's markdown features, you can now utilize, bold, italic, underline, subscript and url links directly into any of the text fields
  • SOFA feed support
    • Set the utilizeSOFAFeed key false under optionalFeatures to disable this feature
    • Nudge will by default check the feed every 24 hours and save a cache file under ~/Library/Application Support/com.github.macadmins.Nudge/sofa-macos_data_feed.json
    • In order to change this, please configure the refreshSOFAFeedTime key under optionalFeatures in seconds
    • If you are utilizing a custom sofa feed, please configure the customSOFAFeedURL key under optionalFeatures
  • "Unsupported device" UI in standard mode that utilizes the SOFA feed
    • Set the attemptToCheckForSupportedDevice key false under optionalFeatures to disable this feature
    • There are new keys to set all of text fields: actionButtonTextUnsupported, mainContentHeaderUnsupported, mainContentNoteUnsupported, mainContentSubHeaderUnsupported, mainContentTextUnsupported, subHeaderUnsupported under the updateElements key in UserInterface
    • unsupportedURL and unsupportedURLs can change the information button itself, but it will remain in the osVersionRequirement key with unsupportedURLs and unsupportedURLs.
    • An icon will appear as an overlay on top of the company image to further emphasize the device is no longer supported
  • An admin can now show the requiredInstallationDate as a item on the left side of nudge.
    • To enable this, please configure the showRequiredDate key under userInterface to true
    • You can also expirement with the format of this date through the key requiredInstallationDisplayFormat under userInterface
    • Be aware that the format you desire may not look good on the UI.
  • Nudge can now honor the current cycle timers when user's press the Quit button.
    • Set the honorCycleTimersOnExit key to true under optionalFeatures to enable this feature
    • Issue 548
  • When the device is running macOS 12.3 or higher, Nudge uses the delta logic for macOS Upgrades
  • Nudge can now bypass activations and re-activations when a macOS update is Downloading, Preparing or Staged for installation.
    • To disable this, please configure the acceptableUpdatePreparingUsage key under optionalFeatures to false
    • Issue 555 and 571
  • Nudge can now attempt to honor DoNotDisturb/Focus times
    • To enable this, please configure the honorFocusModes key in optionalFeatures to true
    • This is an expiremental feature and may not work due to significant changes that Apple has designed for detecting these events.
  • Nudge now attempts to reload the preferences if the MDM profile is updated

Example JSON

{
    "optionalFeatures": {
        "acceptableUpdatePreparingUsage": true,
        "disableNudgeForStandardInstalls": false,
        "honorFocusModes": true,
        "honorCycleTimersOnExit": true,
        "refreshSOFAFeedTime": 86400,
        "utilizeSOFAFeed": true,
        "attemptToCheckForSupportedDevice": true
    },
    "osVersionRequirements": [
        {
            "requiredMinimumOSVersion": "latest",
            "activelyExploitedCVEsMajorUpgradeSLA": 14,
            "activelyExploitedCVEsMinorUpdateSLA": 14,
            "nonActivelyExploitedCVEsMajorUpgradeSLA": 21,
            "nonActivelyExploitedCVEsMinorUpdateSLA": 21,
            "standardMajorUpgradeSLA": 28,
            "standardMinorUpdateSLA": 28,
            "unsupportedURL": "https://support.apple.com/unsupported",
            "unsupportedURLs": [
                {
                    "_language": "en",
                    "unsupportedURL": "https://support.apple.com/unsupported-en"
                },
                {
                    "_language": "es",
                    "unsupportedURL": "https://support.apple.com/unsupported-es"
                }
            ]
        }
    ],
    "userExperience": {
        "allowMovableWindow": true,
        "nudgeMajorUpgradeEventLaunchDelay": 7,
        "nudgeMinorUpdateEventLaunchDelay": 2
    },
    "userInterface": {
        "applicationTerminatedNotificationImagePath": "/path/to/local/path.png",
        "iconDarkPath": "https://example.com/images/logoDark.png",
        "iconLightPath": "https://example.com/images/logoLight.png",
        "screenShotDarkPath": "https://example.com/images/screenShotDark.png",
        "screenShotLightPath": "https://example.com/images/screenShotLight.png",
        "showActivelyExploitedCVEs": true,
        "showDaysRemainingToUpdate": false,
        "showRequiredDate": true,
        "requiredInstallationDisplayFormat": "MM/dd/yyyy",
        "updateElements": [
            {
                "_language": "en",
                "actionButtonTextUnsupported": "Replace Your Device",
                "applicationTerminatedTitleText": "Application terminated",
                "applicationTerminatedBodyText": "Please update your device to use this application",
                "mainContentHeaderUnsupported": "Your device is no longer capable of receiving critical security updates",
                "mainContentNoteUnsupported": "**Important Notes**",
                "mainContentSubHeaderUnsupported": "Please work with your local IT team to obtain a replacement device",
                "mainContentTextUnsupported": "A fully up-to-date device is required to ensure that IT can accurately protect your device.",
                "subHeaderUnsupported": "A friendly reminder from your local IT team"
            },
            {
                "_language": "es",
                "actionButtonTextUnsupported": "Reemplazar su dispositivo",
                "applicationTerminatedTitleText": "Aplicación terminada",
                "applicationTerminatedBodyText": "Actualice su dispositivo para usar esta aplicación",
                "mainContentHeaderUnsupported": "Su dispositivo ya no es capaz de recibir actualizaciones críticas de seguridad",
                "mainContentNoteUnsupported": "**Notas importantes**",
                "mainContentSubHeaderUnsupported": "Trabaje con su equipo local de TI para obtener un dispositivo de reemplazo",
                "mainContentTextUnsupported": "Se requiere un dispositivo completamente actualizado para garantizar que TI pueda proteger su dispositivo con precisión.",
                "subHeaderUnsupported": "Un recordatorio amistoso de su equipo de IT local"
            }
        ]
    }
}