Notes

This is a pre-release version of Nudge created by GitHub Actions.
Nudge.app has been signed and notarized. The package has been signed, notarized and stapled.

By default Nudge looks for a com.github.macadmins.Nudge.json file located in /Library/Preferences. If you would like to use an alternative path, please read the README or the WIKI

About the LaunchAgent

This is a basic launch agent that opens Nudge twice an hour, every 30 minutes.
If you would like to reduce the amount of times Nudge launches per day, it is recommended to create your own LaunchAgent.

Changelog

Requires macOS 12.0 and higher.

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**
• 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
  • Fixes 582
• 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.
  • Fixes 568
• 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
  • Issue 475

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-randomDelay 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
  • Issue 417
• 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
  • Issue 370

Changes

• 26e7fc1 - try and move back to zsh with --no-rcs in the shebangs
• ec9d2d7 - CHange Schema placeholder to EX: en to prevent confusion when configuring a language. (#566)
• f3232ca - v.1.2.0
• c4dd6b2 - bump to macos12 and fix marketing version
• 1520f7b - add remote image support to companyLogo/screenShot
• f38ae97 - tweak screenshot zoom again
• c86a76f - move to web assets
• 0cfd064 - mark macOS 12 and higher for now
• 62178c2 - allow window to be movable by admin (allowMovableWindow)
• 9d6838c - first real attempt at getting gdmf data
• f83eab8 - return board-id for gdmf comparison
• ce83f3c - get rid of some compiler warnings
• 9a3e8a4 - support for apple silicon vs intel hardware for gdmf
• 16426c2 - refactor gdmf and hardmodel
• 6324510 - strip newlines in modelID
• 9fa46e2 - Remove optional logging in serviceTargetProperty
• 05e052e - Add a temporary comparison loop of the macOS Assets from gdmf
• 17853d2 - initial query of sofa v1 api
• b09d493 - remove need for custom decoding strategy for sofa
• 2deab45 - new version of sofa has SupportedDevices enabled
• 0f31977 - new utilizeSOFAFeed preference - defaults to false
• b20dd44 - start implementing unsupported ui
• a8f382a - change the other text ternaries
• bc956ca - sort the keys
• 2afb778 - finish sorting
• cd53504 - flesh out device supported logic
• 098d361 - add sofa logging events
• 335b1bf - add unsupportedURL and informationButtonTextUnsupported
• fc0ce05 - start testing for actively exploited cve info
• 0fb6528 - TODOs so I don't forget
• 027450e - more todo notes
• ad4247b - handle new sofa values for "Latest"
• d290f0e - first attempt at implementing "latest" with ui
• c12fb99 - add activelyExploitedInstallationSLA and standardInstallationSLA
• 0764e29 - add actively exploited UI
• 90974f4 - more todo
• 51184f7 - markdown provided unsupported device
• 0d54d7c - add overlay
• a010370 - move to xcode 15.4
• a3e984d - add logic for sofa caching
• 93757a8 - 2.0.0 release and more notes
• 67936c4 - macos13 to macos14 for new xcode
• 0c6535f - dont try -large
• 5f4b899 - fix changelog
• bc7ec7e - remove forced unsupported
• c5c1dd4 - add another todo
• 45928ce - remove unneccessary key for testing latest
• 9468590 - add support for "latest-supported"
• 3b36418 - add logic to test bundle profile
• 1ba078f - finish all the wrapping around local plist
• 4b33f1d - fix key typo for utilizeSOFAFeed on mdm profiles
• d7f041a - simplify the sofa logic and add latest-* supported
• 5fbd517 - fix bug when matching requiredMinimumOSVersion with OS version values
• 1e0fa3d - test the skip macOS versions no CVE logic
• 863477a - add showActivelyExploitedCVEs
• 8a49079 - active exploit cve test to red when true
• 8185036 - add user-agent in sofa request
• 31dd94b - move to globals.bundleid for all bundleid calls
• ead34ff - add customSOFAFeedURL
• c5bf7cc - add etag logic even though it doesn't work in syncronous calls
• 8a35535 - move to modified date not creation date
• 2a32c12 - break the loop after one query
• b536468 - move sofa logic to a function so it can be called after other logc
• 34cd108 - fix probable issue with xcode tests failing
• 585712f - move todos
• 0ba119a - add logic for sofaPeriodLaunchDelay
• 34fd886 - Update changelog
• eb0088e - -disable-randomDelay
• c1aaec2 - activate nudge if blocked application is terminated
• 4f3d713 - Update CHANGELOG.md
• b3bce47 - add all of the localizations for english
• 0ce73f5 - google translate as much as I can with what's left
• e28f201 - explicitly log OS versioning errors
• 92c67f8 - add custom icon in the application termination notification
• febf073 - fix issue with fallbackLanguage logic
• 83356a2 - update changelog
• 5091266 - move timerCycle logic to seconds remaining vs hours
• d77b540 - update changelog for issue 568
• 8258ebe - optionally show required install date on left side UI
• 4b1f4dd - change key name to allow artificial nudge event delays
• 0add065 - fix bug in launch delay logic
• 9138fb8 - add showDaysRemainingToUpdate rename showRequiredInstallationDate to howRequiredDate
• bfbbe7f - update changelog
• 3bafde2 - add some sequoia info
• 6fa91df - add honorFocusModes key and logic
• fe28eda - disable honorFocusModes for now
• 856db92 - try a different but less reliable method
• 8707bd5 - fix local and utc time
• b8d81e2 - update changelog
• 840e781 - fix non gregorian requiredInstallationDate
• 175549c - update changelog for non gregorian calendars
• b473b1f - move to multiple hardware checks
• 3cf7b62 - utilizeSOFAFeed is not opt-out
• b27875e - changelog utilizeSOFAFeed per opt-out
• 98e177a - fix typos
• bb6dee9 - add honorCycleTimersOnExit support
• 75870f1 - fix some localization issues
• d0f0021 - add additional support for not exiting when you can't fetch the upgrade
• 54ee10e - update changelog
• 921a087 - return gestalt information
• 45362ae - add logic for acceptableUpdatePreparingUsage
• fcf7b18 - add another issue
• d904dff - fix ui issue with requiredinstalldate under hour and no quit button set
• 6e8c7fe - add optional features to jamf json
• 4ff5ebf - add expiremental feature to changelog
• 044e2a0 - osVersionRequirements jamf json
• fbd39fe - sort keys
• 20c5a49 - userExperience jamf json
• 9a3da3c - sort more keys
• d7fe24f - userInterface keys jamf json
• 0fb6fbe - attempt to check for MDM profile changes
• 539ff5f - fix typo
• 2ec3b71 - handle sofa feed failing when there is no internet
• e32887f - add more logic for when json is 0bytes and fails to decode
• 2197848 - bump to test sofa feed on 14.5
• 94749b5 - add manual tester 14.4.1
• 03a3240 - create escape hatch for replacing device logic
• 64b3a7e - add a false to remember where the test is
• 81594c8 - add another potential update assertion for macOS 15
• 16f4090 - grab full path of the process and compare to relative path
• 93ce34a - add major and minor SLAs for sofa
• 29ce1c6 - add changelog into the project so I can modify within xcode
• ba31645 - nudgeEventLaunchDelay is now nudgeMajorUpgradeEventLaunchDelay and nudgeMinorUpdateEventLaunchDelay
• 9871cd2 - add compression to potentially reduce SOFA bw
• 5f7e24c - Update CHANGELOG.md
• 3bf57e6 - Update CHANGELOG.md
• 43e62e0 - add breaking change notes
• 6101b30 - add another note about sofa feed
• 11b6adf - retry when json is malformed
• fee2676 - preparing adds - move to globs and capture username of process now
• 0fd3b7e - acceptableUpdatePreparingUsage is now opt-out
• 6ebb592 - moved to gzipped data feed by default
• a6f4acc - add safety if we cannot save sofa json
• f938ea1 - move logic for etag later in the processing path
• b8a73e2 - add gzip decompression logic
• ac94ef8 - add v1 to api call
• d1dcb15 - move 0byte check to reduce erroneous log errors
• a6f0177 - customfeedurl to test json to use both sofa feeds
• 325e9f7 - gzip deflate is not needed and add timeout logic