userExperience - macadmins/nudge GitHub Wiki

Presentations

Overview of Nudge Lifecycle

Nudge-Process-Overview

Keys

allowGracePeriods - Type: Boolean, Default Value: false

v1.1.6 and higher only

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

v1.1.10 and higher only

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

allowUserQuitDeferrals - Type: Boolean, Default Value: True

v1.1.0 and higher only

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

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

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

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

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

calendarDeferralUnit - Type: String, Default Value: imminentWindowTime

Utilize the approachingWindowTime or imminentWindowTime for calendar deferrals. v1.1.12.81495 and higher only

elapsedRefreshCycle - Type: Integer, Default Value: 300

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

v1.1.6 and higher only

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

v1.1.6 and higher only

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

gracePeriodPath - Type: String, Default Value: /private/var/db/.AppleSetupDone

v1.1.6 and higher only

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

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

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

initialRefreshCycle - Type: Integer, Default Value: 18000

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

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

loadLaunchAgent - Type: Boolean, Default Value: False

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

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

noTimers - Type: Boolean, Default Value: False

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

nudgeRefreshCycle - Type: Integer, Default Value: 60

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: False

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.

Example (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 (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>
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️