# Smart Links Smart Links provide a URL-based mechanism to trigger actions within the application from external sources. **Online tester:** [https://link-test.acrobits.cz/tools/smartLinks](https://link-test.acrobits.cz/tools/smartLinks) ## Format The Smart Link format extends the AppPath format with additional capabilities from CSCommand. Smart Links can be embedded in CSCommand the same way as AppPath. | Component | Requirement | |---------------|----------------------------------------------| | **scheme** | Must be `app` | | **authority** | Must be empty | | **path** | Must be empty | | **query** | Must contain at least the `action` parameter | | **fragment** | Must not be present | ### Example ```text app:?action=navigate&tab=browser&relative=/ble/chicken&reload=true ``` --- ## Actions All actions are defined in a shared format. Platforms may choose which actions to support. !!! note It is not guaranteed that a given platform will support all actions. For example, the mobile platforms cannot support the [External Navigation](#external-navigation) type of the Navigate action. Every action can include additional arguments specific to that action. All arguments are represented as additional query parameters. ### Navigate Navigates to a specific tab within the app or to an external location. This can be either [Tab Navigation](#tab-navigation), [Settings Navigation](#settings-navigation), or [External Navigation](#external-navigation), depending on the provided arguments. **Action:** `navigate` #### Tab Navigation Navigates to a tab within the app. | Name | Type | Required | Description | |-------|--------|----------|-------------------------| | `tab` | String | Yes | The tab to navigate to. | The Navigate Action also supports passing additional arguments to the tab it is navigating to. ##### Browser tab | Name | Type | Default | Description | |------------|---------|---------|----------------------------------------------------------------------------------------------------| | `relative` | String | `null` | Relative URL merged using AppPath merging rules. | | `reload` | Boolean | `false` | If `true`, the tab is always reloaded. If `false`, only reloaded when the URL changes. | | `reset` | Boolean | `false` | If `true`, the browser URL is reset to the default from PrefKeys. The `relative` field is ignored. | ##### Example ```text app:?action=navigate&tab=browser ``` #### Settings Navigation Navigates to a specific settings screen. | Name | Type | Required | Description | |------------|--------|----------|-------------------------------------| | `settings` | String | Yes | The settings screen to navigate to. | ##### Example ```text app:?action=navigate&settings=preferences ``` #### External Navigation Navigates to an external location. | Name | Type | Required | Description | |------------|--------|----------|-----------------------------------------| | `external` | `enum` | Yes | The location that will be navigated to. | Possible `external` values: - `recordings` - The folder where recordings are stored (if applicable) - `logs` - The folder where logs are stored (if applicable) ##### Example ```text app:?action=navigate&external=logs ``` ### Function Invokes an exported [function](../functions/function-reference.md) by ID. Functions cannot be triggered via Smart Links unless they are marked as `exported` in their definition. **Action:** `function` | Name | Type | Required | Description | |---------|--------|----------|--------------------------------------------------------------------------------------------------------------------------| | `id` | String | Yes | ID of the function to invoke. | | `param` | Map | No | Key-value pairs passed as the `param` scope for [placeholder](../functions/scopes.md#supported-placeholders) resolution. | #### Example ```text app:?action=function&id=sendLinkupMessage¶m[from]=Me¶m[message]=Hello ``` ### Provision Triggers provisioning with a new account. The current user will be signed out and the new account will be added. This is Smart Link-native version of the [CSC Links](../provisioning/cloud-account-management/csc-links.md). !!! note The `provision` action can also be used to trigger resets and logouts without signing into new account. **Action:** `provision` | Name | Type | Required | Description | |------------|--------|----------|------------------------------------------------------------------------------------------------------------| | `username` | String | No | Username for the new account. | | `password` | String | No | Password for the new account. | | `cid` | String | No | CID for the new account. | | `mode` | Enum | No | Reset mode, can be either `reset` or `logout`. If not provided the default from provisioning will be used. | Additional parameters are passed as extras, same as in CSC Links. #### Example ```text title="Provision with new account" app:?action=provision&username=hello&password=there&cid=TEST ``` ```text title="Logout current user without a new account" app:?action=provision&mode=logout ``` ```text title="Reset the app" app:?action=provision&mode=reset ``` ```text title="Logout current user and provision a new account" app:?action=provision&username=hello&password=there&cid=TEST&mode=logout ``` ```text title="Either reset or logout" app:?action=provision ``` ```text title="Pass extras" app:?action=provision&username=hello&password=there&cid=TEST&foo=bar ``` ### Reprovsion Triggers reprovisioning. Replaces the legacy `provisioning-update` and `extprov-update` commands. **Action:** `reprovision` | Name | Type | Default | Description | |--------------|----------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------| | `only` | String[] | `null` | Which items to update: `provisioning`, `theme`, `extprov`, `global_extprov`. If `null`, everything is updated. | | `resetCache` | Boolean | `null` | If `true`, provisioning endpoints and other cached values are reset. | | `accounts` | String[] | `null` | Account IDs to update External Provisioning for. If `null`, all accounts are updated. Only applies when `only` is `null` or includes `extprov`. | #### Example ```text app:?action=reprovision&only=provisioning,extprov&resetCache=true&accounts=hello,there ``` ### Balance update Trigger balance update, new version of legacy `balance-update` **Action:** `balance-update` | Name | Type | Default | Description | |------------|----------|---------|-------------------------------------------------------------| | `accounts` | String[] | `null` | Account IDs to update. If `null`, all accounts are updated. | #### Example ```text app:?action=balance-update&accounts=hello,there ``` ### Quit Triggers the app to quit. **Action:** `quit` | Name | Type | Default | Description | |--------|------|---------|----------------------------------------------| | `mode` | Enum | `soft` | Can be either `soft`, `force`, or `restart`. | The `mode` parameter determines how the app will quit: - `soft` (default) - The app will attempt to quit gracefully. This may mean only minimizing to the task tray. - `force` - The app will quit immediately without any cleanup. This may cause data loss. Mobile platforms may stop receiving push notifications until the app is opened again. - `restart` - The app will quit and immediately restart. #### Example ```text title="Restart the app" app:?action=quit&mode=restart ``` --- ## List Format To embed lists in URL query parameters, use the following syntax: ```text list=value1,value2,value3 ``` ## Map Format To embed key-value maps in URL query parameters, use the following syntax: ```text map[key]=value ``` Where `map` is the parameter name, `key` is the map key, and `value` is the assigned value.