Usage
In the follow images you can see all the customizable elements for each UI.
Please see more HERE about the Onboarding UI.
~/IBM\ Notifier.app/Contents/MacOS/IBM\ Notifier [-type] [-payload] [-bar_title] [-title] [-subtitle] [-icon_path] [-accessory_view_type] [-accessory_view_payload] [-main_button_label] [-main_button_cta_type] [-main_button_cta_payload] [-secondary_button_label] [-secondary_button_cta_type] [-secondary_button_cta_payload] [-tertiary_button_label] [-tertiary_button_cta_type] [-tertiary_button_cta_payload] [-help_button_cta_type] [-help_button_cta_payload] [-timeout] [-always_on_top]
The available arguments list varies based on the type of UI you're trying to show to the end user, except for the -type argument of course, in fact some of these are specific for the Pop-up UI or the Onboarding UI.
-type (Mandatory)
Value: [ popup | systemalert | banner | alert | onboarding (available from v2.0.0) ]
The UI type of the notification.
Example: -type popup
-title
Value: "text"
The title of the notification.
Example: -title "Title"
-subtitle
Value: "text"
The subtitle of the notification.
Example: -subtitle "Subtitle"
-main_button_label
Value: "text"
The label of the main button
Example: -main_button_label "Main button title"
-main_button_cta_type
Values:
- none: exit with the related return value;
- link: exit with the related return value and trigger the link defined in the payload.
The call to action type for the main button (default: none -> exit).
Example: -main_button_cta_type link
-main_button_cta_payload
Value: "text"
An URL if [ link ] cta type defined.
Example: -main_button_cta_payload "URL"
-secondary_button_label
Value: "text"
The label of the secondary button.
Example: -secondary_button_label "Secondary button title"
-secondary_button_cta_type
Values:
- none: exit with the related return value;
- link: exit with the related return value and trigger the link defined in the payload.
The call to action type for the secondary button (default: none -> exit).
Example: -secondary_button_cta_type link
-secondary_button_cta_payload
Value: "text"
An URL if [ link ] cta type defined.
Example: -secondary_button_cta_payload "URL"
-tertiary_button_label
Value: "text"
The label of the tertiary button.
Example: -tertiary_button_label "Tertiary button title"
-tertiary_button_cta_type
Values:
- link: trigger the link defined in the payload;
- exitlink: exit with the related return value and trigger the link defined in the payload.
The call to action type for the tertiary button.
Example: -tertiary_button_cta_type link
-tertiary_button_cta_payload
Value: "text"
A mandatory URL if [ link ] cta type defined, you can leave it empty if [ exitlink ] cta defined.
Example: -tertiary_button_cta_type link -tertiary_button_cta_payload "URL"
Example 2: -tertiary_button_cta_type exitlink -tertiary_button_cta_payload ""
-bar_title
Value: "text"
The bar title for the "popup" UI type. Not used for "banner" UI type.
Example: -bar_title "Bar Title"
-title_size (available from v2.5.0)
Value: integer
The title font size
Example: -title_size 16
-icon_path
Value: "text"
The local or remote URL for a custom icon defined for this notification. Despite the name it does accept also base64 encoded images and SF Symbol name.
Remote URL and Base64 images support has been implemented in v2.7.0.
SF Symbol support has been implemented in v3.0.0.
Example: -icon_path "~/Icon/Path.png"
-icon_width (available from v2.5.0)
Value: integer
The custom icon width defined for this notification (Max. 150px)
Example: -icon_width 150
-icon_height (available from v2.5.0)
Value: "text"
The custom icon height defined for this notification (Max. 300px)
Example: -icon_height 300
-accessory_view_type
Value:
- whitebox: white box with the text defined in the payload;
- timer: countdown with the value defined in the payload;
- image: image from the url/path defined in the payload;
- video: video from the url/path defined in the payload;
- progressbar: progress bar with the starting valued defined in the payload;
- input: input field;
- secureinput: secure input field;
- html: text in html format;
- htmlwhitebox: white box with text in html format;
- dropdown: a drop down style selector;
- checklist: a list of elements with check boxes;
- datepicker: a date and time picker; (available from v3.0.0)
- slideshow: a slideshow of multiple images; (available from v3.1.0)
The UI type for the needed accessory view.
Example: -accessory_view_type whitebox
-accessory_view_payload
Value: "text"
The payload for the accessory view:
- Text for [ whitebox ] view type;
- (up to v2.0.0) Seconds for [ timer ] view type;
- (from v2.1.0) Text for [ timer ] view type. This will be timer's label. Use "%@" to define timer's position inside the label. Use [ -timeout ] argument to define timer's duration;
- File path/link for [ image | video ] view type;
- Text with the format "/percent DOUBLE /top_message TEXT /bottom_message TEXT /user_interaction_enabled BOOL /user_interruption_allowed BOOL" for [ progressbar ] view type;
- Text with the format "/placeholder TEXT /title TEXT /value TEXT /required" for the [ input | secureinput ] view type;
- Text with the format "/list ITEM\nITEM\nITEM /selected INT /placeholder TEXT /title TEXT" for [ dropdown ] view type;
- Text with HTML format for [ html | htmlwhitebox ] view type;
- Text with the format "/list ITEM\nITEM\nITEM /preselection ITEM_INDEX ITEM_INDEX ITEM_INDEX /required /complete /title TEXT /radio" for [ checklist ] view type.
- Text with the format "/title TEXT /preselection DATE WITH FORMAT yyyy-MM-dd hh:mm:ss /style TEXT /components TEXT" for the [ date picker ] view type.
/style value options: [ graphical | field | compact | stepperfield ]
/components value options: [ date | time | dateandtime ]
- Text with the format "/images URL\nURL\nURL /autoplay /delay INT" for the [ slideshow ] view type/
Example 1: -accessory_view_payload "This is the time left: %@" (from v2.1.0)
Example 2: -accessory_view_payload "/percent 0 /top_message This is the top message /bottom_message This is the bottom message"
Example 3: -accessory_view_payload "/percent indeterminate /top_message This is the top message /bottom_message This is the bottom message"
Example 4: -accessory_view_payload "<h1>Hello, world!</h1>this is a line of text<br><br><code>this is a code block<br>this is the second line of a code block</code><br>this is <span style=\"color: #ff0000\">red</span> text".
Example 5: -accessory_view_payload "/title Some title /preselection 2023-01-01 13:00:00 /style stepperfield /components date"
Example 6: -accessory_view_payload "/images /path/to/image.jpg\nhttps://www.url.to/image.png\nhttps://www.url.to/image.png /autoplay /delay 3"
-secondary_accessory_view_type (deprecated in v3.2.0)
Same as for the -accessory_view_type argument.
-secondary_accessory_view_payload (deprecated in v3.2.0)
Value: "text"
Same as for the -accessory_view_payload argument.
-accessory_view_type_N (available from v3.2.0)
Value: Same as for the -accessory_view_type argument.
The tool support multiple accessory views on each [ popup ].
Example 1: accessory_view_type_1 image;
Example 2: accessory_view_type_2 dropdown;
-accessory_view_payload_N (available from v3.2.0)
Value: Same as for the -accessory_view_payload argument.
The tool support multiple accessory views on each [ popup ].
Example 1: accessory_view_payload_1 "path/or/URL/to/file"
Example 2: accessory_view_payload_2 "/list One\nTwo\nThree"
For more details about the available Accessory Views for the Pop-up UI please see here.
-help_button_cta_type
Value:
- link: trigger the url defined in the payload;
- infopopup: shows an info pop-up with the text defined in the payload;
The call to action type for the help button.
Example: -help_button_cta_type link
-help_button_cta_payload
Value: "text"
An URL for [ link ] cta type or text for [ infopopup ] cta type.
Example: -help_button_cta_payload "URL"
-warning_button_cta_type
Value:
- link: trigger the url defined in the payload;
- infopopup: shows an info pop-up with the text defined in the payload;
The call to action type for the warning button.
Example: -warning_button_cta_type link
-warning_button_cta_payload
Value: "text"
An URL for [ link ] cta type or text for [ infopopup ] cta type.
Example: -warning_button_cta_payload "https://www.ibm.com"
-warning_button_visibility
Value:
- visible;
- hidden;
Since the warning button visibility is interactive this is the initial visibility state of the button.
If not set by default it's visible.
Example: -warning_button_visibility hidden
To change the warning button visibility while it is showed to the end user you just need to feed the IBM Notifier process with "/warning_button_visibility <STATE>".
Interactive Mode Example (while IBM Notifier is running): /warning_button_visibility hidden
Available states for interactive mode:
- visible
- hidden
- expand
-always_on_top
Value: nil
Flag that tells the UI to keep the pop-up always on top of the window hierarchy.
Example: -always_on_top
-silent (available from v2.0.1)
Value: nil
Flag that tells the UI to not produce any sound when appear.
Example: -silent
-timeout
Value: integer
The timeout for the notification. After this amount of seconds the app exit with the related exit code (4) if no [ timer ] accessory view was defined.
Example: -timeout 300
-miniaturizable (available from v2.3.0)
Value: nil
Flag that allows the UI to show the "miniaturize" button for the pop-up window.
Example: -miniaturizable
-force_light_mode (available from v2.5.0)
Value: nil
Flag that force the UI in light mode.
Example: -force_light_mode
-position (available from v2.2.0)
Value: "text"
Tells the app where to place the pop-up window.
Value:
- center
- top_left
- top_right
- bottom_left
- bottom_right
Example: -position center
-popup_reminder (available from v2.5.0)
Value: "text"
A text payload to define the behavior of an optional reminder for the pop-up. The reminder is basically a timer at the end of which the pop-up is pushed again on top of the view hierarchy on screen.
The payload format is: "/timeinterval <TIME_IN_SECONDS> /silent /repeat"
Example: -popup_reminder "/timeinterval 300"
-retain_values (available from v2.7.0)
Value: nil
Flag that tells the agent to print the available accessory view outputs on any exit (main or secondary button clicked).
Example: -retain_values
-custom_width (available from v3.1.0)
Value: integer
A custom width for the UI.
Example: -custom_width 300
-buttonless (available from v3.1.0)
Value: nil
Flag that tells the agent to not show any destructive CTA (Button).
Example: -buttonless
-hide_title_bar (available from v3.2.0)
Value: nil
Flag that tells the agent to not show the title bar.
Example: -hide_title_bar
-notification_image (available from v2.5.0)
Value: "text"
Custom notification alert/banner attachment (image). It supports remote link, local path and base64 encoded image.
Example: -notification_image "~/path/to/image.png"
-payload (available from v2.0.0)
Value: "text"
The payload of the onboarding workflow.
Please see more here: https://github.com/IBM/mac-ibm-notifications/wiki/Onboarding-UI-Workflow
-always_on_top (available from v2.6.0)
Value: nil
Flag that tells the agent to keep the Onboarding UI always on top of the window hierarchy.
Example: -always_on_top
-hide_title_bar_buttons (available from v2.7.0)
Value: nil
Flag that tells the agent to remove the title bar buttons for the Onbording UI.
Example: -hide_title_bar_buttons
-timeout (available from v3.0.0)
Value: integer
The timeout for the UI. After this amount of seconds the app exit with the related exit code (4).
Example: -timeout 300
-background_panel (available from v3.0.0)
Value: "text"
If defined will show a background view that will cover all the screens/spaces with the desired style.
Value:
- opaque
- translucent
Example: -background_panel translucent
-unmovable (available from v3.0.0)
Value: nil
Flag that if defined will make the UI unmovable for the user.
Example: -unmovable
-disable_quit (available from v3.1.0)
Value: nil
If this flag is set, it instructs the agent to disable the CMD+Q effect for the Pop-up/Onboarding UIs.
Example: -disable_quit
-silent
Value: nil
Flag that tells the UI to not produce any sound when appear.
Example: -silent
-show_suppression_button
Value: nil
Flag that tells the UI to show the default suppress notification button on the bottom of the UI.
If checked by the user the process will print `suppress` in the output pipe and then exit.
Example: -show_suppression_button
- 0 - Main button clicked.
- 1 - Internal error.
- 2 - Secondary button clicked.
- 3 - Tertiary button clicked.
- 4 - Timeout. (available from v2.0.0)
- 200 - Untracked success.
- 201 - Received SigInt.
- 239 - User dismissed the notification banner/alert/popup/onboarding window (also using cmd+q).
- 250 - Invalid number of arguments.
- 255 - Invalid arguments syntax.
- 260 - Unable to load resources
- At least one argument between [ -title | -subtitle | -accessory_view_type + -accessory_view_payload ] must be defined to present a [ popup ] UI.
- [ -payload ] must be defined and is the only argument needed to present an onboarding UI.
- At least one argument between [ -title | -subtitle ] must be defined to present a banner UI.
- By default tertiary button on [ popup | systemalert ] UI types is not destructive so the user must define a call to action type and payload for it. Use [ exitlink ] cta type to trigger a link (in the cta payload) and make it destructive for the [ popup | systemalert ] UIs. Use [ exitlink ] and no cta payload to make the tertiary button destructive for the [ popup | systemalert ] UIs.
- In general if a call to action type is defined for a button, must be defined also the related payload. Except for the cta types [ none | exitlink ].
- If no call to action type defined for the main and secondary buttons the default one is [ none ], that simply return the exit code related to the clicked button.
- To setup multiple accessory views on the [ popup ] UI use "-accessory_view_type_N" and "-accessory_view_payload_N" where N is an integer number that goes from 1 to 100. Use only sequential integers (CORRECT: 1, 2 ,3, 4, ... | WRONG: 1, 3, 5, 6, ...).
- IBM Notifier (Mac@IBM Notifications) provides also a configuration mode that let's the admin define some useful default values, please read more about here.
- You can find some useful special arguments here.
- The Alert UI needs additional configuration profile configuration to work properly. Please read more here.