Go to the
current documentation.
目录
This guide describes how to work with the Chromium build used by JxBrowser.
You do not need to install Chromium or Google Chrome on the target environment to use JxBrowser. JxBrowser uses and deploys its own Chromium build.
Version
Actual JxBrowser version is based on Chromium 69.0.3497.12 engine and supports Windows, Linux and macOS platforms. All the required Chromium binaries are deployed with JxBrowser libraries, so you don’t need to install Google Chromium on the target environment.
Binaries
The jxbrowser-win32.jar, jxbrowser-win64.jar, jxbrowser-mac.jar, jxbrowser-linux64.jar libraries are part of JxBrowser library. They contain Chromium binaries for corresponding platform. At first run, JxBrowser extracts the binaries from appropriate JAR file into user’s temp directory on macOS and Linux, and AppData\Local\JxBrowser on Windows.
You can specify the directory path into which JxBrowser will extract Chromium binaries using the jxbrowser.chromium.dir system property. You can set the system property using the System.setProperty() method:
System.setProperty("jxbrowser.chromium.dir", "Users/Me/.jxbrowser");
Or through JVM parameter:
-Djxbrowser.chromium.dir="Users/Me/.jxbrowser"
The property must be set before you create the first Browser instance in your application.
You can extract Chromium binaries from the jxbrowser-<platform>.jar JAR file manually and configure JxBrowser to use them via the jxbrowser.chromium.dir system property. This property must contain a valid absolute/relative path to the directory with extracted Chromium binaries.
JxBrowser checks the directory and if the directory doesn’t contain the required Chromium files, JxBrowser searches for the binaries inside JAR files included in the application class path and extract them programmatically.
If JxBrowser cannot find Chromium binaries in the provided directory and none of the JAR files included into Java application class path contains Chromium binaries, an exception will be thrown during Browser instance initialization.
Switches
JxBrowser is based on Chromium engine. There are lots of command lines switches which can be used with Chromium. Some change behavior of features, others are for debugging or experimenting.
JxBrowser provides API that allows configuring Chromium with command line switches. The list of command line switches you can provide before you create any Browser instance. The following code demonstrates how to do it:
BrowserPreferences.setChromiumSwitches(
"--disable-web-security",
"--allow-file-access-from-files");
Language
JxBrowser allows configuring Chromium engine with specified language (two letter code from ISO-639 e.g. “en”, “de”, “it”, etc). The language will be used for UI text messages localization (e.g. text on the web page that’s displayed when Chromium failed to load URL).
By default Chromium engine is configured to use Java application language that can be received from the user.language System Property. To configure Chromium engine with Java application language, JxBrowser extracts the language from user.language System Property and pass it to Chromium engine via the --lang Chromium switcher.
If you need to change this default behavior, then you can configure Chromium engine directly with specified language via Chromium --lang switcher. Here’s examples that show how Chromium engine will display localized text on the Navigation Failed web page:
BrowserPreferences.setChromiumSwitches("--lang=en");
Extensions
JxBrowser doesn’t support Google Chrome extensions. Google Chrome extensions integrate with Google Chrome app UI such as tool bar, context menu, etc. So, it’s expected that Chrome extension is running in Google Chrome.
JxBrowser doesn’t integrate with Google Chrome app. It integrates only with web browser control that renders web content via Chromium engine. So, the library doesn’t have Google Chrome UI required for extensions. This is why JxBrowser doesn’t support extensions.
API Keys
JxBrowser is based on Google Chromium engine. Some Chromium features uses Google APIs. To access those APIs, an API Key is required. To acquire API Key follow the instruction.
You can provide the Chromium keys to JxBrowser Chromium engine using one of the following approaches:
- Via environment variables. Set the
GOOGLE_API_KEY,GOOGLE_DEFAULT_CLIENT_IDandGOOGLE_DEFAULT_CLIENT_SECRETenvironment variables to your “API key”, “Client ID” and “Client secret” values respectively. - Using the
BrowserPreferences.setChromiumVariable(String name, String value)method. For example:BrowserPreferences.setChromiumVariable("GOOGLE_API_KEY", "Your API Key"); BrowserPreferences.setChromiumVariable("GOOGLE_DEFAULT_CLIENT_ID", "Your Client ID"); BrowserPreferences.setChromiumVariable("GOOGLE_DEFAULT_CLIENT_SECRET", "Your Client Secret");You must configure Chromium variables before you create any
Browserinstance.
Geolocation
Geolocation is one of those Chromium features that uses the Google API. You must enable the Google Maps Geolocation API and billing, otherwise geolocation will not work.
Once you enable Google Maps Geolocation API and billing, you can provide the keys to the Chromium engine using one of the approaches described in Chromium API Keys.
Due to the security restrictions in Chromium 50 and higher, geolocation doesn’t work for file:/// URI. You must put a web page that works with the Geolocation API on a web server and access the web page through HTTPS protocol.
Permission
Please take into account that there is a specific permission that should be granted to enable geolocation in JxBrowser.
The following sample code demonstrates how to enable this permission:
browser.setPermissionHandler(new PermissionHandler() {
@Override
public PermissionStatus onRequestPermission(PermissionRequest request) {
if (request.getPermissionType() == PermissionType.GEOLOCATION) {
return PermissionStatus.GRANTED;
}
return PermissionStatus.DENIED;
}
});
Voice Recognition
Voice recognition is one of those Chromium features that uses Google API. You must enable the Speech API and billing, otherwise voice recognition will not work.
Once you enable Speech API and billing, you can provide the keys to JxBrowser Chromium engine using one of the approaches described in Chromium API Keys.
Sandbox
Windows
Starting with JxBrowser 6.17, Chromium sandbox support for Windows was added. By default, Sandbox is disabled to save backward compatibility with the previous versions. To enable Sandbox set the jxbrowser.chromium.sandbox System Property to true before you create a first Browser instance. For example:
System.setProperty("jxbrowser.chromium.sandbox", "true");
Browser browser = new Browser();
Linux and macOS
Currently, Sandbox is supported on Windows platform only.
Remote Debugging Port
JxBrowser provides functionality that allows you to use the Chrome Developer Tools remote debugging feature. To enable this feature you must define the --remote-debugging-port Chromium switch by calling the BrowserPreferences.setChromiumSwitches(String...) method before creating any Browser instance.
Once you configured JxBrowser to use a specified remote debugging port, you can get a remote DevTools URL by calling the Browser.getRemoteDebuggingURL() method:
BrowserPreferences.setChromiumSwitches("--remote-debugging-port=9222");
Browser browser = new Browser();
browser.loadURL("http://www.google.com");
String remoteDebuggingURL = browser.getRemoteDebuggingURL();
The remoteDebuggingURL you can load in another Browser instance to open Chrome Developer Tools page that allows inspecting HTML, debugging JavaScript etc.
Do not open the remote debugging URL in other web browser applications such as Mozilla FireFox, MS IE, etc. This will lead to a native crash in Chromium DevTools web server. The remote debugging feature is compatible only with the Chromium version that equals to the version used by JxBrowser library. For example, if you use JxBrowser 6.21 based on Chromium 69.0.3497.12, then you can open remote debugging URL in Google Chrome/Chromium 69.0.3497.12 only. We recommend that you always load the remote debugging URL in another Browser instance instead of Google Chrome.
Windows 32/64-bit
Since 6.21, JxBrowser distribution package includes Chromium 64-bit binaries for Windows platform. So, now JxBrowser provides both the jxbrowser-win32.jar and jxbrowser-win64.jar libraries that contain Chromium 32-bit and Chromium 64-bit binaries accordingly.
Please note that Chromium 64-bit binaries for Windows, supports only Windows 64-bit environment and cannot be used on Windows 32-bit.
Which one should be used? It depends on the Windows architecture and your Java application classpath.
- Both
jxbrowser-win32.jarandjxbrowser-win64.jaradded to the classpath. If you include both JAR files into your Java application classpath and run JxBrowser in a Windows environment for the first time, JxBrowser will check the environment architecture and extract/use the appropriate Chromium binaries. On Windows 64-bit JxBrowser will extract and use Chromium 64-bit binaries. On Windows 32-bit – Chromium 32-bit binaries. - Only jxbrowser-win32.jar added to the classpath. In this case Chromium 32-bit binaries will be extracted and used. Chromium 32-bit binaries work well in both Windows 32-bit and 64-bit environments.
- Only jxbrowser-win64.jar added to the classpath. In this case JxBrowser checks the Windows architecture. If it’s a Windows 64-bit environment, then Chromium 64-bit binaries will be extracted and used. If it’s a Windows 32-bit environment – an exception will be thrown.
Recommendations
If you know that your end users use only Windows 64-bit environment or Windows 32-bit isn’t supported by your software, then it’s recommended to use only jxbrowser-win64.jar.
If your software supports both Windows 32-bit and 64-bit environments, and it’s critical to have the size of your software distribution package as small as possible, then it’s recommended to use only jxbrowser-win32.jar.
If your software supports both Windows 32-bit and 64-bit environments, and the size of your software distribution package isn’t important, then you can use both jxbrowser-win32.jar and jxbrowser-win64.jar.