• User Experience
  • Preferences
    • allowGracePeriods
    • allowLaterDeferralButton
    • allowUserQuitDeferrals
    • allowedDeferrals
    • allowedDeferralsUntilForcedSecondaryQuitButton
    • approachingRefreshCycle
    • approachingWindowTime
    • calendarDeferralUnit
    • elapsedRefreshCycle
    • gracePeriodInstallDelay
    • gracePeriodLaunchDelay
    • gracePeriodPath
    • imminentRefreshCycle
    • imminentWindowTime
    • initialRefreshCycle
    • launchAgentIdentifier
    • loadLaunchAgent
    • maxRandomDelayInSeconds
    • noTimers
    • nudgeMajorUpgradeEventLaunch
    • nudgeMinorUpdateEventLaunchDelay
    • nudgeRefreshCycle
    • randomDelay
  • Examples and Additional Info
    • Presentations
    • Overview of Nudge Lifecycle
    • Example Configuration - JSON
    • Example Configuration - Mobile Configuration

• Type: Boolean
• Default Value: False
• Required: No
• Version: v1.1.6 and later

Allows a device to modify the requiredInstallationDate logic and launch behavior. Useful for new device provisioning.

When using this feature, Nudge will remind the user after the grace period.

• Type: Boolean
• Default Value: True
• Required: No
• Version: v1.1.10 and later

Allows the user to press the Later button through the custom deferrals UI.

• Type: Boolean
• Default Value: True
• Required: No
• Version: v1.1.0 and later

Allows the user to specify when they will next be prompted by Nudge. Set to False to maintain v1.0.0 functionality (Show only 'Later' defer option).

When using this feature, Nudge will continue to honour your existing LaunchAgent configuration but Nudge will evaluate if it should become active each launch.

For example in the case of when you have a LaunchAgent which launches Nudge at the 0th and 30th minute of the hour:

• A user has deferred Nudge to 2022-07-27 09:50:12 +0000, Nudge won't launch at this time. It will wait for the LaunchAgent.

• When Nudge is next triggered by the LaunchAgent at the 0th minute of the hour, Nudge will check the deferRunUntil against the time Nudge is launched.

• If the deferRunUntil is less than the time Nudge is launched then Nudge will activate (appear in main window).

• Where as if deferRunUntil is greater than the time Nudge is launched then Nudge will exit.

• deferRunUntil key is stored via NSUserDefaults (~/Library/Preferences/com.github.macadmins.Nudge.plist) to track when the next time Nudge should launch.

• deferRunUntil also uses UTC timestamps. There may be cases where the log event you view shows local time, where the Nudge event is in UTC time. This is expected behavior and is merely cosmetic.

• Type: Integer
• Default Value: 1000000
• Required: No
• Version: v1.1.0 and later

The number of times a user can defer Nudge (change it from the currently active window) before the "aggressive user experience" is enabled.

• Type: Integer
• Default Value: 14
• Required: No
• Version: v1.1.0 and later

The number of times a user can defer Nudge (change it from the currently active window) before both the "I Understand" and defer quit buttons need to be actioned.

• Type: Integer
• Default Value: 6000
• Required: No
• Version: v1.1.0 and later

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.

• Type: Integer
• Default Value: 72
• Required: No
• Version: v1.1.0 and later

The amount of time in hours Nudge will use to determine that the requiredInstallationDate is "approaching".

• Type: String
• Default Value: imminentWindowTime
• Required: No
• Version: v1.1.12.81495 and later

Utilize the approachingWindowTime or imminentWindowTime for calendar deferrals.

• Type: Integer
• Default Value: 300
• Required: No
• Version: v1.1.0 and later

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.

• Type: Integer
• Default Value: 23
• Required: No
• Version: v1.1.6 and later

The amount of time in hours Nudge will extend the requiredInstallationDate for newly provisioned devices via DEP (if gracePeriodPath is not defined and not set to /private/var/db/.AppleSetupDone)

• Type: Integer
• Default Value: 1
• Required: No
• Version: v1.1.6 and later

The amount of time in hours Nudge will bypass launching for newly provided devices.

• Type: String
• Default Value: /private/var/db/.AppleSetupDone
• Required: No
• Version: v1.1.6 and later

The path of the file Nudge will read and assess for allowGracePeriods. Nudge uses this file's creation timestamp for grace period calculations. The file /private/var/db/.AppleSetupDone is created automatically after finishing the Apple Setup Assistant.

• Type: Integer
• Default Value: 600
• Required: No
• Version: v1.1.0 and later

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.

• Type: Integer
• Default Value: 24
• Required: No
• Version: v1.1.0 and later

The amount of time in hours Nudge will use to determine that the requiredInstallationDate is "imminent".

