This guide shows how to work with the network-related functionality such as proxy, network events, authentication, TLS, client certificate authentication, etc.

Accept Language

JxBrowser allows configuring the Accept-Language via the NetworkService.setAcceptLanguage(String) method. The acceptLanguage string represents the Accept-Language HTTP header value.

For example, the “fr, en-gb;q=0.8, en;q=0.7” value would mean: “I prefer French, but will accept British English, and other types of English”:

networkService.setAcceptLanguage("fr, en-gb;q=0.8, en;q=0.7");

Server Whitelist

HTTP Server Authorization Whitelist

You can configure HTTP server authorization whitelist that represents a string with a list of comma/semicolon separated URLs. For example:

networkService.setServerWhitelist("*google.com,*example.com,*baz");

HTTP Network Delegate Whitelist

To configure HTTP network delegate whitelist you can use the approach described below:

networkService.setDelegateWhitelist("*google.com,*example.com,*baz");

TLS

Certificate Verification

By default Chromium verifies all SSL certificates obtained from a web server during the web page loading. JxBrowser allows modifying this default behavior and take control over the verification process.

To handle certificate verification use the VerifyCertificateCallback callback. Before this callback is invoked, Chromium verifies SSL certificate and provides the results of the verification to the callback. With the results of verification, the callback receives the SSL certificate itself. You can verify the given SSL certificate and notify the engine with the verification results.

For example:

networkService.set(VerifyCertificateCallback.class, (params, callback) -> {
    // SSL Certificate to verify.
    Certificate certificate = params.getCertificate();
    // The results of the verification performed by default verifier.
    List<CertVerificationStatus> verificationStatuses =
            params.getVerificationStatusesList();
    // The results of default verification should be used.
    callback.defaultAction();
});

Ignoring Certificate Errors

When you load HTTPS web site, JxBrowser verifies its SSL certificate. If the SSL certificate is invalid, the library calls the CertificateErrorCallback callback and depending on the callback return value, it can cancel web page loading or ignore the error and continue loading the insecure web page.

By default JxBrowser cancels HTTPS web page loading if its SSL certificate is invalid.

To ignore the SSL certificate error and continue loading an insecure web page please use the following approach:

browser.set(CertificateErrorCallback.class, (params, callback) -> {
    String url = params.getUrl();
    // The reason of the certificate error.
    NetError netError = params.getNetError();
    // The invalid SSL certificate.
    Certificate certificate = params.getCertificate();
    // Ignore the error and allow the invalid SSL certificate.
    callback.allow();
});

Client Certificate Authentication

JxBrowser supports authentication using HTTPS client certificates. Please check the Authentication guide for details.

Network Events & Callbacks

The NetworkService API defines a set of events and callbacks that follow the life cycle of a web request. You can use these events to observe and analyze traffic. The callbacks will allow you to intercept, block, or modify requests.

The event life cycle of successful requests looks as follows: Network Events Flow

Before URL Request

The BeforeUrlRequestCallback callback is invoked when an HTTP request is about to occur. You can use this callback to redirect the request to another location. For example:

networkService.set(BeforeUrlRequestCallback.class, (params, callback) ->
        callback.redirect("<new-url>"));

Before Send Upload Data

The BeforeSendUploadDataCallback callback is invoked before the upload data is sent to a web server. Here you can override the upload data. For example:

networkService.set(BeforeSendUploadDataCallback.class, (params, callback) ->
        callback.proceed(UploadData.newBuilder()
                .setTextData(TextData.newBuilder()
                        .setData("<text-data>")
                        .build())
                .build()));

This callback will not be called if the request does not have the upload data.

The following UploadData types are supported:

  • BytesData represents a sequence of bytes.
  • TextData the data of the text/plain content type.
  • FormData the data of the application/x-www-form-urlencoded content type.
  • MultipartFormData the data of the multipart/form-data content type.

Before Start Transaction

The BeforeStartTransactionCallback callback is invoked before the network transaction starts. In this callback you can add or override the HTTP headers before they are sent out. For example:

networkService.set(BeforeStartTransactionCallback.class, (params, callback) -> {
    Collection<HttpHeader> customHttpHeaders =
            new ArrayList<>(params.getHttpHeadersList());
    customHttpHeaders.add(HttpHeader.newBuilder()
            .setName("<header-name>")
            .setValue("<header-value>")
            .build());
    callback.proceed(customHttpHeaders);
});

