> ## Documentation Index > Fetch the complete documentation index at: https://docs.velatir.com/llms.txt > Use this file to discover all available pages before exploring further. # Browser Extension - Safari (macOS) > Deploy the Velatir Safari extension: Velatir for Desktop installs it and sets the ingest key, your MDM keeps it switched on Safari has no force-install policy, so the Safari extension ships inside a small Mac app, **Velatir Safari Extension**. [Velatir for Desktop](https://docs.velatir.com/desktop-app/overview.md) installs that app, keeps it current, and sets the ingest key. Your MDM does one thing: it turns the extension on and keeps it on, with the Safari extensions setting that Jamf Pro calls the **Manage Safari extensions** Blueprint. | Part | With Velatir for Desktop | Without Velatir for Desktop | | - | - | - | | Install the app and keep it updated | The desktop agent | Your MDM pushes the [package](#with-your-own-mdm) | | Set the ingest key | The desktop agent | Your MDM pushes a [configuration profile](#with-your-own-mdm) | | Turn the extension on and keep it on | Your MDM, with the [Blueprint](#2-keep-the-extension-on) | Your MDM, with the [Blueprint](#2-keep-the-extension-on) | Without the Blueprint, the extension stays off until a user turns it on in Safari. Safari is not covered until then. ## Requirements | Requirement | Detail | | - | - | | Operating system | macOS 15.4 or later (Apple Silicon, Intel) | | Velatir for Desktop | **0.26.0 or later**, for the automatic install | | Enrollment | **Supervised** Macs. macOS applies Safari extension settings only on supervised Macs. | | MDM | Jamf Pro with Blueprints, or any MDM that sends declarative device management (DDM) configurations | To check that a Mac is supervised, run this. It prints `DeviceIsSupervised = 1`: ```bash theme={null} /usr/libexec/mdmclient dumpManagementStatus | grep DeviceIsSupervised ``` ## 1. Install the extension ### With Velatir for Desktop Nothing to upload. While **Browser coverage** on the **Setup** page of the [Velatir dashboard](https://app.velatir.com) is **Velatir-managed**, the default, the agent on each Mac: * Downloads the current Safari release from Velatir and installs it. Before installing, it checks the package's SHA-256 and that the package is notarized and signed by Velatir ApS (Team ID `AA7QLU3S4R`). * Writes the ingest key to the extension's managed preferences, so users are never asked for one. * Checks for a newer release a minute after it starts and every four hours after that. It installs a newer version over the old one and never downgrades. * Leaves an app it did not install alone. If your MDM already pushed the package, keep managing it there. | Browser coverage | Safari | | - | - | | **Velatir-managed** | Installs the app and the ingest key. Keeps the app updated. | | **Key-only** | Sets the ingest key. Never installs or removes the app. | | **Off** | Removes the app, if the agent installed it. | > [!NOTE] > > The agent installs the app. It cannot turn the extension on: only Safari, or your MDM, can do that. Continue with [step 2](#2-keep-the-extension-on). ### With your own MDM Use this route on Macs without Velatir for Desktop, or when Browser coverage is **Key-only**. | File | Link | | - | - | | Package | [velatir-safari.pkg](https://releases.velatir.com/velatir-safari/macos/latest/velatir-safari.pkg) | | Checksum | [velatir-safari.pkg.sha256](https://releases.velatir.com/velatir-safari/macos/latest/velatir-safari.pkg.sha256) | The package is signed by Velatir ApS (Team ID `AA7QLU3S4R`) and notarized by Apple. One package covers Apple Silicon and Intel, and it always installs into `/Applications`. **Deploy the package** 1. In Jamf Pro, upload the package under **Packages**. 2. Create a policy with the package. Trigger: **Recurring Check-in**. Frequency: **Once per computer**. Scope it to your Macs. Users do not need to open the app: Safari registers the extension as soon as the package is installed. To roll out a new version, replace the package in the policy, then open the policy's **Logs** and click **Flush All**. Macs that already ran the policy install the new version at their next check-in, over the old one. **Set the ingest key** Copy the profile below and replace `vltr_ingest_yourIngestKeyHere` with your ingest key, from the **Setup** page of the [Velatir dashboard](https://app.velatir.com). Save it as `velatir-safari.mobileconfig`. 1. Go to **Computers** > **Configuration Profiles** > **Upload**. 2. Upload `velatir-safari.mobileconfig` as it is. Do not edit it in Jamf. 3. Scope it to the same Macs as the package. The extension accepts the key only from managed preferences, so users cannot change or remove it. ```xml expandable velatir-safari.mobileconfig theme={null} PayloadContent PayloadType com.apple.ManagedClient.preferences PayloadIdentifier com.velatir.safari-extension.managed-config.preferences PayloadUUID 518798C2-3CFA-43B8-A10C-7A9B6559567C PayloadVersion 1 PayloadContent com.velatir.safari-extension.extension Forced mcx_preference_settings apiToken vltr_ingest_yourIngestKeyHere PayloadDisplayName Velatir Safari Extension PayloadIdentifier com.velatir.safari-extension.managed-config PayloadScope System PayloadType Configuration PayloadUUID 598E04F9-8DE2-4BFD-AAE5-2A845ECC7F9C PayloadVersion 1 ``` > [!WARNING] > > Do not paste this profile into **Application & Custom Settings**. That payload expects only the settings for one preference domain, and wraps whatever it is given in a second profile. The extension then cannot find `apiToken` and shows *Your organisation's configuration profile could not be read*. > > To use Application & Custom Settings instead, set **Preference Domain** to `com.velatir.safari-extension.extension` and upload a property list with only the key: > > ```xml theme={null} > > > > > apiToken > vltr_ingest_yourIngestKeyHere > > > ``` ## 2. Keep the extension on This step is the same on both routes. It is what makes Safari coverage hold: the extension is on, users cannot turn it off, and it has access to every website without a per-site prompt. 1. In Jamf Pro, go to **Blueprints**, create a macOS Blueprint, and add **Manage Safari extensions**. 2. Add one extension with this identifier, including the space and the parentheses: ``` com.velatir.safari-extension.extension (AA7QLU3S4R) ``` 3. Set **State** to **Always On**, **Private Browsing** to **Always On**, and **Allowed Domains** to `*`. 4. Scope the Blueprint to your Macs and click **Deploy**. A saved Blueprint does nothing until it is deployed. > [!WARNING] > > The identifier is the extension's bundle ID followed by Velatir's Team ID. The Team ID alone, or the app's bundle ID `com.velatir.safari-extension`, matches nothing. Safari then leaves the extension unmanaged and reports no error. On another MDM, send a `com.apple.configuration.safari.extensions.settings` configuration on the **user** channel with this payload: ```json theme={null} { "ManagedExtensions": { "com.velatir.safari-extension.extension (AA7QLU3S4R)": { "State": "AlwaysOn", "PrivateBrowsing": "AlwaysOn", "AllowedDomains": ["*"] } } } ``` The Blueprint can arrive before or after the app. Safari applies it as soon as both are on the Mac. > [!NOTE] > > **Macs that are not supervised** ignore this setting. There, each user turns the extension on once: open **Safari** > **Settings** > **Extensions**, tick **Velatir**, and choose **Always Allow on Every Website**. The user can turn it off again. ## Verify On a Mac in scope, once the app and the Blueprint have arrived: 1. Confirm the app is installed. This prints the version: ```bash theme={null} /usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "/Applications/Velatir Safari Extension.app/Contents/Info.plist" ``` With Velatir for Desktop, the agent log says what it did. It prints lines such as `safari-extension: installed 1.20.2`: ```bash theme={null} grep safari-extension /Library/Logs/Velatir/agent.stdout.log ``` 2. Confirm the ingest key arrived. The output shows `apiToken` at the top level: ```bash theme={null} plutil -p "/Library/Managed Preferences/com.velatir.safari-extension.extension.plist" ``` 3. Quit Safari (**⌘Q**) and open it again. In **Safari** > **Settings** > **Extensions**, Velatir is on and its checkbox is greyed out. 4. Click the Velatir button in the Safari toolbar. The dashboard opens without asking for a key. ## Troubleshoot * **The agent log says *not published for this environment yet***: Velatir has not released the Safari extension to your environment. Nothing is wrong on the Mac. The agent installs it on its first check after the release. * **The agent log says *installed but not by the agent***: your MDM, or someone with administrator rights, installed the app. The agent leaves it alone and does not update it. Keep managing it from your MDM, or delete `/Applications/Velatir Safari Extension.app` and the agent installs the current release within four hours. * **The extension shows *Your organisation's configuration profile could not be read***: the profile was wrapped twice. Run the `plutil` command from [Verify](#verify). If it shows `PayloadContent` instead of `apiToken`, delete that profile and upload the `.mobileconfig` under **Configuration Profiles** > **Upload**. * **Users can untick Velatir in Safari**: the Blueprint has not applied. Confirm it is deployed and scoped to the Mac, that the Mac is supervised, and that the identifier is exactly `com.velatir.safari-extension.extension (AA7QLU3S4R)`. Then quit and reopen Safari. * **Safari still offers Uninstall**: this is expected. The Blueprint keeps the extension on, but Safari always shows **Uninstall**. Removing the extension means deleting the app, which needs administrator rights. With Velatir for Desktop, the agent puts the app back within four hours. On the MDM route, scope the package policy to a smart group of Macs where the app is missing, and set the frequency to **Ongoing**. * **The policy succeeds but the version does not change** (MDM route): macOS skips the package when the Mac already has a higher version. Delete `/Applications/Velatir Safari Extension.app`, flush the policy logs for that Mac, and run the policy again. * **Collect diagnostics for support**: click five times anywhere inside the extension window to open its diagnostics view. Use **Copy report** and paste the result into your support request. ## Known limitations * Until the extension is on, by the Blueprint or by the user, Safari is not covered. * Without Velatir for Desktop, Safari traces carry no [directory context](https://docs.velatir.com/desktop-app/directory-context.md), and pasted content is not [redacted](https://docs.velatir.com/agents/redaction.md) on the device. *** > [card] [Enterprise deployment](https://docs.velatir.com/desktop-app/enterprise-deployment.md) > > Roll Velatir for Desktop out with Jamf, Intune, or any MDM > [card] [Enterprise overview](https://docs.velatir.com/setup/browser-extension-managed.md) > > Browser support, managed config, and other platforms This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.