Setting a custom protocol

Sometimes your application needs to handle links that use protocols other than HTTP or HTTPS. By default, Chromium’s security model blocks non‐standard protocol handlers. That means if a web page served in an embedded Equo Chromium browser tries to open a mailto: link or a tel: link, nothing will happen unless you explicitly allow it. Equo Chromium provides a configuration property that allows you to control how these custom protocols are treated, whether to allow them automatically, prompt the user, or whitelist only specific schemes.

Usage

You can configure custom‐protocol handling by supplying the chromium.custom_protocol system property when starting your Java application. When this property is set, the embedded browser will follow your preference, which must be one of the following supported modes:

  • Allow all custom protocols.

  • Allow all custom protocols but prompt the user before delegating.

  • Allow only a specific set of protocols.

Always set the chromium.custom_protocol property before initializing any Browser or ChromiumBrowser instance. Otherwise, Chromium will use its default blocking behavior.

The following examples show the three supported modes:

Allow all custom protocols

-Dchromium.custom_protocol=true

If set to true, all non‐HTTP(S) links are delegated directly to the OS or the application registered to handle that protocol. There is no prompt, so the user experience is seamless—links simply work.

Allow all custom protocols but prompt the user before delegating

-Dchromium.custom_protocol=confirm

If set to confirm, the user sees a confirmation dialog each time a non‐HTTP(S) link is clicked. The user must approve before the browser invokes the external application.

Allow only a specific set of protocols

-Dchromium.custom_protocol="mailto;tel;"

If set to a semicolon‐delimited list (e.g., "mailto;tel;"), only the listed schemes will be allowed; all other custom protocols will remain blocked. The list must end with a semicolon and contain no spaces between entries.

Replace "mailto;tel;" with whatever protocols your application needs.

When to use this feature

  • Email Links (mailto:) If your application displays web content containing mailto: links (for example, a “Contact Us” form), enabling the mailto protocol ensures that clicking such a link will open the user’s default email client.

  • Telephone Links (tel:) For applications used on systems with telephony support (for instance, desktop VoIP apps), allowing tel: links lets users click a phone number on a web page and dial directly.

  • Custom App Integrations If your organization has registered a proprietary protocol (for example, myapp:) for deep integration with a desktop or mobile application, you can whitelist only that protocol while keeping all others blocked.