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 | 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.
Remote URL and Base64 images support has been implemented in v2.7.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;
- securedinput: secured 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;
The UI type for the needed accessory view.
Example: -accessory_view_type text
-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.
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".
-secondary_accessory_view_type (available from v2.3.0)
Same as for the -accessory_view_type argument.
-secondary_accessory_view_payload (available from v2.3.0)
Value: "text"
Same as for the -accessory_view_payload argument.
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
-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
- 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/onboarding window.
- 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 ] UI type is not destructive. Use [ exitlink ] cta type to trigger a link (optional) and make it destructive for the pop-up.
- 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 a button the default one is [ none ], that simply return the exit code related to the clicked button.
- 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.