Skip to content

Onboarding UI Workflow

Jump to bottom
Simone Martorelli edited this page Jul 13, 2023 · 12 revisions

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]] 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

Key Mandatory Type Note
type YES String Accessory View's type.
payload YES String Accessory View's payload.

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\"}]}"

Clone this wiki locally