Nudge (macadmin's Slack #nudge)
Nudge is application for enforcing macOS updates, written in Swift 5.5 and SwiftUI 5.2. In order to use the newest features of Swift, Nudge will only work on macOS 11.0 and higher.
This is a replacement for the original Nudge, which was written in Python 2/3. If you need to enforce macOS updates for earlier versions, it is recommend to use nudge-python.
Some enhancements to the SwiftUI version over nudge-python
- An enhanced UI, redesigned with new functionality
- A new UI called
simpleMode - Support for localization
- Support for Apple Silicon macs
- Every one of the buttons can be customized
- Every text element except for the left portion can be customized
OS support
The following operating system and versions have been tested.
- 11.0, 11.0.1, 11.1, 11.2, 11.2.1, 11.2.2, 11.2.3, 11.3, 11.3.1, 11.4, 11.5, 11.5.1, 11.5.2
- 12.0 beta
Troubleshooting
Before submitting any issues Nudge, please ensure you using the latest version. You can find the version you are using by running Nudge and clicking on the ? button at the top left.
Alternatively you can run the -version argument through the command line
/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge -version
1.0.0.02202021152516
Tools that work with Nudge
Any MDM that supports the installation of packages (.pkgs) and profiles (.mobileconfig) can deploy and enforce Nudge.
Nudge Functionality Overview
Nudge consists of the following three components:
- Nudge.app installed to
/Applications/Utilities/Nudge.app - A LaunchAgent installed to
/Library/LaunchAgents - A Preference file, either in JSON or mobileconfig format
Rather than trying to install updates via softwareupdate, Nudge merely prompts users to install updates via Apple approved/tested methods - System Preferences and major application upgrades (Ex: Install macOS Monterey.app).
With the optionally provided LaunchAgent package, Nudge will open every 30 minutes, at the 0 and 30 minute mark. If you find this behavior too aggressive, you will need to create your own LaunchAgent.
Deploy Nudge
After installing Nudge through the package, you can attempt to open Nudge through Finder - but you will quickly realize that it immediately closed.
This is because Nudge has not been configured! Please read on to learn how to engage with Nudge through the command line.
Command Line Arguments
For a full listing of the available command line arguments, please see the wiki
To open Nudge through the command-line application, open Terminal and run the following command:
/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge
If you have just installed Nudge for the first time, you will likely see the following message returned:
/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge
Device fully up-to-date.
Demo Mode
In order to trigger Nudge in demo mode, simply pass the -demo-mode argument
/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge \
-demo-mode
This will open Nudge in the English localization and allow you to test the buttons, as well as Light/Dark mode.
If you'd like to trigger simpleMode in Demo mode, chain the both -demo-mode and -simple-mode arguments
/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge \
-demo-mode \
-simple-mode
If you'd like to force the icon in Demo mode, chain the both -demo-mode and -force-screenshot-icon arguments
/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge \
-demo-mode \
-force-screenshot-icon
Simple Mode
If you'd like to force simple mode (and don't want to use the built in preferences configuration), simply pass the -simple-mode argument
/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge \
-simple-mode
JSON Support
Nudge has support for both a local JSON and a remote JSON.
By default, Nudge will look for a JSON located at /Library/Preferences/com.github.macadmins.Nudge.json
Using the -json-url argument
To download a hosted JSON file, simply pass the -json-url argument.
Note: Spaces must be converted to %20, just as a standard URL. (This is required both for web-hosted and local assets.)
The following example uses the JSON included in the Nudge GitHub repository. (You can safely ignore any warnings indicating "There is no application set to open the URL munki://updates. )
/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge \
-json-url \
"https://raw.githubusercontent.com/macadmins/nudge/main/Example%20Assets/com.github.macadmins.Nudge.json"
While the -json-url argument is mainly designed for web-hosted URLs, you can actually pass it a file:// path as well if you want to deploy JSON to a location other than /Library/Preferences or simply want to test your workflow:
- Save the sample JSON to your Downloads folder as
com.github.macadmins.Nudge.json - Modify with your preferred editor
- Execute the following command
/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge \
-json-url \
"file:///Users/`id -n -u`/Downloads/com.github.macadmins.Nudge.json"
See also Testing and resetting Nudge.
Setting the json-url in mobileconfig profile
Using PayloadType com.github.macadmins.Nudge in a mobileconfig, use the json-url
PayloadContent
json-url
https://example.org/nudge.json
PayloadType
com.github.macadmins.Nudge
Scheduling Nudge to run
Every release of Nudge comes with an optional LaunchAgent package.
This LaunchAgent will open Nudge every 30 minutes, at the 0 and 30 minute mark. If you find this behavior too aggressive, you will need to create your own LaunchAgent.
Example LaunchAgent
xml version="1.0" encoding="UTF-8"?>
DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Labelkey>
<string>com.github.macadmins.Nudgestring>
<key>LimitLoadToSessionTypekey>
<array>
<string>Aquastring>
array>
<key>ProgramArgumentskey>
<array>
<string>/Applications/Utilities/Nudge.app/Contents/MacOS/Nudgestring>
array>
<key>RunAtLoadkey>
<true/>
<key>StartCalendarIntervalkey>
<array>
<dict>
<key>Minutekey>
<integer>0integer>
dict>
<dict>
<key>Minutekey>
<integer>30integer>
dict>
array>
dict>
plist>
Localization
By default, Nudge supports the following locales:
- English
- French
- Spanish
- German
- Swedish
- Dutch
If you need additional localizations, you will need the following:
- Localization.strings for locale of the left side of Nudge and the
Additional Machine Detailsview - Preferences file
The following example would add support for the French (fr) locale.
Note: There is already a French localization string to fill the rest of the UI
JSON
{
"userInterface": {
"updateElements": [
{
"_language": "es",
"actionButtonText": "Actualizar dispositivo",
"informationButtonText": "Más información",
"mainContentHeader": "Su dispositivo se reiniciará durante esta actualización",
"mainContentNote": "Notas importantes",
"mainContentSubHeader": "Las actualizaciones pueden tardar unos 30 minutos en completarse",
"mainContentText": "Se requiere un dispositivo completamente actualizado para garantizar que IT pueda proteger su dispositivo con precisión.\n\nSi no actualiza su dispositivo, es posible que pierda el acceso a algunos elementos necesarios para sus tareas diarias.\n\nPara comenzar la actualización, simplemente haga clic en el botón Actualizar dispositivo y siga los pasos proporcionados.",
"mainHeader": "Tu dispositivo requiere una actualización de seguridad",
"primaryQuitButtonText": "Más tarde",
"secondaryQuitButtonText": "Entiendo",
"subHeader": "Un recordatorio amistoso de su equipo de IT local"
},
{
"_language": "fr",
"actionButtonText": "Mettre à jour l'appareil",
"informationButtonText": "Plus d'informations",
"mainContentHeader": "Votre appareil redémarrera pendant cette mise à jour",
"mainContentNote": "Notes Importantes",
"mainContentSubHeader": "Les mises à jour peuvent prendre environ 30 minutes.",
"mainContentText": "Un appareil entièrement à jour est nécessaire pour garantir que le service informatique puisse le protéger efficacement.\n\n Si vous ne mettez pas à jour votre appareil, vous risquez de perdre l'accès à certains systèmes nécessaires à vos tâches quotidiennes.\n\nPour commencer la mise à jour, cliquez simplement sur le bouton Mettre à Jour le Périphérique et suivez les étapes fournies.",
"mainHeader": "Votre appareil nécessite une mise à jour de sécurité",
"primaryQuitButtonText": "Plus tard",
"secondaryQuitButtonText": "Je comprends",
"subHeader": "Un rappel amical de votre équipe informatique locale"
}
]
}
}
Mobile Config
xml version="1.0" encoding="UTF-8"?>
DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>PayloadContentkey>
<array>
<dict>
<key>userInterfacekey>
<dict>
<key>updateElementskey>
<array>
<dict>
<key>_languagekey>
<string>esstring>
<key>actionButtonTextkey>
<string>Actualizar dispositivostring>
<key>informationButtonTextkey>
<string>Más informaciónstring>
<key>mainContentHeaderkey>
<string>Su dispositivo se reiniciará durante esta actualizaciónstring>
<key>mainContentNotekey>
<string>Notas importantesstring>
<key>mainContentSubHeaderkey>
<string>Las actualizaciones pueden tardar unos 30 minutos en completarsestring>
<key>mainContentTextkey>
<string>Se requiere un dispositivo completamente actualizado para garantizar que IT pueda proteger su dispositivo con precisión.
Si no actualiza su dispositivo, es posible que pierda el acceso a algunos elementos necesarios para sus tareas diarias.
Para comenzar la actualización, simplemente haga clic en el botón Actualizar dispositivo y siga los pasos proporcionados.string>
<key>mainHeaderkey>
<string>Tu dispositivo requiere una actualización de seguridadstring>
<key>primaryQuitButtonTextkey>
<string>Más tardestring>
<key>secondaryQuitButtonTextkey>
<string>Entiendostring>
<key>subHeaderkey>
<string>Un recordatorio amistoso de su equipo de IT localstring>
dict>
<dict>
<key>_languagekey>
<string>frstring>
<key>actionButtonTextkey>
<string>Mettre à jour l'appareilstring>
<key>informationButtonTextkey>
<string>Plus d'informationsstring>
<key>mainContentHeaderkey>
<string>Votre appareil redémarrera pendant cette mise à jourstring>
<key>mainContentNotekey>
<string>Notes Importantesstring>
<key>mainContentSubHeaderkey>
<string>Les mises à jour peuvent prendre environ 30 minutes.string>
<key>mainContentTextkey>
<string>Un appareil entièrement à jour est nécessaire pour garantir que le service informatique puisse protéger votre appareil efficacement.
Si vous ne mettez pas à jour votre appareil, vous risquez de perdre l'accès à certains outils nécessaires à vos tâches quotidiennes.
Pour commencer la mise à jour, cliquez simplement sur le bouton Mettre à jour le périphérique et suivez les étapes fournies.string>
<key>mainHeaderkey>
<string>Votre appareil nécessite une mise à jour de sécuritéstring>
<key>primaryQuitButtonTextkey>
<string>Plus tardstring>
<key>secondaryQuitButtonTextkey>
<string>Je comprendsstring>
<key>subHeaderkey>
<string>Un rappel amical de votre équipe informatique localestring>
dict>
array>
dict>
dict>
array>
dict>
plist>
Configuration
Nudge offers significant customization, which might be overwhelming. But don't worry, you don't have to customize everything.
For a full listing of the available preferences, please see the wiki.
Small Example
In this example, Nudge will do the following:
- Open up in
simpleMode - Enforce Big Sur version
11.5.2to the following operating systems- all big sur releases
- an enforcement date of February 28th, 2021
- The
More Infobutton will open up to Apple's Big Sur English release notes
JSON
{
"userInterface": {
"simpleMode": true
},
"osVersionRequirements": [
{
"aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
"requiredInstallationDate": "2021-08-28T00:00:00Z",
"requiredMinimumOSVersion": "11.5.2",
"targetedOSVersionsRule": "11"
}
]
}
Mobile Config
xml version="1.0" encoding="UTF-8"?>
DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>PayloadContentkey>
<array>
<dict>
<key>osVersionRequirementskey>
<array>
<dict>
<key>aboutUpdateURLkey>
<string>https://support.apple.com/en-us/HT211896string>
<key>requiredInstallationDatekey>
<date>2021-08-28T00:00:00Zdate>
<key>requiredMinimumOSVersionkey>
<string>11.5.2string>
<key>targetedOSVersionsRulekey>
<string>11string>
dict>
array>
<key>userInterfacekey>
<dict>
<key>simpleModekey>
<true/>
dict>
dict>
array>
dict>
plist>
Full Example
For full examples please see the Example Assets folder in this repo.
Examples of the User Interface
simpleMode
English
Light
Dark
Localized (Spanish)
Light
Dark
standardMode
English
Light
Dark
Localized (Spanish)
Light
Dark
.
0 Nov 15, 2021
5 Feb 10, 2022
306 Nov 9, 2022
1 Mar 25, 2022
8 Dec 8, 2022
80 Dec 23, 2022
21 Nov 22, 2022
1 Jan 17, 2022
1 May 13, 2022
573 Jan 5, 2023
203 Dec 30, 2022
7 Feb 10, 2022
2 Jan 16, 2022
2 Nov 10, 2021
0 Nov 30, 2021
1 Mar 16, 2022
3 Aug 3, 2022
1 Jun 9, 2022
2 Dec 4, 2022