Getting Started - macadmins/nudge GitHub Wiki

Nudge has two main items that must be configured for it to be useful in production. They are a LaunchAgent and a Configuration. Nudge is configured using two primary methods:

• Configuration Profile (Typically delivered via MDM)
• JSON file

We will explore a basic LaunchAgent as well as both methods of configuring nudge using the examples found in Example Assets

The first step is to install Nudge.app itself. Nudge is extremely safe to install without configuration as it doesn't do anything unless it is configured and has a LaunchAgent configured to open it on a cadence. Install the latest version from the releases page. You will want the package that has a name similar to Nudge-1.x.x.x.x.x.pkg.

Alternatively, use the following .sh script to install the latest version published.

Before we are ready to create a LaunchAgent, we must pick a configuration method and confirm it is working as intended.

Configuration Profile

JSON file

First, grab a copy of the example configuration profile from Example Assets. It is named com.github.macadmins.Nudge.mobileconfig and can be downloaded by clicking the file name, selecting Raw in upper right corner of the code box, then right click anywhere in the page, select Save As... and save it in your favorite directory.

This configuration profile contains all of the default values for Nudge itself. Deploying it as-is would not be very useful, so we will customize the settings first.

Only settings which are different from the defaults need to be changed. For instance, if you want to change the text on the quit button, you would change the primaryQuitButtonText key. If you are happy with the default text of "Later", you do not need to set the key

First we will make the most basic config profile we can. Delete everything out of the downloaded example profile except for the following items:

<?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 all Nudge preferences</string>
        <key>PayloadDisplayName</key>
        <string>Nudge Preferences</string>
        <key>PayloadIdentifier</key>
        <string>com.github.macadmins.Nudge.preferences.example</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>osVersionRequirements</key>
        <array>
          <dict>
            <key>requiredInstallationDate</key>
            <date>2021-08-28T00:00:00Z</date>
            <key>requiredMinimumOSVersion</key>
            <string>11.2.1</string>
          </dict>
        </array>
      </dict>
    </array>
    <key>PayloadDescription</key>
    <string>Configures Nudge application</string>
    <key>PayloadDisplayName</key>
    <string>Nudge (v1.1.0) Example</string>
    <key>PayloadIdentifier</key>
    <string>com.github.macadmins.Nudge.example</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>

Within this profile, we will focus on the osVersionRequirements key:

        <key>osVersionRequirements</key>
        <array>
          <dict>
            <key>requiredInstallationDate</key>
            <date>2021-08-28T00:00:00Z</date>
            <key>requiredMinimumOSVersion</key>
            <string>11.2.1</string>
          </dict>
        </array>

The primary keys which are required for Nudge to do its thing are as follows:

requiredInstallationDate is the required installation date for Nudge to enforce the required operating system version.

requiredMinimumOSVersion is the required minimum operating system version. That is, Nudge will ask people to update until they are at this version or later. If the current version of macOS is higher than or equal to the requiredMinimumOSVersion, Nudge will not open.

To ensure we always get a prompt while testing, we need to make sure the version of macOS that we are running Nudge on is below the value in requiredMinimumOSVersion.

For example, if you are currently on macOS 11.3.0, the above config means you would never see Nudge launch as you are already up to date.

Tweak the osVersionRequirements values so it looks like the values below. If this is being read in the distant future, you will need to change the requiredInstallationDate to something reasonable. Note: This is ONLY for testing purposes, never deploy it this way in production.

        <key>osVersionRequirements</key>
        <array>
          <dict>
            <key>requiredInstallationDate</key>
            <date>2021-08-01T00:00:00Z</date>
            <key>requiredMinimumOSVersion</key>
            <string>11.99.1</string>
          </dict>
        </array>

Save the profile changes, double click it, go to System Preferences => Profiles and click install at the top. Once the profile is installed, open Nudge.app (found in /Applications/Utilities/Nudge.app)

If everything went well, you should be able to open Nudge.app and it should ask you to update macOS to the required version. If this did not happen, now is a good time to look at the documentation for Logging. For general logging around nudge, the go-to is the following log command:

log stream --predicate 'subsystem == "com.github.macadmins.Nudge"' --style syslog --color none

Now that we know the config is triggering nudge, lets change the configuration to something more suitable for production use:

        <key>osVersionRequirements</key>
        <array>
          <dict>
            <key>requiredInstallationDate</key>
            <date>2021-08-01T00:00:00Z</date>
            <key>requiredMinimumOSVersion</key>
            <string>11.2.3</string>
          </dict>
        </array>

After changing the config as shown above, save it, reinstall it and run Nudge. If you are already on 11.2.3+, Nudge shouldn't open at all. If you are on an older version of macOS, you should get the Nudge prompt to update. For versions that should be listed in targetedOSVersions, the wikipedia page for macOS 11 is a good place to start.

It is worth noting that if you are requiring version 11.2.3, make sure to only target versions prior to that in targetedOSVersions.

To do a simple test with the LaunchAgent, continue on to the LaunchAgent section of this guide.

First, grab a copy of the example JSON configuration file from Example Assets. It is named com.github.macadmins.Nudge.json and can be downloaded by clicking the file name, selecting Raw in upper right corner of the code box, then right click anywhere in the page, select Save As... and save it in your favorite directory.

