Setting a custom protocol

Sometimes your application needs to handle links that use protocols other than HTTP or HTTPS—things like launching an email client with a mailto: link or opening a dialer with a tel: link. By default, Chromium will block any “non-standard” protocols for security reasons. 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. The following examples show the three supported modes:

Allow all custom protocols. Any link that uses a non‐HTTP(S) scheme will be handed off directly to the operating system without any prompt:

-Dchromium.custom_protocol=true

Allow all custom protocols, but prompt the user before delegating. When the browser encounters a non‐HTTP(S) link, it will first ask the user if they want to proceed:

-Dchromium.custom_protocol=confirm

Allow only a specific set of protocols. List the allowed schemes separated by semicolons (;). For example, this will permit only mailto: and tel::

-Dchromium.custom_protocol="mailto;tel;"

Replace "mailto;tel;" with whatever protocols your application needs. Any scheme not listed will be blocked by Chromium.

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

Description

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 (to send an email) or a tel: link (to start a phone call), nothing will happen unless you explicitly allow it.

When you set chromium.custom_protocol, the embedded browser will consult your preference:

  • 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.

  • 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.

  • 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 (remember the list must end with a semicolon and contain no spaces between entries). This is useful when you want tighter control and only need a few well‐known handlers.

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.