Copyright 2023 DATA JAR LTD
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Notifier
Notifier is a Swift app which can post macOS alert or banner notifications on 10.10+ clients.
On macOS 10.10-10.14 the deprecated NSUserNotifications API is used, for 10.15+ the UserNotifications Framework are used.
This project was originally intended for use with jamJAR
Usage
Basic Usage
./Notifier.app/Contents/MacOS/Notifier
OVERVIEW: Notifier: Sends banner or alert notifications.
USAGE: notifier --type <alert/banner> --message <some message> <options>
OPTIONS:
--message message text - REQUIRED if not passing --remove all
--messageaction The action to be performed when the message is clicked. Either pass 'logout' or path to
item to open on click. Can be a .app, file, URL etc. With non-.app items being opened in
their default handler
--messagebutton alert type only. Sets the message buttons text
--messagebuttonaction alert type only. The action to be performed when the message button is clicked. Either
pass 'logout' or path to item to open on click. Can be a .app, file, URL etc. With non-.app
items being opened in their default handler. Requires '--messagebutton' to be passed
--remove "prior" or "all". If passing "prior", the full message will be required too. Including all
passed flags
--sound sound to play. Pass "default" for the default macOS sound, else the name of a sound in
/Library/Sounds or /System/Library/Sounds. If the sound cannot be found, macOS will use the
"default" sound
--subtitle message subtitle
--title message title
--type alert or banner - REQUIRED
--verbose Enables logging of actions. Check console for 'Notifier Log:' messages
--help Display available options
SEE ALSO: https://github.com/dataJAR/Notifier
When looking at the above, --messagebutton & --messagebuttonaction refer to the button for Alert notifications as shown in the green box.
Other verbs apply to the main message area, the red box.
Example Usage
Example 1 This example shows a basic banner notification.
/Applications/Utilities/Notifier.app/Contents/MacOS/Notifier --type banner --message "message"
Example 2 This example shows a basic alert notification.
/Applications/Utilities/Notifier.app/Contents/MacOS/Notifier --type alert --message "message" --messagebutton "Logout" --messagebuttonaction "Logout"
Example 3 This example shows both alert & banner notifications, (sleep used for the example gif, not needed in use but below for completeness sake).
/Applications/Utilities/Notifier.app/Contents/MacOS/Notifier --type alert --message "Please Logout" --messagebutton "Logout" --title "Logout"
sleep 2
/Applications/Utilities/Notifier.app/Contents/MacOS/Notifier --type banner --message "message" --title "Notification ;)"
Example 4 This example shows removal of a prior notification, (sleep used for the example gif, not needed in use but below for completeness sake).
/Applications/Utilities/Notifier.app/Contents/MacOS/Notifier --type alert --message 'Look at me!!'
sleep 5
/Applications/Utilities/Notifier.app/Contents/MacOS/Notifier --type alert --message "message" --messagebutton "Logout"
/Applications/Utilities/Notifier.app/Contents/MacOS/Notifier --type alert --message 'Look at me!!' --remove prior
Example 5 This example shows removal of all alert notifications, for banner alerts this will remove from Notification Center. Sleep used for the example gif, not needed in use but below for completeness sake.
/Applications/Utilities/Notifier.app/Contents/MacOS/Notifier --type alert --message "message" --messagebutton "Logout"
sleep 2
/Applications/Utilities/Notifier.app/Contents/MacOS/Notifier --type alert --message "message2" --messagebutton "Logout"
sleep 2
/Applications/Utilities/Notifier.app/Contents/MacOS/Notifier --type alert --message "message3" --messagebutton "Logout"
/Applications/Utilities/Notifier.app/Contents/MacOS/Notifier --type alert --remove all
Deployment
PKG
PKG's will be supplied for every release, & can be found in the releases section
This will place the Notifier.app within /Applications/Utilities/, removing /Applications/Utilities/Notifier.app if found prior.
macOS 10.15+
If running Notifier on macOS 10.15+, you'll want to deploy the supplied profile (https://github.com/dataJAR/Notifier/blob/master/profile/Allow%20Notifier%20Notifications.mobileconfig) to UAMDM devices.
This will allow Notifier to post Notifications without prompting the user to allow & needs to be deployed when a device is running 10.15+ & not before.
How it works
When using the deprecated NSUserNotifications API, the notification type (alert or banner), is defined by the NSUserNotificationAlertStyle key in the Applications info.plist.
For the UserNotifications Framework, the user can choose the notification type or an admin can define this in a profile.
Notifier follows the above rules, by actually being not one but three applications.
An enclosing Notifier.app & two sub apps, with one used to post Alert notifications & another Banner notifications. As per the below:
Notifier.app/Contents/Resources/
alert/Notifier - Alerts.app
banner/Notifier - Notifications.app
These sub applications contain code for both the NSUserNotifications API & UserNotifications Framework, as well as the relevant NSUserNotificationAlertStyle key in the Applications info.plist for the NSUserNotifications API.
The apps themselves seamlessly transition between the NSUserNotifications API when running on macOS 10.10-10.14, & the UserNotifications Framework when running on 10.15+ via the @available declaration attribute.
So why the Notifier.app?
This is to give a single app to call, the Notifier.app will also check the parsed args & then pass to the required sub application.
Notifier.app also checks tha Notification Center is running, & runs the sub apps in the user context. As well as having an enclosing Notifier.app allows for some of the rebrand options below without adjusting any code.
Rebranding
If you find the Notifier logo too garish &/or want to rename the notifications as they show in Notification Center, then you can follow the below rebrand guidelines.
NOTE: It's likely that these will change regularly, PR's accepted to correct &/or clarify any of the below or any or this README.
Requirements
- Apple Xcode
- A macOS developer account signed into Xcode
- A copy of this project downloaded, & the Notifier.xcodeproj file loaded into Xcode
Re-signing
Notifier is made up of three applications, the enclosing Notifier.app & the sub apps with one used to post Alert notifications & another Banner notifications.
As such, all three will need to be re-signed with your developer certificate & it is worth making sure this is all compile-able before proceeding.
See this guide, for where to change the signing identity per app.
(Note: You may also need to change the signing in "Build Settings" as well as "Signing and Capabilities" for each app.)
Those steps will need to be repeated for each of the three apps, & they are highlighted in the Xcode screenshot below:
Renaming
The name which is shown within Notification Center is the name of the applications themselves capitalised, so to change them follow the below. This will need to be repeated for both the Alert & Banner applications.
- Select the app that you're looking to rename in Xcode's project navigator.
Changing Icons
The application icons for the Alert & Banner applications can be changed to fit with your requirements.
At a minimum, you'll need a PNG of 1024 x 1024 for this.
But if you'd like to supply all the sizes offered, then you'll want PNG's in the below sizes:
• 1024 x 1024
• 512 x 512
• 256 x 256
• 128 x 128
• 64 x 64
• 32 x 32
• 16 x 16
Below is the process,
- Select the application that you're looking to change the icon in Xcode's project navigator, click the disclosure triangle for the application, click the sub folder, click "Assets.xcassets" & lastly click "AppIcon".
4. Now build the project to test, if the build fails please review the above & attempt again.
5. If you now test your new icons on a macOS device on which Notifier has run before, you'll likely see the previous icon. So test in a VM or try to reset Notification Center as per the Resetting Notifications Center steps below.
Miscellaneous
Resetting Notifications Center
The below should rest Notifications Center, but please test & submit a PR with a better method as applicable.
rm -rf $(getconf DARWIN_USER_DIR)/com.apple.notificationcenter/*- Logout & then log back in, or:
- For macOS 10.16+:
killall "NotificationCenter"
- Test the Notifier once more
FAQs
Q1: Why start at version 2?
A1: At dataJAR, we already had a v1 "Notifier" app deployed.
Q2: How can you post both banner & alert notifications?
A2: See How it works
Q3: The users are being prompted to allow.. help!
A3: This can be due to a few things:
- Was the notifications profile installed? If not, install.
- Was the notifications profile installed when running macOS 10.10-10.14? If it was, re-install when running 10.15+.
- Is the device under UAMDM? If not, check with your MDM vendor on making the device UAMDM. Then try again & maybe reinstall the profile once under UAMDM.
- Did you change the Bundle ID of either the Alert or Banner applications? If so you'll need to amend the notifications profile accordingly.
Q4: Is that logo magen...
A4: No, it's a shade of pink...
Q5: Banner or Notifications?
A5: The temporary notifications are referred to as "banner" notifications in Apple's documentation, but it seems that most folks call them "Notifications" with the persistent notifications being referred to as alerts by folks as well as within Apple's documentation.
Q6: I'm seeing alerts when expecting banner notifications, & vice versa
A6: Check step 12 of Renaming, it's likely the wrong app is in the wrong folder.
Q7: --remove prior, didn't clear my last message.
A7: Make sure you pass EXACTLY the same message to be cleared.
Q8: I've rebranded, but the old icon is being shown..
A8: Please reset Notification Center as per the Resetting Notifications Center, then try again.
Q9: I'm struggling with rebranding &/or would like some changes for my organisation that are bespoke to us.
A9: We should be able to help, please visit our website & fill out the contact form or join us in the #datajar channel on the macadmins.org slack & we can arrange a quote as needed.
Q10: The NSUserNotifications API was deprecated in 10.14, why not use the UserNotifications Framework for 10.14+ instead of 10.15+?
A10: Simply, macOS 10.14 didn't support managing the notification type via a profile, where 10.15+ does.
Q11: Some functionality is missing.. why is this?
A11: Notifier supports 10.10+, multiple API's & notification types. One of the main drivers was for consistency across the vast OS versions & differing API's, so if one API doesn't support a function.. it'll not be added to keep a consistent KISS approach.
Alternatives
The below projects can be used instead of Notifier & were very much instrumental in Notifiers creation