Since version 2.6.0 Mac@IBM Notifications will use a new Onboarding UI.
This new UI consist in a fully customisable paged onboarding experience like the old one but with some additional features:
- Embedding of a matrix of Accessory Views in each page;
- Common Progress Bar.
The admin will define pages with a structured model based on JSON format. This JSON will be passed to IBM Notifier through the -payload CLI argument as seen in the Usage wiki page.
The app will write the result of the selections/inputs made by the user on the visible accessory views on a property list file called IBM_Notifier_Onboarding.plist placed in ~/.ibmnotifier/ hidden folder.
Model
Onboarding Payload
| Key |
Mandatory |
Type |
Note |
| progressBarPayload |
NO |
String |
The initial payload for the common Onboarding Progress Bar. See Progress Bar Accessory View payload for more info. |
| pages |
YES |
[OnboardingPage] |
This array contains all the pages that will be showed in the onboarding workflow |
OnboardingPage
| Key |
Mandatory |
Type |
Note |
| title |
NO* |
String |
The title of the page |
| subtitle |
NO* |
String |
The subtitle of the page. Supports Markdown format on macOS 12+. |
| body |
NO* |
String |
The body of the page. Supports Markdown format on macOS 12+. |
| accessoryViews |
NO |
[Accessory View](/IBM/mac-ibm-notifications/wiki/Accessory-View) |
A matrix of accessory view elements. |
| infoSection |
NO |
InfoSection |
The info section that will be showed with a click on the info button. |
| topIcon (from v.2.4.0) |
NO |
String |
The local/remote url to a custom icon that will appear above page's title. |
| singleChange |
NO |
BOOL |
Set this parameter to true if you want the user to not be able to come back to this page once he/she/they clicked on the "Continue" button. |
| tertiaryButton |
NO |
NotificationButton |
A tertiary button that will appear on the bottom left of the page. On the side of the info section if defined. |
| primaryButtonLabel |
NO |
String |
Custom label for the primary button (Continue). |
| secondaryButtonLabel |
NO |
String |
Custom label for the secondary button (Back). |
Accessory View
When using a Matrix of Accessory Views please be aware of:
- Accessory View will be rendered in rows;
- IBM Notifier doesn't currently check if all the Accessory Views included in the matrix will have enought space to be rendered;
- Image and Video Accessory Views must be placed in the last available row of the matrix.
InfoSection
| Key |
Mandatory |
Type |
Note |
| fields |
YES |
[InfoField] |
This array contains all the info field that will be showed in the info section. |
InfoField
| Key |
Mandatory |
Type |
Note |
| label |
YES |
String |
The label (or first item) of the info field. |
| description |
NO |
String |
The description (or second item) of the info field. |
NotificationButton
| Key |
Mandatory |
Type |
Note |
| label |
YES |
String |
The label (or first item) of the button. |
| callToActionType |
YES |
String |
The value could be link or exitlink. The exitlink type will cause the Onboarding UI exit when the button is clicked. |
| callToActionPayload |
YES |
String |
The URL to be opened. |
Example of JSON
{
"progressBarPayload":"/percent 0 /top_message Top Message /bottom_message Bottom Message",
"pages":[
{
"title":"First page's title",
"subtitle":"First page's subtitle",
"body":"First page's body",
"topIcon":"http://image.address/"
},
{
"title":"Second page's title",
"subtitle":"Second page's subtitle",
"body":"Second page's body",
"singleChange":true,
"accessoryViews":[
[
{
"type":"input",
"payload":"/placeholder Something /title First"
},
{
"type":"input",
"payload":"/placeholder Something /title Second"
}
]
]
},
{
"title":"Third page's title",
"subtitle":"Third page's subtitle",
"body":"Third page's body",
"accessoryViews":[
[
{
"type":"dropdown",
"payload":"/list One\nTwo\nThree /title First"
},
{
"type":"dropdown",
"payload":"/list One\nTwo\nThree /title Second"
}
]
],
"infoSection":{
"fields":[
{
"label":"First label only"
},
{
"label":"Second label only"
},
{
"label":"Third label only"
}
]
}
},
{
"title":"Fourth page's title",
"subtitle":"Fourth page's subtitle",
"body":"Fourth page's body",
"infoSection":{
"fields":[
{
"label":"First label",
"description":"First description"
},
{
"label":"Second label",
"description":"Second description"
},
{
"label":"Third label",
"description":"Third label"
}
]
}
}
]
}
Example of command line invocation
~/Applications/IBM\ Notifier.app/Contents/MacOS/IBM\ Notifier -type onboarding -payload "{\"pages\":[{\"title\":\"First page's title\",\"subtitle\":\"First page's subtitle\",\"body\":\"First page's body\"}]}"