Configure on Firefox for macOS using native manifest

This article covers the process to configure the Pendo Launcher extension on the Mozilla Firefox web browser on a Mac computer using Mozilla’s native manifest functionality. Native manifests apply to both Windows and Mac devices, but the process for implementing them is different for each operating system (OS). The process described in this article can be used to configure the following types of data:

• API Key
• Visitor ID
• Metadata

For complete documentation on native manifests in Firefox, see Mozilla's Native manifests: Native messaging manifests documentation.

Prerequisites

Before configuring the extension on end-user devices, you must first install it on end-user browsers. See the IT guide to deploying the Pendo Launcher for all implementation options. We also recommend reading the Plan your browser extension implementation article before running any deployment steps.

Step 1. Create a PowerShell script

Adjust the following template script to include your own value for the API_KEY field and, if required, correctly capture your Visitor IDs and metadata.

Find your API key

Find the API key by navigating to Settings > Subscription Settings. Your unique extension API key is displayed at the top of the page and looks something like the following:

{
    "APIKey": {
        "Value": "c022bb1e-676d-4c58-731c-caf13fe12a89"
    }
}

Insert values into the template

In this template example, the current username is captured in the variable currentUser. The email domain example.com is appended to create the visitor ID, which is then stored in the file: /Library/Application Support/Mozilla/ManagedStorage/pendo-launcher@pendo.io.json.

You don't have to generate Visitor IDs in this way. The approach you follow for generating the Visitor ID value is determined by the plan you created according to the Plan your browser extension implementation article.

#!/bin/bash

# Set the API key
API_KEY="your-api-key-goes-here"

# Get current username
currentUser=$( echo "show State:/Users/ConsoleUser" | scutil | awk '/Name :/ { print $3 }' )

# Set domain name for emails
domainName="example.com"

# Create folder location if not there
dest_folder="/Library/Application Support/Mozilla/ManagedStorage"

if [ ! -d "$dest_folder" ]; then
  sudo mkdir -p "$dest_folder"
  sudo chown $(whoami) "$dest_folder"
fi

# JSON content
visitor_object='{
    "id": "'"$currentUser@$domainName"'",
}'

visitor_string=$(echo "$visitor_object" | jq tostring)

# For EU environments, change io to eu; for US1 environments, change io to us1; for Japan environments, change io to jpn
json_content='{
    "name": "pendo-launcher@pendo.io",
    "description": "Metadata for Pendo",
    "type": "storage",
    "data": {
        "APIKey": "'"$API_KEY"'",
        "visitor": '"$visitor_string"'
    }
}'

echo "$json_content" > "$dest_folder/pendo-launcher@pendo.io.json"

If available, additional metadata can be added as keys on the visitor object. For example, if you can determine the current user’s office location, you could pass the following as json_content:

visitor_object='{
    "id": "'"$currentUser@$domainName"'",
    "office": "$office"
}'

Step 2. Push your script to end-user devices

Using your MDM tooling, set the shell script to run on end-user devices on a regular basis. Pendo recommends running at least once daily or once every login. However, if there's metadata included in the file that might change periodically, you can increase the frequency to ensure that new data is provided to the browser promptly.

The specifics for running a shell script on end-user devices depends on your company’s MDM tooling. Below is the documentation for some of the most common MDM tools used for Mac devices:

• Jamf
• Kandji
• Hexnode
• Workspace ONE

Step 3. Validate your configuration

First, test the script on a single device that you can physically access to verify correct configuration. Validation involves confirming the presence of the native manifest file and validating the correct browser behaviour.

Confirm the presence of the native manifest file

1. Open the Mac terminal app.
2. Enter the command cd /Library/Application\ Support/Mozilla/ManagedStorage.
3. Enter the command ls -l.
4. Search for the pendo-launcher@pendo.io.json to check that it's listed in the output.
5. Check the contents of the file by entering the command cat pendo-launcher@pendo.io.json. Verify that the contents match the Visitor ID and metadata you expect to see.

Validate the browser behavior

Confirm that the browser is correctly reading the contents of the manifest file.

1. Open Firefox on the device with the manifest file. If the Firefox app is already running, quit and re-open it.
2. Install the Pendo Launcher browser extension on your Firefox browser. If you've already configured force-installation of the Pendo Launcher, you can skip this step.
3. Visit any non-Mozilla webpage, such as https://pendo.io/. 
4. Right-click on the Pendo Launcher extension icon in the top-right corner of your browser toolbar.
5. Select Show Debug Info.
6. Confirm that the Visitor ID in the Identified as field is correct.
7. Select Show Configuration Info.
8. Open the IT-Managed Config dropdown menu and search for your configuration values to check that they're present.