• Type: Integer
• Default Value: 18000
• Required: No
• Version: v1.1.0 and later

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.

• Type: String
• Default Value: com.github.macadmins.Nudge
• Required: No
• Version: v1.1.13.81503 and later

The identifier of the Nudge LaunchAgent. Only set this if you use a custom identifier.

• Type: Boolean
• Default Value: False
• Required: No
• Version: v1.1.13.81503 and later

Loads the Nudge LaunchAgent using macOS Ventura's SMAppService API (macOS 13+ required).

This Key is experimental because the SMAppService API seems to be buggy in macOS 13+.

• Type: Integer
• Default Value: 1200
• Required: No
• Version: v1.1.0 and later

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 randomDelay is enabled

• Type: Boolean
• Default Value: False
• Required: No
• Version: v1.1.0 and later

This will disable all functionality related to the userExperience preference domain.

• Type: Integer
• Default Value: 0
• Required: No
• Version: v2.0 and later

When a new major upgrade is posted to the SOFA feed, this can artificially delay the SOFA nudge events by x amount of days.

• Type: Integer
• Default Value: 0
• Required: No
• Version: v2.0 and later

When a new minor update is posted to the SOFA feed, this can artificially delay the SOFA nudge events by x amount of days.

• Type: Integer
• Default Value: 60
• Required: No
• Version: v1.1.0 and later

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.

• Type: Boolean
• Default Value: True
• Required: No
• Version: v1.1.0 and later

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.

• JNUC 2021 Presentation - Nudge User Experience Preferences Overview

{
  "userExperience": {
    "allowUserQuitDeferrals": true,
    "allowedDeferrals": 1000000,
    "allowedDeferralsUntilForcedSecondaryQuitButton": 14,
    "approachingRefreshCycle": 6000,
    "approachingWindowTime": 72,
    "elapsedRefreshCycle": 300,
    "imminentRefreshCycle": 600,
    "imminentWindowTime": 24,
    "initialRefreshCycle": 18000,
    "maxRandomDelayInSeconds": 1200,
    "noTimers": false,
    "nudgeRefreshCycle": 60,
    "randomDelay": false,
    "allowGracePeriods": true,
    "gracePeriodInstallDelay": 4,
    "gracePeriodLaunchDelay": 1,
    "gracePeriodPath": "/private/var/db/.AppleSetupDone"
  }
}

<?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>PayloadContent</key>
    <array>
      <dict>
        <key>PayloadDescription</key>
        <string>Configures userExperience preferences</string>
        <key>PayloadDisplayName</key>
        <string>Nudge Preferences</string>
        <key>PayloadIdentifier</key>
        <string>com.github.macadmins.Nudge.preferences.example.userExperience</string>
        <key>PayloadOrganization</key>
        <string></string>
        <key>PayloadType</key>
        <string>com.github.macadmins.Nudge</string>
        <key>PayloadUUID</key>
        <string>CA02957C-7472-446B-9F77-3E0414405556</string>
        <key>PayloadVersion</key>
        <integer>1</integer>
        <key>userExperience</key>
        <dict>
          <key>allowUserQuitDeferrals</key>
          <true/>
          <key>allowedDeferrals</key>
          <integer>1000000</integer>
          <key>allowedDeferralsUntilForcedSecondaryQuitButton</key>
          <integer>14</integer>
          <key>approachingRefreshCycle</key>
          <integer>6000</integer>
          <key>approachingWindowTime</key>
          <integer>72</integer>
          <key>elapsedRefreshCycle</key>
          <integer>300</integer>
          <key>imminentRefreshCycle</key>
          <integer>600</integer>
          <key>imminentWindowTime</key>
          <integer>24</integer>
          <key>initialRefreshCycle</key>
          <integer>18000</integer>
          <key>maxRandomDelayInSeconds</key>
          <integer>1200</integer>
          <key>noTimers</key>
          <false/>
          <key>nudgeRefreshCycle</key>
          <integer>60</integer>
          <key>randomDelay</key>
          <false/>
          <key>allowGracePeriods</key>
          <true/>
          <key>gracePeriodInstallDelay</key>
          <integer>4</integer>
          <key>gracePeriodLaunchDelay</key>
          <integer>1</integer>
          <key>gracePeriodPath</key>
          <string>/private/var/db/.AppleSetupDone</string>
        </dict>
      </dict>
    </array>
    <key>PayloadDescription</key>
    <string>Configures Nudge application</string>
    <key>PayloadDisplayName</key>
    <string>Nudge</string>
    <key>PayloadIdentifier</key>
    <string>com.github.macadmins.Nudge.example.userExperience</string>
    <key>PayloadOrganization</key>
    <string>Nudge</string>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>2F54F734-132D-4539-B583-F1DCF23DB5EB</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
  </dict>
</plist>