Before Send Headers

The BeforeSendHeadersCallback callback is invoked when a URL request is about to occur and the initial HTTP headers are prepared. In this callback you can add, modify, and delete the HTTP request headers before they are sent to a web server. For example:

networkService.set(BeforeSendHeadersCallback.class, (params, callback) -> {
    Collection<HttpHeader> httpHeaders =
            new ArrayList<>(params.getHttpHeadersList());
    httpHeaders.add(HttpHeader.newBuilder()
            .setName("<header-name>")
            .setValue("<header-value>")
            .build());
    callback.proceed(httpHeaders);
});

The following headers are currently not provided to the callback. This list is not guaranteed to be complete nor stable:

- Authorization
- Cache-Control
- Connection
- Content-Length
- Host
- If-Modified-Since
- If-None-Match
- If-Range
- Partial-Data
- Pragma
- Proxy-Authorization
- Proxy-Connection
- Transfer-Encoding

Before Send Proxy Headers

The BeforeSendProxyHeadersCallback callback is invoked when a URL request is about to occur and the initial HTTP headers have been prepared through the proxy connection. In this callback you can add, modify, and delete the HTTP request headers before they are sent to a web server. For example:

networkService.set(BeforeSendProxyHeadersCallback.class, (params, callback) -> {
    Collection<HttpHeader> httpHeaders =
            new ArrayList<>(params.getHttpHeadersList());
    httpHeaders.add(HttpHeader.newBuilder()
            .setName("<header-name>")
            .setValue("<header-value>")
            .build());
    callback.proceed(httpHeaders);
});

Start Transaction

The StartTransaction event is fired when a URL request is about to be sent out. In this event you can access the request and HTTP headers that will be sent out. For example:

networkService.on(StartTransaction.class, event -> {
    UrlRequest urlRequest = event.getUrlRequest();
    List<HttpHeader> httpHeaders = event.getHttpHeadersList();
});

Headers Received

The HeadersReceivedCallback callback is invoked for HTTP requests when the headers have been received. Here you can add, modify, or remove the HTTP headers received over the network. For example:

networkService.set(HeadersReceivedCallback.class, (params, callback) -> {
    Collection<HttpHeader> httpHeaders =
            new ArrayList<>(params.getHttpHeadersList());
    httpHeaders.add(HttpHeader.newBuilder()
            .setName("<header-name>")
            .setValue("<header-value>")
            .build());
    callback.proceed(httpHeaders);
});

Before Redirect

The BeforeRedirect event is fired when a redirect response code 3xx has been received for the request. In this event you can get the details about the redirect such as new URL and response code. For example:

networkService.on(BeforeRedirect.class, (event) -> {
    String newUrl = event.getNewUrl();
    int responseCode = event.getResponseCode();
});

Response Started

The ResponseStarted event is fired when the first byte of the URL response body has been received. For HTTP requests this means that the status line and the response headers are available. In this event you can access the corresponding request and the response code. For example:

networkService.on(ResponseStarted.class, (event) -> {
    UrlRequest urlRequest = event.getUrlRequest();
    int responseCode = event.getResponseCode();
});

Data Received

The DataReceived event is fired when a part of the URL response body has been received. In this event you can access the MIME type of the received data and the data bytes. For example:

networkService.on(DataReceived.class, (event) -> {
    MimeType mimeType = event.getMimeType();
    ByteString data = event.getData();
});

Request Completed

The RequestCompleted event is fired when the URL request has been successfully completed or failed. In this event you can check whether the request has been started at all, get the details of the request state, access the response code. For example:

networkService.on(RequestCompleted.class, (event) -> {
    UrlRequest urlRequest = event.getUrlRequest();
    // Indicates whether request has been started.
    boolean started = event.getStarted();
    // The details of the URL request state.
    RequestStatus requestStatus = event.getRequestStatus();
    // The HTTP response code.
    int responseCode = event.getResponseCode();
});

Request Destroyed

The RequestDestroyed event is fired when the request has been destroyed and it cannot be used anymore. To access the details of the destroyed request use the following code:

networkService.on(RequestDestroyed.class, (event) -> {
    UrlRequest urlRequest = event.getUrlRequest();
});
Go Top