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 |
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 containingmailto:
links (for example, a “Contact Us” form), enabling themailto
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), allowingtel:
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.