User Deferrals

Introduction

While the user deferrals feature was technically available in v1.0.0 of Nudge, it was only calculated per active Nudge session. (After closing Nudge and re-opening, the deferral count would be reset to 0.)

With v1.1.0 and later, user deferrals are now saved and maintained across the entirety of a Nudge event.

NSUserDefaults

Nudge saves the following keys in ~/Library/Preferences/com.github.macadmins.Nudge.plist

• deferRunUntil
• requiredMinimumOSVersion
• userDeferrals
• userQuitDeferrals
• userSessionDeferrals

Resetting values when a new Nudge event is detected

When Nudge first launches, it determines what Nudge event is configured and compares the requiredMinimumOSVersion key of the JSON / Mobile Configuration against requiredMinimumOSVersion key in NSUserDefaults.

If the value in your configuration is higher than the value in NSUserDefaults the following occurs:

• Log event: New Nudge event detected - resetting all deferral values
• deferRunUntil key is deleted
• userDeferrals, userQuitDeferrals and userSessionDeferrals are reset to 0

Types of user deferrals

There are two types of user deferrals: Session Deferrals and Quit Deferrals.

• Session Deferrals are the amount of times Nudge was not the foremost application when the built-in nudge timer was passed.
  • The count is saved to userSessionDeferrals
• Quit Deferrals are the amount of times Nudge was exited out by the user
  • The count is saved to userQuitDeferrals

Session and Quit Deferrals values are combined for all Nudge logic and saved to userDeferrals

Defer buttons

There are four buttons available to the user. The text is customizable following the updateElements key structure.

• primaryQuitButton - primaryQuitButtonText
• One Day - oneDayDeferralButtonText
• One Hour - oneHourDeferralButtonText
• Custom - customDeferralButtonText

Behavior of Defer buttons

As the Nudge event gets closer and closer, some of the user deferral buttons will no longer be displayed to the end-user.

• If the the amount of hours from the current date to the requiredInstallationDate is greater than 0, the one hour button will appear
• If the the amount of hours from the current date to the requiredInstallationDate is greater than the imminentWindowTime, the one day button will appear
• If the the amount of hours from the current date to the requiredInstallationDate is greater than the approachingWindowTime, the custom button will appear

You will see log events showing what is allowed

Device allow1HourDeferralButton: true
Device allow24HourDeferralButton: true
Device allowCustomDeferralButton: false

Clicking on the customDeferralButton opens a new UI, where the user is presented all available times that they can select. The user is not allowed to select a time in the past, nor select a time that is passed the amount of daysRemaining minus imminentWindowTime (converted into days by dividing the value by 24).

Example:

{
    "osVersionRequirements": [
      {
        "requiredInstallationDate": "2021-08-30T00:00:00Z",
        "requiredMinimumOSVersion": "11.5.2"
      }
    ],
  "userExperience": {
    "approachingWindowTime": 72,
    "imminentWindowTime": 24
  },
}

• If the current date was 2021-08-01T00:00:00Z, all buttons would be selectable and the user could use custom deferral up until 2021-08-28T00:00:00Z
• If the current date was 2021-08-28T00:00:00Z, the one hour and one day buttons would be selectable
• If the current date was 2021-08-29T00:00:00Z, only the one hour button would be selectable

Notes

customDeferral UI Behavior

userQuitDeferrals and LaunchAgent behavior

It is very likely that your LaunchAgent timing will no longer occur when utilizing userQuitDeferrals. For instance, if you have Nudge set to launch every 30 minutes, but a user has deferred for a day, you will lose up to 24 nudge events. If you do not want this behavior, it is recommended to disable user deferrals with the allowUserQuitDeferrals key.

Timestamps and logging

When utilizing the Nudge Logging LaunchDaemon, the log events are always saved with the machine's local time, while Nudge calculates and saves all time via UTC (GMT timezone). This is a cosmetic issue.

Testing and resetting Nudge

If you are an admin and want to reset Nudge's user deferral behavior, simply run the following Terminal command

defaults delete ~/Library/Preferences/com.github.macadmins.Nudge.plist