Skip to content

Configuration

Jump to bottom
Jordy Witteman edited this page Oct 29, 2025 · 6 revisions

Introduction

The configuration of Support App is optimized for use with your Device Management Service. The easiest way to configure the app is using a Configuration Profile so you can use whatever Device Management Service you like, as long as it supports custom Configuration Profiles or other integration/feature to configure 3rd party applications.

Configurator Mode

The easiest way to configure Support App is using its built-in Configurator Mode which allows you to visualize the app, quickly try different layouts, iterate on previous configurations and export the result to a property list of .mobileconfig file to directly upload into your Device Management Service. Please check the Configurator Mode page for more information.

Preference domain

Support App uses the following preference domain for configuration: nl.root3.support

File locations

Some preference keys like the icon and status bar icon can point to a file location. Because Support App is sandboxed, not all file locations are allowed. We suggest putting the files in a folder within Application Support such as /Library/Application Support/Your Company/ where the app can read the contents. Other supported file locations can be found in Apple’s documentation about App Sandbox: https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW17

Dependencies

Managed Login Item

A sample Configuration Profile is provided (both signed and unsigned) for macOS 13 and higher to avoid users from disabling the LaunchAgent in System Settings > General > Login Items. The profile uses the Root3 Team ID to only allow signed software from Root3. Samples

PPPC

You need to configure PPPC in the following scenarios:

  • If you are an App Catalog customer and using the App Catalog integration. Support App requires additional permissions to be able to perform app updates.
  • If you use Privileged Scripts and trying to read from or write to protected locations.

To explicitely grant the SystemPolicyAllFiles (Full Disk Access) permission in a Privacy Preference Policy Control profile (PPPC), here are the details:

  • Allowed: true

  • Identifier: nl.root3.support

  • IdentifierType: Bundle ID

  • CodeRequirement: anchor apple generic and identifier "nl.root3.support" and (certificate leaf[field.1.2.840.113635.100.6.1.9] /* exists */ or certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "98LJ4XBGYK")

  • Allowed: true

  • Identifier: /Library/PrivilegedHelperTools/nl.root3.support.helper

  • IdentifierType: Path

  • CodeRequirement: anchor apple generic and identifier "nl.root3.support.helper" and (certificate leaf[field.1.2.840.113635.100.6.1.9] /* exists */ or certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "98LJ4XBGYK")

A sample Configuration Profile is provided here

Preference keys

Below are all available preference keys, categorized in the same way these appear in the Configurator Mode settings.

General

Preference key Type Default value Description Example
Title String Support Text shown in the top left corner when the app opens. “Your Company Name“, “IT Helpdesk“, "Hi $LocalFullName!" etc.
FooterText String - Text shown at the bottom as footnote "Provided by your IT department with ❤️"
ErrorMessage String Please contact IT support Shown when clicking an action results in an error "Please contact the servicedesk", "Please contact COMPANY_NAME"
ShowWelcomeScreen Boolean false Shows the welcome screen when Support App is opened for the first time. true
StatusBarIconNotifierEnabled Boolean false Shows a small notification badge in the Status Bar Icon when an info items triggers a warning or notification true

Branding

