Skip to content

Deep link usage

Jump to bottom
Simone Martorelli edited this page Jan 26, 2026 · 12 revisions

IBM Notifier (Mac@IBM Notifications) provide also a light and state less method to trigger Banner, Pop-up and Onboarding UIs: Deep links.

The default url schema associated with the app is ibmnotifier and the path to trigger UIs is shownotification.

This deep link accept all the available arguments used in the invocation through command line (except for the special arguments) but remember to remove the - from the front. (ex. -title -> title)

How to handle deep link security?

Deep links are secured via JSON Web Tokens (JWT). This token must be added to the deep link in order to let the agent to validate it and then parse the link arguments.

This JWT token are signed with a private key guarded by the admin. In order for the agent to evaluate the token signature, it needs to use the related shared public key.

Every token can specify a different expiration date and set different other claims. To learn more about the technology of JWT and its use, please refer to the jwt.io site.

How to enable deep link security and share the public key with the agent?

To enable deep link security the admin should deploy and ad-hoc configuration profile on the user device.
This profile will define the following ManagedPreferences for IBM Notifier (com.ibm.cio.notifier):

  • deeplinkSecurity = YES
  • deeplinkSecurityKey = YOUR_JWT_PUBLIC_KEY

The resultant config profile should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>PayloadContent</key>
	<array>
		<dict>
			<key>PayloadContent</key>
			<dict>
				<key>com.ibm.cio.be.mac-notification-agent</key>
				<dict>
					<key>Forced</key>
					<array>
						<dict>
							<key>mcx_preference_settings</key>
							<dict>
								<key>deeplinkSecurity</key>
								<true/>
								<key>deeplinkSecurityKey</key>
								<string>-----BEGIN PUBLIC KEY-----
HEREYOURPUBLICKEY
-----END PUBLIC KEY-----</string>
							</dict>
						</dict>
					</array>
				</dict>
			</dict>
			<key>PayloadDisplayName</key>
			<string>Custom Settings</string>
			<key>PayloadIdentifier</key>
			<string>37681FFA-B01E-4575-8B6F-4AAFE406BC21</string>
			<key>PayloadOrganization</key>
			<string>JAMF Software</string>
			<key>PayloadType</key>
			<string>com.apple.ManagedClient.preferences</string>
			<key>PayloadUUID</key>
			<string>37681FFA-B01E-4575-8B6F-4AAFE406BC21</string>
			<key>PayloadVersion</key>
			<integer>1</integer>
		</dict>
	</array>
	<key>PayloadDescription</key>
	<string></string>
	<key>PayloadDisplayName</key>
	<string>IBM Notifier DeepLink Security</string>
	<key>PayloadIdentifier</key>
	<string>1BE1618D-5D7A-4F23-9693-B985DFF39FA9</string>
	<key>PayloadScope</key>
	<string>System</string>
	<key>PayloadType</key>
	<string>Configuration</string>
	<key>PayloadUUID</key>
	<string>1BE1618D-5D7A-4F23-9693-B985DFF39FA9</string>
	<key>PayloadVersion</key>
	<integer>1</integer>
</dict>
</plist>

You can find it also here.

Example

This is an example on how to trigger a simple Pop-up with a deep link:
open "ibmnotifier:shownotification?token=THISISATOKEN&type=popup&title=This%20is%20a%20title&subtitle=This%20is%20a%20subtitle"

Clone this wiki locally