# App

App-level capabilities: lifecycle (quit, launch-at-startup), OS permissions, deeplinks, and auto-updates.

{% hint style="info" %}
The methods on this page span several namespaces (`app`, `permissions`, `autoUpdate`, `deeplink`). They're grouped here because they concern the app as a whole rather than any one window.
{% endhint %}

## Methods

### <mark style="color:purple;">Exit App</mark>

Force closes all windows and quits the app.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.app.exit()
```

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Launch At Startup</mark>

Sets whether the app should automatically launch when the user logs in.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.app.setLaunchAtStartup({ arguments })
```

**Arguments**

* `launchAtStartup` <mark style="color:green;">Boolean</mark> (Required)

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.

**Example**

{% code overflow="wrap" %}

```javascript
const result = await window.deskifier.app.setLaunchAtStartup({
    launchAtStartup: true
});

console.log(result.success);  // true
```

{% endcode %}
{% endtab %}
{% endtabs %}

***

### <mark style="color:purple;">Request Permission</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> Request use of a certain media type.

{% hint style="warning" %}
Usually, permissions can only be asked once. It's recommended to prompt users with your own UI letting them know to accept the request.\
\
This feature is only available on macOS. Generally, other platforms will have permissions by default.\
\
If needed, you can deep link users to their relevant settings / system preferences.
{% endhint %}

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.permissions.request({ arguments })
```

**Arguments**

* `permission` <mark style="color:green;">String</mark> (Required)\
  Possible values are `microphone`, `camera`, `screenSharing`, and `accessiblity`. The accessibility value will open the system preferences linked to the accessibility settings, since there's currently no way to request accessibility permissions.

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If access was granted successfully.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Open System Preferences</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> <mark style="color:purple;background-color:purple;">**Windows**</mark> Opens the device's settings panel, at the specified submenu.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.permissions.openSystemPreferences({ arguments })
```

**Arguments**

* `target` <mark style="color:green;">String</mark> (Required)\
  Possible values are `camera`, `microphone`, `screenSharing`, `notification` and the `accessibility` value is available on macOS only.

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Check For Update</mark>

Checks to see if there's an app update available.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.autoUpdate.check()
```

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the update was checked.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
* `updateAvailable` <mark style="color:green;">Boolean</mark>\
  If there is an update available.
* `nextVersion` <mark style="color:green;">String</mark>\
  Available update version.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Start App Update</mark>

{% hint style="danger" %}
This will force close the app.
{% endhint %}

Starts the app update.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.autoUpdate.startUpdate()
```

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  Returns false if the update couldn't be started, or if there is no update available.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
  {% endtab %}
  {% endtabs %}

***

## Properties

### <mark style="color:purple;">Get Permissions</mark>

<mark style="color:purple;background-color:purple;">**macOS**</mark> <mark style="color:purple;background-color:purple;">**Windows**</mark> Returns an object with the current permissions.

