Nudge

com.github.macadmins.Nudge

Nudge settings

macOS

macOS 11.0+

Configuration Keys (6)

Key	Type	Description	Default	Range
`PFC_SegmentedControl_0`string required	string	—	Default: —	Range: —
`optionalFeatures`dict Optional Features	dict	All optional features to enhance and customize the Nudge experience for your employer's needs.	Default: —	Range: —
`attemptToFetchMajorUpgrade`boolean Attempt to Fetch Major Upgrade	boolean	When a major upgrade is required, Nudge will attempt to download it through the softwareupdate binary.	Default: true	Range: —
`acceptableApplicationBundleIDs`array Acceptable Application Bundle IDs	array	The application Bundle ID which Nudge allows without taking focus. (You can specify one or more Bundle ID.)	Default: —	Range: —
string acceptableApplicationBundleIDs	string	—	Default: —	Range: —
`acceptableAssertionUsage`boolean Acceptable Assertion Usage	boolean	When enabled, Nudge will not activate or re-activate when assertions are currently set.	Default: false	Range: —
`acceptableAssertionApplicationNames`array Acceptable Assertion Application Names	array	The application names using assertions which Nudge allows without taking focus. (You can specify one or more applications. To find the names please run /usr/bin/pmset -g assertions in terminal while the application is open and running)	Default: —	Range: —
string acceptableAssertionApplicationNames	string	—	Default: —	Range: —
`acceptableCameraUsage`boolean Acceptable Camera Usage	boolean	When enabled, Nudge will not activate or re-activate when the camera is on.	Default: false	Range: —
`acceptableScreenSharingUsage`boolean Acceptable Screen Sharing Usage	boolean	When enabled, Nudge will not activate or re-activate when screen sharing is active.	Default: false	Range: —
`aggressiveUserExperience`boolean Aggressive User Experience	boolean	When disabled, Nudge will not hide all non-acceptableApplicationBundleIDs after the requiredInstallationDate or allowedDeferrals.	Default: true	Range: —
`aggressiveUserFullScreenExperience`boolean Aggressive User Full Screen Experience	boolean	When disabled, Nudge will not create a blurred background when the user is past the deferral window.	Default: true	Range: —
`asynchronousSoftwareUpdate`boolean Asynchronous Software Update	boolean	When disabled, Nudge will wait for Software Update to finish downloading (if any) updates before showing the UI.	Default: true	Range: —
`attemptToBlockApplicationLaunches`boolean Attempt To Block Application Launches	boolean	When enabled, Nudge will attempt to block application launches after the required installation date. This key must be used in conjunction with blockedApplicationBundleIDs	Default: false	Range: —
`blockedApplicationBundleIDs`array Blocked Application Bundle IDs	array	The application Bundle ID which Nudge disallows from launching after the required installation date. (You can specify one or more Bundle ID.)	Default: —	Range: —
string blockedApplicationBundleIDs	string	—	Default: —	Range: —
`disableNudgeForStandardInstalls`boolean	boolean	When utilizing a SOFA feed and disableNudgeForStandardInstalls is true, Nudge will only enforce updates with published CVEs. Defaults to false.	Default: false	Range: —
`disableSoftwareUpdateWorkflow`boolean Disable Software Update Workflow	boolean	When disableSoftwareUpdateWorkflow is true, Nudge will not attempt to run the softwareupdate process. Defaults to false.	Default: false	Range: —
`enforceMinorUpdates`boolean Enforce Minor Updates	boolean	When enabled, Nudge will enforce minor updates. This should likely never be disabled.	Default: true	Range: —
`terminateApplicationsOnLaunch`boolean Terminate Applications On Launch	boolean	When enabled, Nudge will terminate the applications listed in blockedApplicationBundleIDs upon initial launch.	Default: false	Range: —
`acceptableUpdatePreparingUsage`boolean	boolean	When enabled, Nudge will not activate or re-activate when an update is being downloaded, prepared or staged.	Default: true	Range: —
`attemptToCheckForSupportedDevice`boolean	boolean	When disabled, Nudge will no longer compare the current device against the SOFA feed for the required update. If the device cannot install this update, Nudge will not present the Unsupported UI	Default: true	Range: —
`customSOFAFeedURL`string	string	A url path to use a custom SOFA feed.	Default: —	Range: —
`honorFocusModes`boolean	boolean	When enabled, Nudge will not activate or re-activate when a user is in DoNotDisturb/Focus status. This feature is expiremental and may not work in all user settings.	Default: false	Range: —
`honorCycleTimersOnExit`boolean	boolean	When enabled, Nudge will honor the current cycle timers when user's press the `Quit` button.	Default: false	Range: —
`refreshSOFAFeedTime`integer	integer	The maximum age the cached SOFA feed file can be on disk. When this file age expires, Nudge will re-assess the SOFA feed for updates. Please be mindful of changing this value as there is an associated cost for maintaining the SOFA service.	Default: 86400	Range: —
`utilizeSOFAFeed`boolean	boolean	When enabled, Nudge will utilize the SOFA feed url for update data.	Default: true	Range: —
`osVersionRequirements`array OS Version Requirements	array	The required components necessary to enforce an Operating System version through Nudge. Specify one array to enforce a single Operating System version across all machines or specify multiple arrays for specific enforcements.	Default: —	Range: —
`osVersionRequirement`dict osVersionRequirement	dict	—	Default: —	Range: —
`aboutUpdateURL`string About Update URL	string	A single URL, enabling the More Info button URL path. While this accepts a string, it must be a valid URL (http://, https://, file://). Note: If this value is passed with aboutUpdateURLs, the aboutUpdateURLs key will be ignored.	Default: —	Range: —
`aboutUpdateURLs`array About Update URLs	array	The aboutUpdateURL - per country localization.	Default: —	Range: —
dict aboutUpdateURL - Dictionary	dict	—	Default: —	Range: —
`_language`string	string	The targeted language locale for the user interface. Note: For a list of locales, please run the following command in Terminal: /usr/bin/locale -a	Default: —	Range: —
`aboutUpdateURL`string	string	The URL for the More Info button. While this accepts a string, it must be a valid URL (http://, https://, file://).	Default: —	Range: —
`majorUpgradeAppPath`string Major macOS Upgrade App Path	string	The app path for a major upgrade.	Default: —	Range: —
`requiredInstallationDate`string Required Installation Date	string	The required installation date for Nudge to enforce the required operating system version. You must follow a standard date string as YYYY-MM-DDTHH:MM:SSZ - Example: 2021-09-15T00:00:00Z. Required for Nudge versions 1.1.16 and below.	Default: —	Range: —
`requiredMinimumOSVersion`string Required Minimum OS Version required	string	The required minimum operating system version. Note: When passing versions such as `11.2.0`, it will be normalized to `11.2`. It is recommended to remove the trailing zero from the version number.	Default: —	Range: —
`targetedOSVersions`array Targeted OS Versions	array	The versions of macOS that require a security update. You can specify single version or multiple versions.	Default: —	Range: —
string	string	—	Default: —	Range: —
`targetedOSVersionsRule`string Targeted OS Versions Rule	string	The OS string rule for targeting Nudge events. You can target with "default", the full OS version (example: "11.5.1"). or the major OS version (example: "11").	Default: —	Range: —
`actionButtonPath`string	string	A path to a URI for opening alternative actions, like Jamf self service items.	Default: —	Range: —
`activelyExploitedCVEsMajorUpgradeSLA`integer	integer	When a major upgrade is under active exploit, this is the amount of days a user has to install the update.	Default: 14	Range: —
`activelyExploitedCVEsMinorUpdateSLA`integer	integer	When a minor update is under active exploit, this is the amount of days a user has to install the update.	Default: 14	Range: —
`nonActivelyExploitedCVEsMajorUpgradeSLA`integer	integer	When a major upgrade is not under active exploit but contains CVEs, this is the amount of days a user has to install the update.	Default: 21	Range: —
`nonActivelyExploitedCVEsMinorUpdateSLA`integer	integer	When a minor update is not under active exploit but contains CVEs, this is the amount of days a user has to install the update.	Default: 21	Range: —
`standardMajorUpgradeSLA`integer	integer	When a major upgrade has no known CVEs, this is the amount of days a user has to install the update.	Default: 28	Range: —
`standardMinorUpdateSLA`integer	integer	When a minor update has no known CVEs, this is the amount of days a user has to install the update.	Default: 28	Range: —
`unsupportedURL`string	string	A single URL, enabling the More Info button URL path when using the unsupported UI. While this accepts a string, it must be a valid URL (http://, https://, file://). Note: If this value is passed with aboutUpdateURLs, the aboutUpdateURLs key will be ignored.	Default: —	Range: —
`unsupportedURLs`array unsupportedURLs	array	The unsupportedURL - per country localization.	Default: —	Range: —
dict unsupportedURL - Dictionary	dict	—	Default: —	Range: —
`_language`string	string	The targeted language locale for the user interface. Note: For a list of locales, please run the following command in Terminal: /usr/bin/locale -a	Default: —	Range: —
`unsupportedURL`string	string	A single URL, enabling the More Info button URL path when using the unsupported UI. While this accepts a string, it must be a valid URL (http://, https://, file://). Note: If this value is passed with aboutUpdateURLs, the aboutUpdateURLs key will be ignored.	Default: —	Range: —
`minorVersionRecalculationThreshold`integer	integer	The amount of minor versions a device can be behind before the requiredInstallationDate is recalculated against a previous update.	Default: 0	Range: —
`userExperience`dict User Experience	dict	All features related to how Nudge refreshes and defines the user experience	Default: —	Range: —
`noTimers`boolean No Timers	boolean	This will disable all functionality related to the `userExperience` preference domain.	Default: false	Range: —
`allowedDeferrals`integer Allowed Deferrals	integer	The number of times a user can defer Nudge (change it from the currently active window) before the "aggressive user experience" is enabled.	Default: 1000000	Range: —
`allowGracePeriods`boolean Allow Grace Periods	boolean	Allows a device to modify the requiredInstallationDate logic and launch behavior. Useful for new device provisioning.	Default: false	Range: —
`allowUserQuitDeferrals`boolean Allow User Quit Deferrals	boolean	Allows the user to specify when they will next be prompted by Nudge. (Set to `False` to maintain v1.0.0 behavior.) When using this feature, Nudge will no longer adhere to your LaunchAgent logic as the user is specifying their own execution time for the next Nudge event.(See: `~/Library/Preferences/com.github.macadmins.Nudge.plist`.)	Default: true	Range: —
`gracePeriodInstallDelay`integer Grace Period Install Delay	integer	The amount of time in hours Nudge will extend the requiredInstallationDate for newly provisioned devices.	Default: 23	Range: —
`gracePeriodLaunchDelay`integer Grace Period Launch Delay	integer	The amount of time in hours Nudge will bypass launching for newly provided devices.	Default: 1	Range: —
`gracePeriodPath`string Grace Period Path	string	The path of the file Nudge will read and assess for allowGracePeriods.	Default: "/private/var/db/.AppleSetupDone"	Range: —
`imminentRefreshCycle`integer Imminent Refresh Cycle	integer	The amount of time in seconds Nudge will use as a timer to refresh the user interface if it is not the currently active window. This key is directly tied to its partner key `imminentWindowTime` to know when to trigger this timer.	Default: 600	Range: —
`allowedDeferralsUntilForcedSecondaryQuitButton`integer Allowed Deferrals until Forced Secondary Quit Button	integer	The number of times a user can defer Nudge (change it from the currently active window) before both quit buttons need to be actioned.	Default: 14	Range: —
`approachingRefreshCycle`integer Approaching Refresh Cycle	integer	The amount of time in seconds Nudge will use as a timer to refresh the user interface if it is not the currently active window. This key is directly tied to its partner key `approachingWindowTime` to know when to trigger this timer.	Default: 6000	Range: —
`approachingWindowTime`integer Approaching Window Time	integer	The amount of time in hours Nudge will use to determine that the `requiredInstallationDate` is "approaching".	Default: 72	Range: —
`elapsedRefreshCycle`integer Elapsed Refresh Cycle	integer	The amount of time in seconds Nudge will use as a timer to refresh the user interface if it is not the currently active window. This key is triggered once the `requiredInstallationDate` has expired.	Default: 300	Range: —
`imminentRefeshCycle`integer Imminent Refresh Cycle	integer	—	Default: 600	Range: —
`imminentWindowTime`integer Imminent Window Time	integer	The amount of time in hours Nudge will use to determine that the `requiredInstallationDate` is "imminent".	Default: 24	Range: —
`initialRefreshCycle`integer Initial Refresh Cycle	integer	The amount of time in seconds Nudge will use as a timer to refresh the user interface if it is not the currently active window. This key is triggered for all Nudge launches until the `approachingWindowTime` has been passed.	Default: 18000	Range: —
`maxRandomDelayInSeconds`integer Max Random Delay	integer	The maximum amount of delay Nudge will utilize before launching the UI. This is useful if you do not want your users to all receive the Nudge prompt at the exact time of the LaunchAgent. Note: This functionality only applies when also enabling `randomDelay`.	Default: 1200	Range: —
`nudgeRefreshCycle`integer Nudge Refresh Cycle	integer	The amount of time in seconds Nudge will use as its core timer to refresh all the core code paths. Note: While you can lower this setting, it could make Nudge too aggressive. Be mindful of decreasing this value.	Default: 60	Range: —
`randomDelay`boolean Random Delay	boolean	Enables an initial delay Nudge before launching the UI. This is useful if you do not want your users to all receive the Nudge prompt at the exact time of the LaunchAgent.	Default: true	Range: —
`allowLaterDeferralButton`boolean	boolean	Allows the user to press the `Later` button through the custom deferrals UI	Default: true	Range: —
`allowMovableWindow`boolean	boolean	Allows the user to move the Nudge window.	Default: false	Range: —
`calendarDeferralUnit`string	string	Utilize the approachingWindowTime or imminentWindowTime for calendar deferrals.	Default: "imminentWindowTime"	Range: —
`launchAgentIdentifier`string	string	The identifier of the Nudge LaunchAgent. Only set this if you use a custom identifier	Default: —	Range: —
`loadLaunchAgent`boolean	boolean	Loads the Nudge LaunchAgent using macOS Ventura's SMAppService API (macOS 13+ required).	Default: false	Range: —
`nudgeMajorUpgradeEventLaunchDelay`integer	integer	When a new major upgrade is posted to the SOFA feed, this can artificially delay the SOFA nudge events by x amount of days.	Default: 0	Range: —
`nudgeMinorUpdateEventLaunchDelay`integer	integer	When a new minor update is posted to the SOFA feed, this can artificially delay the SOFA nudge events by x amount of days.	Default: 0	Range: —
`userInterface`dict User Interface	dict	All features related to how Nudge defines the user interface.	Default: —	Range: —
`simpleMode`boolean Simple Mode	boolean	Enables Nudge to launch in the simplified user experience.	Default: false	Range: —
`forceScreenShotIcon`boolean Force Screenshot Icon	boolean	Force the built-in ScreenShot icon to render in the UI if a ScreenShot path is not passed.	Default: false	Range: —
`showDeferralCount`boolean Show Deferral Count	boolean	Enables or disables the deferral count of the current Nudge event.	Default: true	Range: —
`singleQuitButton`boolean single Quit Button	boolean	Only display one quit button regardless of proximity to the due date.	Default: false	Range: —
`iconDarkPath`string Dark Icon Path	string	A path to a local jpg, png, icns that contains the icon for dark mode. This will replace the Apple logo on the left side of Nudge.	Default: —	Range: —
`iconLightPath`string Light Icon Path	string	A path to a local jpg, png, icns that contains the icon for light mode. This will replace the Apple logo on the left side of Nudge.	Default: —	Range: —
`screenShotDarkPath`string Dark Screenshot Path	string	A path to a local jpg, png, icns that contains the screen shot for dark mode. This will replace the Big Sur logo on the lower right side of Nudge.	Default: —	Range: —
`screenShotLightPath`string Light Screenshot Path	string	A path to a local jpg, png, icns that contains the screen shot for light mode. This will replace the Big Sur logo on the lower right side of Nudge.	Default: —	Range: —
`actionButtonPath`string Action Button Path	string	A path to a URI for opening alternative actions, like Jamf self service items.	Default: —	Range: —
`fallbackLanguage`string Fallback Language	string	The language to revert to if no localizations are available for the device's current language.	Default: "en"	Range: —
`forceFallbackLanguage`boolean Force Fallback Language	boolean	Force the custom localizations to the value of `fallbackLanguage`.	Default: false	Range: —
`updateElements`array Update Elements	array	The individual buttons and text elements that can be customized for your employer's needs. This includes per country localization.	Default: —	Range: —
dict updateElement - Dictionary	dict	—	Default: —	Range: —
`_language`string Language	string	The targeted language locale for the user interface. Note: For a list of locales, please run the following command in Terminal: /usr/bin/locale -a	Default: —	Range: —
`customDeferralButtonText`string Custom Deferral Button Text	string	Modifies the customDeferralButtonText, also known as the "Custom" button.	Default: —	Range: —
`customDeferralDropdownText`string Custom Deferral Dropdown Text	string	customDeferralDropdownText, also known as the "Defer" button.	Default: —	Range: —
`oneDayDeferralButtonText`string One Day Deferral Button Text	string	Modifies the oneDayDeferralButtonText, also known as the "One Day" button.	Default: —	Range: —
`oneHourDeferralButtonText`string One Hour Deferral Button Text	string	Modifies the oneHourDeferralButtonText, also known as the "One Hour" button.	Default: —	Range: —
`informationButtonText`string Information Button Text	string	Modifies the informationButton, also known as the "More Info" button.	Default: —	Range: —
`mainContentHeader`string Main Content Header	string	Modifies the mainContentHeader. This is the "Your device will restart during this update" text.	Default: —	Range: —
`mainContentSubHeader`string Main Content Sub Header	string	Modifies the mainContentSubHeader. This is the "Updates can take around 30 minutes to complete" text.	Default: —	Range: —
`mainContentText`string Main Content Text	string	Modifies the `mainContentText`. This is the "A fully up-to-date device is required to ensure that IT can your accurately protect your device." text. (See the Wiki for information on adding line breaks.)	Default: —	Range: —
`mainContentNote`string Main Content Note	string	Modifies the mainContentNote. This is the "Important Notes" text.	Default: —	Range: —
`mainHeader`string Main Header	string	Modifies the `mainHeader`. This is the "Your device requires a security update" text.	Default: —	Range: —
`actionButtonText`string Action Button Text	string	Modifies the actionButton, also known as the "Update Device" button.	Default: —	Range: —
`primaryQuitButtonText`string Primary Quit Button Text	string	Modifies the `primaryQuitButton`, also known as the "Later" button.	Default: —	Range: —
`secondaryQuitButtonText`string Secondary Quit Button Text	string	Modifies the `secondaryQuitButton`, also known as the "I understand" button.	Default: —	Range: —
`subHeader`string Sub Header	string	Modifies the `subHeader`. This is the "A friendly reminder from your local IT team" text.	Default: —	Range: —
`actionButtonTextUnsupported`string	string	Modifies the primaryQuitButton, also known as the "Update Device" button when using the Unsupported UI.	Default: —	Range: —
`applicationTerminatedTitleText`string	string	Modifies the terminated application notification title.	Default: —	Range: —
`applicationTerminatedBodyText`string	string	Modifies the terminated application notification body.	Default: —	Range: —
`mainContentHeaderUnsupported`string	string	Modifies the mainContentHeader. This is the "Your device is no longer capable of receiving critical security updates" text when using the Unsupported UI.	Default: —	Range: —
`mainContentNoteUnsupported`string	string	Modifies the mainContentNote. This is the "Important Notes" text when using the Unsupported UI.	Default: —	Range: —
`mainContentSubHeaderUnsupported`string	string	Modifies the mainContentSubHeader. This is the "Please work with your local IT team to obtain a replacement device" text when using the Unsupported UI.	Default: —	Range: —
`mainContentTextUnsupported`string	string	Modifies the `mainContentText`. This is the "A fully up-to-date device is required to ensure that IT can your accurately protect your device." text when using the Unsupported UI. See the Wiki for information on adding line breaks.	Default: —	Range: —
`mainHeaderUnsupported`string	string	Modifies the `mainHeader`. This is the "Your device requires a security update" text when using the Unsupported UI.	Default: —	Range: —
`screenShotAltText`string	string	Modifies the accessible hover over on screen shots.	Default: —	Range: —
`subHeaderUnsupported`string	string	Modifies the `subHeader`. This is the "A friendly reminder from your local IT team" text when using the Unsupported UI.	Default: —	Range: —
`applicationTerminatedNotificationImagePath`string	string	A local image path for the notification event when Nudge terminates and application.	Default: —	Range: —
`requiredInstallationDisplayFormat`string	string	When utilizing showRequiredDate, set a custom display format. Be aware that the format you desire may not look good on the UI.	Default: —	Range: —
`showActivelyExploitedCVEs`boolean	boolean	When disabled, Nudge will not show the Actively Exploited CVEs in the left sidebar.	Default: true	Range: —
`showDaysRemainingToUpdate`boolean	boolean	When disabled, Nudge will not show the `Days Remaining To Update:` item on the left side of the UI.	Default: true	Range: —
`showRequiredDate`boolean	boolean	When enabled, Nudge will also show the requiredInstallationDate as string formatted date.	Default: false	Range: —
`json-url`string JSON Preference File Location	string	When configuring Nudge using a JSON-formatted preferences file located outside of the default location, set this key to the custom location using either a remote (https://) or a local (file://) URL, and leave other keys in this payload unset. Leave this key unset when configuring Nudge using the other keys in this payload.	Default: —	Range: —