Module com.gluonhq.attach.browser
Package com.gluonhq.attach.browser

Interface BrowserService

All Known Implementing Classes:
AndroidBrowserService, DesktopBrowserService, DummyBrowserService, IOSBrowserService
public interface BrowserService
Launches the default browser of the platform as a separate application process. The browser will be opened with the provided URL by means of launchExternalBrowser(String).

Example

 BrowserService.create().ifPresent(service -> {
      service.launchExternalBrowser("https://gluonhq.com/");
  });

The service can also be used to perform secure user authentication against a web service (for instance an OAuth 2.0 / OpenID Connect provider), using an embedded browser, by means of launchWebAuthentication(String, String, Consumer).

Example

 BrowserService.create().ifPresent(service -> {
      service.launchWebAuthentication(
              "https://my-auth-provider.com/authorize?response_type=token&redirect_uri=myapp://callback",
              "myapp",
              callbackUrl -> {
                  if (callbackUrl != null) {
                      System.out.println("Authenticated, callback: " + callbackUrl);
                  } else {
                      System.out.println("Authentication cancelled or failed");
                  }
              });
  });

Android Configuration: none

iOS Configuration: none

Since:
3.0.0

  • Method Details

    • create

      static Optional<BrowserService> create()
      Returns an instance of BrowserService.
      Returns:
      An instance of BrowserService.

    • launchExternalBrowser

      void launchExternalBrowser(String url) throws IOException, URISyntaxException
      Launches the user-default browser to show a specified URL.
      Parameters:
      url - The URL to load when the browser application opens.
      Throws:
      IOException - If the URL can't be opened
      URISyntaxException - If it is not a valid URL string

    • launchWebAuthentication

      void launchWebAuthentication(String url, String callbackUrlScheme, Consumer<String> callback) throws IOException, URISyntaxException
      Starts a web authentication session that lets the user authenticate against a web service, and delivers the redirect (callback) URL back to the app once the authentication flow completes.

      On iOS this is implemented with a secure, dedicated native web view on top of the app. When the web service redirects to a URL that matches callbackUrlScheme, the session is automatically dismissed and the full callback URL with the authorization code is passed to callback. The redirect is secure and never travels through the system URL dispatch.

      The callbackUrlScheme can be provided in two forms:

      • A custom URL scheme (without ://, e.g. "myapp"), with a redirect like myapp://callback. No Info.plist URL scheme registration is required, since the session intercepts the redirect on its own.
      • A full HTTPS URL (e.g. "https://example.com/callback"), with a verified HTTPS redirect. This requires iOS 17.4 or higher and the following setup:
        • The Associated Domains capability enabled on an explicit App ID (a wildcard App ID cannot carry it), and a provisioning profile that grants it.
        • The app's entitlements must declare the domain under the webcredentials service type (e.g. webcredentials:example.com).
        • An apple-app-site-association file hosted at https://example.com/.well-known/apple-app-site-association (served as application/json, no redirects) containing a webcredentials section that lists the app, e.g. {"webcredentials":{"apps":["TEAMID.bundle.id"]}}.
        • For local development with a development-signed build (where the file is not on Apple's CDN), append ?mode=developer to the entitlement domain and enable Settings > Developer > Associated Domains Development on the device.

      iOS Configuration: none for the custom-scheme form; the HTTPS form requires the Associated Domains capability and webcredentials entitlement described above.

      On Android and Desktop the default implementation simply opens the URL in the external browser (see launchExternalBrowser(String)). On Android the redirect is caught by the system through an HTTPS or custom-scheme intent filter declared in the AndroidManifest.xml, and the resulting URL can be read with the RuntimeArgsService.

      Parameters:
      url - the authentication URL to load, including the redirect_uri expected by the web service.
      callbackUrlScheme - either a custom URL scheme (without ://, e.g. "myapp") or a full HTTPS URL (e.g. "https://example.com/callback") that the web service uses for its redirect.
      callback - a consumer that receives the full callback URL on success, or null if the user canceled the flow or an error occurred.
      Throws:
      IOException - If the URL can't be opened
      URISyntaxException - If it is not a valid URL string
      Since:
      4.0.25