{% hint style="info" %}
Generally, macOS will be the only platform that doesn't have permissions by default. In this case, use the "Request Media Permission" method to gain access to these devices.\
\
You can also deep link users to their relevant settings / system preferences with the "Open System Preferences" method.
{% endhint %}

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.permissions.getAll()
```

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
* `cameraPermissionStatus` <mark style="color:green;">String</mark>\
  Can be `not-determined`, `granted`, `denied`, `restricted` or `unknown`.
* `microphonePermissionStatus` <mark style="color:green;">String</mark>\
  Can be `not-determined`, `granted`, `denied`, `restricted` or `unknown`.
* `screenPermissionStatus` <mark style="color:green;">String</mark>\
  Can be `not-determined`, `granted`, `denied`, `restricted` or `unknown`.
* `accessibilityPermissionStatus` <mark style="color:green;">String</mark> ***macOS***\
  Can be `not-determined`, `granted`, `denied`, `restricted` or `unknown`. Will return `unknown` on platforms other than macOS.
* `notificationPermissionStatus` <mark style="color:green;">String</mark>\
  Can be `not-determined`, `granted`, `denied`, `restricted` or `unknown`.<br>

Return Value Descriptions:

* `not-determined` - The user has not yet made a choice regarding whether the application may access the data.
* `restricted` - The application is not authorized to access the data. The user cannot change this application’s status, possibly due to active restrictions such as parental controls being in place.
* `denied` - The user explicitly denied access to data for the application.
* `authorized` - The application is authorized to access the data.
* `provisional` - The application is provisionally authorized to access the data. Currently only applicable to the `notifications` type.
* `unknown` - The permission status can not be determined.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Get App Info</mark>

Returns metadata about the running app. This call is **Synchronous** it returns a value directly (no `await`).

{% tabs %}
{% tab title="JavaScript" %}

```javascript
const info = window.deskifier.app.getAppInfo()
```

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
* `launchAtStartup` <mark style="color:green;">Boolean</mark>\
  If the app is currently set to launch at system startup.
* `launchedWithDeeplink` <mark style="color:green;">Boolean</mark>\
  Whether the current instance of the app was launched via a deeplink.
* `deeplinkUrl` <mark style="color:green;">String</mark>\
  If the app was launched with a deeplink, this will be populated with the URL used. Empty string otherwise.
* `appName` <mark style="color:green;">String</mark>\
  Name of the current app.
* `appVersion` <mark style="color:green;">String</mark>\
  The app version.
* `appDist` <mark style="color:green;">String</mark>\
  Which distribution the app is currently running as. Can be `MAS`, `DMG`, `APPX`, `NSIS`, `APPIMAGE`.
* `willAutoUpdate` <mark style="color:green;">Boolean</mark>\
  If the app is set to automatically update when a new version is published.
  {% endtab %}
  {% endtabs %}

***

## Events

### <mark style="color:purple;">Deeplink Used</mark>

{% hint style="info" %}
Note, a deeplink can be used to launch your application. If this happens, this event will fire when the app starts. You can also check via [<mark style="color:blue;">Get App Info</mark>](#get-app-info).\
\
Deeplinks may also be used when the app is already running, in this case you should show your application.
{% endhint %}

Fires when the app's deeplink is used.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.deeplink.onUsed((data) => {})
```

**Arguments**

* `url` <mark style="color:green;">String</mark>

**Example**

```javascript
window.deskifier.deeplink.onUsed((data) => {
   console.log(data.url);
});

//yourAppProtocol://data?foo=bar
```

{% endtab %}
{% endtabs %}

***

### <mark style="color:purple;">Update Available</mark>

Fires when a new app version is detected. This also fires after a background download completes (check `downloaded` to distinguish).

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.autoUpdate.onAvailable((data) => {})
```

**Arguments**

* `updateAvailable` <mark style="color:green;">Boolean</mark>\
  `true` if an update is available.
* `nextVersion` <mark style="color:green;">String</mark>\
  The version string of the available update (if known).
* `downloaded` <mark style="color:green;">Boolean</mark>\
  `true` if the update has finished downloading and is ready to install. When `false`, the update is still downloading or not yet started.

**Example**

```javascript
window.deskifier.autoUpdate.onAvailable((data) => {
    if (data.downloaded) {
        // Prompt the user to restart-to-install
        showBanner(`${data.nextVersion} is ready. Click to install.`);
    } else {
        console.log(`Found update ${data.nextVersion}, downloading...`);
    }
});
```

{% endtab %}
{% endtabs %}

***

### <mark style="color:purple;">Update Progress</mark>

Fires repeatedly during an update download, with progress information.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.autoUpdate.onProgress((data) => {})
```

**Arguments**

* `percent` <mark style="color:green;">Number</mark>\
  Download progress percentage (0–100).
* `transferred` <mark style="color:green;">Number</mark>\
  Bytes downloaded so far.
* `total` <mark style="color:green;">Number</mark>\
  Total bytes to download.
* `bytesPerSecond` <mark style="color:green;">Number</mark>\
  Current download speed.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Update Error</mark>

Fires when an update check or download fails.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
window.deskifier.autoUpdate.onError((data) => {})
```

**Arguments**

* `message` <mark style="color:green;">String</mark>\
  Human-readable error description.
  {% endtab %}
  {% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://deskifier.gitbook.io/deskifier/app.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.