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:

Create a session via the backend API (POST /session)
Inject an HTML form containing the session token into the embedded browser
Submit the form to the handover endpoint (POST /session/$handover)
Intercept the redirect response to capture the redirect URL
Handle the redirect in your application

The HTML form for session handover:

<!DOCTYPE html>
<html>
<body>
  <form id="handover" action="https://reports.tiro.health/session/$handover" method="POST">
    <input type="hidden" name="token" value="YOUR_SESSION_TOKEN" />
    <input type="hidden" name="next" value="https://app.tiro.health/reports/edit" />
  </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();

Inject HTML Form

var html = $@"<!DOCTYPE html>
<html><body>
  <form id='handover' action='https://reports.tiro.health/session/$handover' method='POST'>
    <input type='hidden' name='token' value='{sessionToken}' />
    <input type='hidden' name='next' value='{nextUrl}' />
  </form>
  <script>document.getElementById('handover').submit();</script>
</body></html>";

webView.CoreWebView2.NavigateToString(html);

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();

Inject HTML Form

String html = "<!DOCTYPE html><html><body>" +
    "<form id='handover' action='https://reports.tiro.health/session/$handover' method='POST'>" +
    "<input type='hidden' name='token' value='" + sessionToken + "' />" +
    "<input type='hidden' name='next' value='" + nextUrl + "' />" +
    "</form>" +
    "<script>document.getElementById('handover').submit();</script>" +
    "</body></html>";

browser.navigation().loadHtml(html);

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:

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

For more information, see the Session Management API.