Skip to main content
Skip table of contents

Browser Configuration profiles (API)

Browser Configuration parameters

Use these parameters in the JSON data structure when you apply the Browser Configuration policy to the app with app-market/policy.


Optional. Lets a user create a new bookmark for a web site. Users can add bookmarks from the options menu (three lines or three dots). The Launch Pad displays the websites that you have configured for the browser in a grid layout.

  • true: Adds the Bookmarks option to the options menu.
  • false (default): No option is available for adding bookmarks.

Optional. (iOS only) Whether to present an option in the options menu to share the page in an email address.

  • true: Enables the display of an option in the options menu to share the page in an email address.
  • false (default): Disables the display of an "allow email" option in the options menu.

Optional. Whether to allow users to view browser history and navigate to previously visited pages.

  • true: enables users to view browser history and navigate to previously visited pages
  • false (default): Disables the "allow history" feature.

Optional. Configures Compass to query a search engine when an incomplete URL is entered. The default search engine is Google.

Note: If you set allow_url_entry=false, it overrides the setting of allow_search=true.

  • true: Allows the browser to query a search engine when an incomplete URL is entered.
  • false (default): Does not allow the browser to query a search engine.

Optional. Indicates whether the user can edit the currently displayed URL in the browser.

Note: Setting allow_url_entry=false overrides the setting of allow_search=true.

Compass only supports http and https requests and does not support ftp requests.

  • true: The user can edit or enter a URL in the address field.
  • false (default): The URL appears in the address field, but the user cannot edit or enter a URL. The user can still refresh the page.
app_idOptional. (iOS only) This setting can be used to customize the iOS bundle ID for the Compass app. Administrators can use this ID to replace an older Compass with a new secured Compass. Only change this setting when directed by Blue Cedar support.
app_schemesOptional. (iOS only) An array of custom URL schemes to allow Compass to open external apps.

Optional. Sets the first HTML page that Compass displays when a new tab is opened. If no URL value is provided for this parameter, by default, a new tab will open to the Launch Pad.

Valid values: Accepts a URL.

launcher_icon_idThe Blue Cedar-generated ID for the launcher icon. (Appears in the response.)

The icon for the browser app that appears on the device's home screen. The user taps this icon to launch Compass.

When specifying the launcher icon, include the PNG file with the POST profile/mocana-browser/new launcher_icon parameter; use this parameter in the JSON data to point to that PNG file.

The icon image must be square. Blue Cedar recommends a minimum of 152 x 152 pixels for cross-platform icons. Check the target platform's guidelines for more specific requirements.

If not set, Compass uses the icon specified via settings/browser-launcher-icon. If that icon is not set, Compass uses the default Blue Cedar icon.


Optional. An array of customized browser settings for a website.  Each member of the array consists of individual settings for a single website. All members of an array constitute a group of websites that constitute the web app list.

Each member of the array accepts sub-parameters specified in a <name>:<value> pair format as JSON data. See Secure web app list below for details.


Optional. Specify the color of the Compass toolbars as an unsigned long data type in ARGB format, with the Alpha sample in the highest 8 bits, followed by the Red sample, Green sample, and Blue sample in the lowest 8 bit. ARGB values are typically expressed using hexadecimal digits, so you must convert this value into an unsigned long data type. For example, the hexadecimal value EF2B2D converts to 15674157 in the unsigned long data type. While the REST API supports such a color specification with the alpha component, it is currently not supported on the Android device and thus, the alpha component is ignored. 

Valid values:  Unsigned long data type (converted from a hexadecimal value). Default is 0.


Optional. A custom name for the Compass app name. The app name displays under the app icon that displays on the device's home screen.

Valid values: Must be a string. Default is an empty field.

Secure web app list

In the sites array, specify the secure websites displayed on the Compass Launch Pad, and customize the name, URL, and icon for each site. 

Site array parameterDescription
allow_closeOptional. A boolean value that indicates whether the user can remove the web page from the browser. Each page has a small optional "close" button. Useful when Compass is customized for many sites. Valid values (must be a string) are:
  • true: Allow the user to remove the web page from the Launch Pad view.
  • false: Prevent the user from removing the web page from the Launch Pad view. Default.

The Blue Cedar-generated ID for the site icon. (Appears in the response.)

idThe Blue Cedar-generated ID for the site. (Appears in the response.)
nameRequired. The "user-friendly" name for the URL. Must be a string.

Required. The URL for the site. Must be a string.

Compass only supports http and https requests.

Browser Configuration API resources

To manage browser profiles, use these resources:

  • profile/catalog/{policytype}: Use "browser" for "{policytype}". GET returns an array of details for all policy profiles of the specified type.
  • profile/mocana-browser/new: POST creates a new profile for Compass, using a file or JSON string to specify the profile data.
  • profile/mocana-browser/{GUID}: Use the profile ID to specify a policy profile. GET returns details for the specified profile, POST updates the details in the specified profile, and DELETE archives the profile.
  • settings/browser-default-profile (settings/{policytype}-default-profile):  POST sets one of the browser profiles as the default. GET returns the GUID of the current default profile. DELETE archives the current default.

To retrieve details for the policy:

  • app-policy/{GUID}: Use the policy ID to specify a policy. GET returns details for the specified policy.
  • app-policy/code/{code}: Use POLICY_CODE_MOCANA_BROWSER to specify the policy. GET returns details for the specified policy.

To secure Compass with the Browser Configuration policy:

  • app-market/policy: Use POLICY_CODE_MOCANA_BROWSER or the policy GUID to apply the policy along with a profile GUID to Compass.

To customize Compass features:

Creating a browser profile

This example creates a browser profile with profile/mocana-browser/new, specifying all options.


curl -k -v -L -b c.txt -c c.txt -X POST \ \
  -F profileName="TestProfile" \
  -F profileDesc="Default Profile" \
  -F browser_profile_data="{\"title\":\"Default Browser\",
     \"theme_color\":12055885}" \
  -F site_icon[0]=@/Users/jlennon/Downloads/lock-icon-48.png \
  -F launcher_icon=@/Users/jlennon/Downloads/lock-icon-48.png 

This is an example of JSON-formatted data for an existing browser profile returned from GET profile/mocana-browser/{GUID}/json

Note: The response may include deprecated parameters. Supported parameters are described above.


   "message": "",
   "profiles": {
     "data": {
       "profile_data": {
         "allow_bookmarks": true,
         "allow_email": true,
         "allow_history": true,
         "allow_invalid_certs": false,
         "allow_printing": false,
         "allow_search": true,
         "allow_url_entry": true,
         "home_page": "",
         "krb5": "",
         "launcher_icon_id": "6f57eba7-2db0-481e-8d2c-bec43ad2838a",
         "launcher_icon_url": "",
         "sites": [{
           "allow_close": true,
            "icon_id": "2282d966-0eab-45e5-9353-a6f53e474c26",
            "icon_url": "",
            "id": "b807001d-f0aa-492d-83ab-4880013c3f65",
            "name": "default-site-1",
            "sso_script": "",
            "sso_type": 0,
            "url": "",
            "use_favicon": false
          "theme_color": 12055885,
          "title": "Default Browser"
        "profile_data_id": "7ef21657-7ed2-4372-b35d-4b8762fbc783",
        "profile_data_stamp": "2016-08-19 15:01:50.0"
      "profile_desc": "Default Profile",
      "profile_id": "555fec78-160f-4503-b787-db291cb6d7d3",
      "profile_name": "TestProfile",
      "profile_type": "browser",
      "profile_url": ""
  "status": "OK"
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.