Preference key Type Default value Description Example
Logo String App Icon Remote URL, SF Symbol or path to the logo shown in the top right corner when the app opens. Scales to 48 points maximum height. A subfolder in /Library/Application Support/ is the recommended location due to sandboxing /Library/Application Support/Your Company/logo.png or https://domain.tld/url_to_image.png
LogoDarkMode String App Icon Remote URL, SF Symbol or path to the logo shown in the top right corner when the app opens for Dark Mode. Scales to 48 points maximum height. A subfolder in /Library/Application Support/ is the recommended location due to sandboxing /Library/Application Support/Your Company/logo_darkmode.png or https://domain.tld/url_to_image.png
NotificationIcon String App Icon Remote URL or path to a custom square image to be shown in alerts and the about window. /Library/Application Support/Your Company/logo.png or https://domain.tld/url_to_image.png
StatusBarIcon String - Remote URL or path to the status bar icon shown in the menu bar. Recommended: PNG, 16x16 points. Icons larger than 22 points will automatically be resized to 16 points. A subfolder in /Library/Application Support/ is the recommended location due to sandboxing /Library/Application Support/Your Company/statusbaricon.png or https://domain.tld/url_to_image.png
StatusBarIconAllowsColor Boolean false Allow status bar icon to show color when a custom image is used (SF Symbol excluded) true
StatusBarIconSFSymbol String "lifepreserver" Custom status bar icon using an SF Symbol. Ignored when StatusBarIcon is also set “lifepreserver”
CustomColor String macOS Accent Color Custom color for all symbols. Leave empty to use macOS Accent Color. We recommend not to use a very light color as text may become hard to read HEX color in RGB format like "#8cc63f"
CustomColorDarkMode String macOS Accent Color Custom color for all symbols in Dark Mode. Leave empty to use macOS Accent Color or CustomColor if specified. We recommend not to use a very dark color as text may become hard to read HEX color in RGB format like "#8cc63f"

Info items

Preference key Type Default value Description Example
UptimeDaysLimit Integer 0 (Disabled) Days of uptime after which a notification badge is shown, disabled by default. Only applicable when the Uptime Info Item is enabled 7
PasswordType String Apple The account type to use with the Password info item: local user account (Apple), Jamf Connect, Kerberos SSO Extension or NoMAD. Only applicable when the Password Info Item is enabled "Apple", "JamfConnect", "KerberosSSO" or "Nomad"
PasswordExpiryLimit Integer 0 (Disabled) Days until password expiry after which a notification badge is shown, disabled by default. Only applicable when the Password Info Item is enabled 14
PasswordLabel String Mac Password Alternative text label shown in the Password info item. Only applicable when the Password Info Item is enabled "AD Password", "Company Password"
StorageLimit Integer 0 (Disabled) Percentage of storage used after which a notification badge is shown, disabled by default. Only applicable when the Storage Info Item is enabled 80
UpdateText String - The text shown below the software update details popover "Your organization requires you to update as soon as possible. More info..."

Advanced

Preference key Type Default value Description Example
OpenAtLogin Boolean false Launch Support (non-PKG version) automatically at login and keep it open. This setting is ignored if a legacy LaunchAgent is installed/active. Keep disabled if you don't want to open Support at login or use your own LaunchAgent false
DisablePrivilegedHelperTool Boolean false Disable the Privileged Helper Tool for the PKG installer during the time of installation or at launch of Support App true
DisableConfiguratorMode Boolean false Prevents users from enabling Configurator Mode true
OnAppearAction String - Path to privileged script to be executed when Support App is shown by clicking on the menu bar item. The Privileged Helper Tool is required for this feature. /usr/local/bin/runs_when_support_appears.zsh

Rows

Key Type Description Example
Rows Array Top-level array containing one or more Row dictionaries. Each Row represents a horizontal section of the interface. –
Row Dictionary Container that defines one group or section of items. Each Row can contain one or more Items. –
Items Array Array of items within a Row. Each Item defines an element shown in the app such as a button, info tile, or extension-based component. –
Item Dictionary An item inside a Row. Must include Type; may include Title, Subtitle, Symbol, Action, ActionType, ExtensionID, OnAppearAction. See “Item dictionary” below. –

Item dictionary

Each Item represents one tile or button in the Support App interface.
The Type key defines what kind of element it is (for example, “Button”, “InfoItem”, “Extension”, etc.).
Other keys control its appearance, behavior, and optional extensions.

