userExperience

User Experience

User Experience
- Preferences
- Examples and Additional Info

Preferences

`allowGracePeriods`

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.

`allowLaterDeferralButton`

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.

`allowUserQuitDeferrals`

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.

`allowedDeferrals`

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.

`allowedDeferralsUntilForcedSecondaryQuitButton`

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.

`approachingRefreshCycle`

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.

`approachingWindowTime`

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".

`calendarDeferralUnit`

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

Utilize the approachingWindowTime or imminentWindowTime for calendar deferrals.

`elapsedRefreshCycle`

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.

`gracePeriodInstallDelay`

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)

`gracePeriodLaunchDelay`

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.

`gracePeriodPath`

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.

`imminentRefreshCycle`

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.

`imminentWindowTime`

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".

`initialRefreshCycle`

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.

`launchAgentIdentifier`

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.

`loadLaunchAgent`

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+.

`maxRandomDelayInSeconds`

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

`noTimers`

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

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

`nudgeMajorUpgradeEventLaunch`

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.

`nudgeMinorUpdateEventLaunchDelay`

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.

`nudgeRefreshCycle`

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.

`randomDelay`

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.

Examples and Additional Info

Presentations

JNUC 2021 Presentation - Nudge User Experience Preferences Overview

Overview of Nudge Lifecycle

Example Configuration - JSON

{
  "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"
  }
}

Example Configuration - Mobile Configuration

<?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>