This JSON configuration contains all of the default values for Nudge itself. Deploying it as-is would not be very useful, so we will customize the settings first.

Only settings which are different from the defaults need to be changed. For instance, if you want to change the text on the quit button, you would change the primaryQuitButtonText key. If you are happy with the default text of "Later", you do not need to set the key

First we will make the most basic JSON config we can. Delete everything out of the downloaded example JSON except for the following items:

{
    "osVersionRequirements": [
        {
            "requiredInstallationDate": "2021-02-28T00:00:00Z",
            "requiredMinimumOSVersion": "11.2.1",
        }
    ]
}

The primary keys which are required for Nudge to do its thing are as follows:

requiredInstallationDate is the required installation date for Nudge to enforce the required operating system version.

requiredMinimumOSVersion is the required minimum operating system version. That is, Nudge will ask people to update until they are at this version or later. If the current version of macOS is higher than or equal to the requiredMinimumOSVersion, Nudge will not open.

To ensure we always get a prompt while testing, we need to make sure the version of macOS that we are running Nudge on is well as below the value in requiredMinimumOSVersion.

For example, if you are currently on macOS 11.3.0, the above config means you would never see Nudge launch as you are already up to date.

Tweak the osVersionRequirements values so it looks like the values below. If this is being read in the distant future, you will need to change the requiredInstallationDate to something reasonable. Note: This is ONLY for testing purposes, never deploy it this way in production.

{
    "osVersionRequirements": [
        {
            "requiredInstallationDate": "2021-08-01T00:00:00Z",
            "requiredMinimumOSVersion": "11.99.1",
        }
    ]
}

Save the JSON changes, and copy it into the default config location using the following command:

 sudo cp ./com.github.macadmins.Nudge.json /Library/Preferences/

If everything went well, you should be able to open Nudge.app and it should ask you to update macOS to the required version. If this did not happen, now is a good time to look at the documentation for Logging. For general logging around nudge, the go-to is the following log command:

log stream --predicate 'subsystem == "com.github.macadmins.Nudge"' --style syslog --color none

Now that we know the config is triggering nudge, lets change the configuration to something more suitable for production use:

{
    "osVersionRequirements": [
        {
            "requiredInstallationDate": "2021-08-01T00:00:00Z",
            "requiredMinimumOSVersion": "11.2.3",
        }
    ]
}

After changing the config as shown above, save it, copy it into place and run Nudge. If you are already on 11.2.3+, Nudge shouldn't open at all. If you are on an older version of macOS, you should get the Nudge prompt to update. For versions that should be listed in targetedOSVersions, the wikipedia page for macOS 11 is a good place to start.

It is worth noting that if you are requiring version 11.2.3, make sure to only target versions prior to that in targetedOSVersions.

To do a simple test with the LaunchAgent, continue on to the LaunchAgent section of this guide.

For attemptToBlockApplicationLaunches and terminateApplicationsOnLaunch it is useful if a Notification Profile is implimented for Nudge. Otherwise the user will not see what caused the application to be closed.

The Notification Profile must be configured in the MDM as described below. The preference domain for the Profile is com.apple.notificationsettings.

<?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>NotificationSettings</key>
    <array>
      <dict>
        <key>BundleIdentifier</key>
        <string>com.github.macadmins.Nudge</string>
        <key>NotificationsEnabled</key>
        <true/>
        <key>AlertType</key>
        <integer>2</integer>
        <key>ShowInLockScreen</key>
        <true/>
        <key>ShowInNotificationCenter</key>
        <true/>
        <key>BadgesEnabled</key>
        <true/>
        <key>SoundsEnabled</key>
        <true/>
      </dict>
    </array>
  </dict>
</plist>

For the launchagent, there is a default option available that will work for most everyone unless you use a non-standard location for the json configuration file.

An Apple package for this LaunchAgent can be found on the releases page.

To use the default LaunchAgent, install the latest version of the Nudge_LaunchAgent-x.x.x.pkg package. It will place the LaunchAgent and load it in the current active console user's session.

Congratulations, you now have a working Nudge config!

If the window is closed: The launch agent frequency (every 30 minutes with the default LA) controls how often the window will be re-launched

OR

If the window is open and not in focus: The <window>RefreshCycle keys control how often it is brought back to the front, also re-activating any enabled aggressive mode features based on the window.

These settings do not interact, overlap, conflict, contradict, feed off each other, or go out for drinks after work. The LaunchAgent controls the behavior when nudge is not open. The RefreshCycles control the behavior when it's open.

After Nudge's first launch for an event, the timing is mainly controlled by the deferral time, but the actual timing of the popup can be later than the exact deferral time set based on the timing set in the LA. If a user defers for an hour at 12:10 (deferral time set to 1:10), nudge will launch 20 minutes later at 12:30 and quit because it hasn't reached the deferral time. It will run again at 1:00 and quit again. Finally at 1:30, 20 minutes after the deferral time, nudge will launch and prompt the user.

It may be tempting to increase the LA frequency to have more accurate deferrals. Keep in mind that if you do, users who defer with the Later option will see more frequent popups. That option just defers until the next launch. You may want to disable the later option if you care about accurate deferral times. (I think the later option is one of the best features though, and well worth the trade-off. It can trick some of the very laziest users into being nudged more often!)