Embedded Browsers

Embedded browsers enable native applications to integrate Tiro.health's session handover flow seamlessly within the application UI.

When integrating Tiro.health with native applications (Windows, macOS, or cross-platform desktop apps), embedded browsers provide several advantages:

  • Seamless user experience: Users remain within your application
  • Session control: Your application maintains control over the session lifecycle
  • Context preservation: Easily pass context and handle redirects programmatically
  • Security: Keep authentication tokens within the application boundary

This guide covers two popular embedded browser solutions:

  • WebView2: Microsoft's modern WebView for Windows applications
  • JxBrowser: Cross-platform Chromium-based browser for Java applications

Session Handover Pattern

The embedded browser integration follows the standard Session Management flow:

  1. Create a session from your backend (POST /sessions), which returns a handover_token
  2. Navigate the embedded browser to the handover URL carrying that token
  3. Intercept the redirect response to capture the redirect URL
  4. Handle the redirect in your application

The next parameter carries the Launch URL — the task to open once the session is active. Both parameters must be URL-encoded.

https://auth.tiro.health/sessions/$handover
  ?token=<handover_token>
  &next=https%3A%2F%2Fapp.tiro.health%2Fexternal%2Fv1%3Ftask%3DTask%2F123

Because the handover accepts a GET, the embedded browser only has to navigate to a URL — there is no HTML to build and no form to auto-submit.

Using a form instead

The handover also accepts a form POST, which is worth knowing if you already have that wired up:

<!DOCTYPE html>
<html>
<body>
  <form id="handover" action="https://auth.tiro.health/sessions/$handover" method="POST">
    <input type="hidden" name="token" value="YOUR_HANDOVER_TOKEN" />
    <input type="hidden" name="next" value="https://app.tiro.health/external/v1?task=Task/123" />
  </form>
  <script>document.getElementById('handover').submit();</script>
</body>
</html>

WebView2

WebView2 is Microsoft's recommended embedded browser solution for Windows applications. It uses the Microsoft Edge (Chromium) rendering engine.

Documentation:

Initialize WebView2

await webView.EnsureCoreWebView2Async();

Navigate to the Handover

var nextUrl = $"https://app.tiro.health/external/v1?task=Task/{taskId}";

var handoverUrl = "https://auth.tiro.health/sessions/$handover"
    + $"?token={Uri.EscapeDataString(handoverToken)}"
    + $"&next={Uri.EscapeDataString(nextUrl)}";

webView.CoreWebView2.Navigate(handoverUrl);

Intercept Redirect

webView.CoreWebView2.AddWebResourceRequestedFilter(
    "https://app.tiro.health/*",
    CoreWebView2WebResourceContext.Document
);

webView.CoreWebView2.WebResourceRequested += (sender, args) =>
{
    var uri = args.Request.Uri;
    if (uri.StartsWith("https://app.tiro.health/"))
    {
        args.Response = sender.Environment.CreateWebResourceResponse(
            null, 204, "No Content", ""
        );
        // Handle redirect in your application
    }
};

JxBrowser

JxBrowser is a commercial Chromium-based browser for Java applications that works on Windows, macOS, and Linux.

Documentation:

Initialize JxBrowser

Engine engine = Engine.newInstance(
    EngineOptions.newBuilder(renderingMode).build()
);
Browser browser = engine.newBrowser();

Navigate to the Handover

String nextUrl = "https://app.tiro.health/external/v1?task=Task/" + taskId;

String handoverUrl = "https://auth.tiro.health/sessions/$handover"
    + "?token=" + URLEncoder.encode(handoverToken, StandardCharsets.UTF_8)
    + "&next=" + URLEncoder.encode(nextUrl, StandardCharsets.UTF_8);

browser.navigation().loadUrl(handoverUrl);

Intercept Redirect

engine.network().set(
    InterceptUrlRequestCallback.class,
    params -> {
        String url = params.urlRequest().url();
        if (url.startsWith("https://app.tiro.health/")) {
            // Handle redirect
            return Response.intercept(params.urlRequest().newUrlRequest());
        }
        return Response.proceed();
    }
);

Security Considerations

When implementing embedded browser integration:

  1. Token Security: Never log or store session tokens
  2. HTTPS Only: Always use HTTPS for all communication
  3. Validate Redirects: Verify redirect URLs match expected domains
  4. Session Cleanup: Implement proper session cleanup on logout
  5. Keep Updated: Update WebView2 and JxBrowser regularly

For more information, see the Session Management API.

Was this page helpful?