Key Type Required Description Example
Type String ✅ Defines the type of item. Available built-in types include: ComputerName, MacOSVersion, Network, Password, Storage, Uptime, AppCatalog, Extension, Button, ButtonMedium, ButtonSmall etc. "Button"
Title String – Text displayed as the main title of the item. “Share My Screen”, “Remote Support“, “Software Updates“ “My core application”, "Company Portal", etc.
Subtitle String – Subtitle text will appear under title when the user hovers over the button. Ignored if left empty. “Click to open“, “Share your screen“
Symbol String – The SF Symbol shown in the button. binoculars.fill, cursorarrow.click.2 or any other SF Symbol. Please check the SF Symbols app
Action String – The Bundle Identifier of the App, URL, command to run or privileged script to run. nl.root3.catalog, "/usr/local/bin/yourscript.zsh", "https://intranet.company.tld", "mailto:support@company.tld"
ActionType String – Type of link the item should open. Can be anything like screen sharing tools, company stores, file servers or core applications in your organization. App, URL, Command or PrivilegedScript
ExtensionID String – Identifier for the Support App Extension. This value can be used in a script used in OnAppearAction to populate and update the Extension "tld.yourorganization.extension.description"
OnAppearAction String – Command or script executed when the item becomes visible in the interface. Useful for dynamic info items. "/usr/local/bin/update_status.zsh"

Visual hierarchy

Below is a visualization of the hierarchy of Rows:

Root (Configuration)
└── Rows (Array)
    ├── Row (Dictionary)
    │   └── Items (Array)
    │       ├── Item (Dictionary)
    │       │   ├── Type (Required)
    │       │   ├── Title
    │       │   ├── Subtitle
    │       │   ├── Symbol
    │       │   ├── Action
    │       │   ├── ActionType
    │       │   ├── ExtensionID
    │       │   └── OnAppearAction
    │       ├── Item (Dictionary)
    │       │   ├── Type (Required)
    │       │   ├── Title
    │       │   ├── Subtitle
    │       │   ├── Symbol
    │       │   ├── Action
    │       │   ├── ActionType
    │       │   ├── ExtensionID
    │       │   └── OnAppearAction
    │       └── …
    │
    ├── Row (Dictionary)
    │   └── Items (Array)
    │       └── Item (Dictionary)
    │           ├── Type (Required)
    │           ├── Title
    │           ├── Subtitle
    │           ├── Symbol
    │           ├── Action
    │           ├── ActionType
    │           ├── ExtensionID
    │           └── OnAppearAction
    │
    └── …

Example

Below is an example of how the Rows key can be configured:

<key>Rows</key>
<array>
  <dict>
    <key>Items</key>
    <array>
      <dict>
        <key>Type</key>
        <string>ComputerName</string>
      </dict>
      <dict>
        <key>Type</key>
        <string>MacOSVersion</string>
      </dict>
    </array>
  </dict>
  <dict>
    <key>Items</key>
    <array>
      <dict>
        <key>Type</key>
        <string>Uptime</string>
      </dict>
      <dict>
        <key>Type</key>
        <string>Storage</string>
      </dict>
    </array>
  </dict>
  <dict>
    <key>Items</key>
    <array>
      <dict>
        <key>Action</key>
        <string>com.teamviewer.TeamViewerQS</string>
        <key>ActionType</key>
        <string>App</string>
        <key>Subtitle</key>
        <string>Share Screen</string>
        <key>Symbol</key>
        <string>macwindow.and.pointer.arrow</string>
        <key>Title</key>
        <string>Remote Support</string>
        <key>Type</key>
        <string>ButtonMedium</string>
      </dict>
      <dict>
        <key>Action</key>
        <string>/usr/local/bin/myscript.zsh</string>
        <key>ActionType</key>
        <string>PrivilegedScript</string>
        <key>Subtitle</key>
        <string></string>
        <key>Symbol</key>
        <string>person.2.badge.gearshape</string>
        <key>Title</key>
        <string>My Tool</string>
        <key>Type</key>
        <string>ButtonMedium</string>
      </dict>
      <dict>
        <key>Action</key>
        <string>https://myapps.microsoft.com</string>
        <key>ActionType</key>
        <string>URL</string>
        <key>Subtitle</key>
        <string>Open</string>
        <key>Symbol</key>
        <string>square.grid.3x2</string>
        <key>Title</key>
        <string>My Apps</string>
        <key>Type</key>
        <string>ButtonMedium</string>
      </dict>
    </array>
  </dict>
</array>

Clone this wiki locally