Bridget Integration Guide

This guide explains how to embed the Bridget widget into your web or mobile application using an <iframe>. The widget URL handles data fetching, theming, and real-time events back to your app.

1. High-Level Integration Journey

A typical Bridget integration follows this end-to-end journey:

1. Backend authentication
   Your backend calls the Bridgewise authentication endpoint with your application credentials and receives an access token that Bridget widgets will use for all data calls.
2. Token storage and refresh
   The access token is stored securely on the backend and refreshed regularly (for example, every 24 hours), or immediately when authentication errors occur.
3. Frontend requests the token
   When a user opens a page that should display Bridget, your frontend calls your backend, retrieves the current access token, and constructs the Bridget widget URL.
4. Widgets are rendered
   The frontend embeds Bridget using an iframe:
   • bridget-chat for the full chat experience.
   • bridget-teaser as a compact teaser that can open the full chat.
5. Events and navigation
   The widget sends events to your application using postMessage(for example, load, resize, navigation, teaser-trigger). Your app listens for these events to:
   • Adjust the iframe height dynamically.
   • Handle navigation to your own security pages.
   • Open the full chat when a teaser question is clicked.
6. Monitoring and error handling
   Your application logs any relevant widget events and HTTP errors, and reacts to token issues (such as 401/403) by refreshing the token on the backend and reloading the widget if necessary.

2. Quick Start

Minimal Bridget Chat embed:

<iframe id="widget" src="https://embeded.bridgewise.com/en-US/bw/bridget-chat?accessToken=YOUR_TOKEN" style="width:100%; border:0; height:400px;"></iframe>

This example uses the default Bridgewise UI (tenant=bw) and the bridget-chat widget. You can switch to your own tenant and add identifiers, theming, and analytics parameters as described in the following sections.

3. URL Structure & Available Widgets

3.1 Base URL Format

All Bridget widgets share the same base URL structure:

https://embeded.bridgewise.com/{language}/{tenant}/{widgetName}?accessToken=...&identifier=...&identifierType=...&mode=...&actionType=...&sessionId=...&userId=...&scoringMethod=...

Path parameters

Query parameters (shared by all widgets)

3.2 Available Bridget Widgets

4. Bridget-Specific Parameters

5. Prompt Mapping & Examples

Parameters bridget.q, bridget.examples, and teaser.examples support a text/query mapping format: { t: "Displayed text", q: "Submitted prompt" }.

// Step 1 – define your prompts
const examples = [
  { t: "Hello" },
  { t: "Market recap", q: "Show me the daily market recap with key index moves." }
];
// Step 2 – stringify and encode
const param = encodeURIComponent(JSON.stringify(examples));

6. Events & postMessage

Bridget widgets send JSON-serialized messages to window.parent via postMessage.

7. Handling Navigation

8. Theming, Localization, Errors & Security

• Theming: Set mode=dark or light. Host iframe should have border:0.
• Localization: Pass language code in path (e.g. en-US, he-IL).
• Error handling: Listen for error events (e.g. invalid token) and surface a message.
• Security: Always validate event.origin is https://embeded.bridgewise.com.

9. Per-Security Text Customization

Use placeholders in customized text lines: {companyName} and {companyTicker}. When you load the widget with an ?identifier=... parameter, these are automatically replaced.

10. Native Mobile Integration

10.1 iOS (SwiftUI / UIKit)

import SwiftUI
import WebKit

struct WidgetView: UIViewRepresentable {
  @Binding var height: CGFloat
  let widgetURL: String
  func makeCoordinator() -> Coordinator { Coordinator(self) }
  func makeUIView(context: Context) -> WKWebView {
    let configuration = WKWebViewConfiguration()
    let userContentController = WKUserContentController()
    let script = """
      window.addEventListener('message', function (event) {
        if (event.origin !== 'https://embeded.bridgewise.com') return;
        window.webkit.messageHandlers.postMessage.postMessage(event.data);
      }, false);
    """
    let userScript = WKUserScript(source: script, injectionTime: .atDocumentStart, forMainFrameOnly: false)
    userContentController.addUserScript(userScript)
    userContentController.add(context.coordinator, name: "postMessage")
    configuration.userContentController = userContentController
    return WKWebView(frame: .zero, configuration: configuration)
  }
  func updateUIView(_ webView: WKWebView, context: Context) { 
      if let url = URL(string: widgetURL) { webView.load(URLRequest(url: url)) }
  }
  class Coordinator: NSObject, WKNavigationDelegate, WKScriptMessageHandler {
    var parent: WidgetView
    init(_ parent: WidgetView) { self.parent = parent }
    func userContentController(_ ucc: WKUserContentController, didReceive message: WKScriptMessage) {
      // Parse JSON message from iframe here
    }
  }
}

10.2 Android (WebView)

class WidgetWebView @JvmOverloads constructor(context: Context, attrs: AttributeSet? = null) : WebView(context, attrs) {
  init {
    settings.javaScriptEnabled = true
    settings.domStorageEnabled = true
    addJavascriptInterface(PostMessageHandler(), "AndroidInterface")
    webViewClient = object : WebViewClient() {
      override fun onPageFinished(view: WebView?, url: String?) {
        val script = """
          window.addEventListener('message', function (event) {
            if (event.origin !== 'https://embeded.bridgewise.com') return;
            AndroidInterface.handlePostMessage(typeof event.data === 'string' ? event.data : JSON.stringify(event.data));
          }, false);
        """
        evaluateJavascript(script, null)
      }
    }
  }
  inner class PostMessageHandler {
    @JavascriptInterface
    fun handlePostMessage(messageData: String) {
       // Handle JSON message
    }
  }
}

11. Mobile Integration Notes

• The widget is responsive and adapts to mobile viewports automatically.
• Use actionType=external to handle security selections in your app instead of redirecting to Bridgewise.
• Listen for error events to handle network or authentication issues gracefully.

12. Optional: Compression for Long Parameters

If your encoded JSON for bridget.examples is too long: Stringify → Gzip → Base64 → Prefix gz_ → URI Encode.

async function compress(str) {
  const blob = new Blob([str]);
  const stream = blob.stream().pipeThrough(new CompressionStream("gzip"));
  const compressed = await new Response(stream).arrayBuffer();
  return String.fromCharCode.apply(null, new Uint8Array(compressed));
}
async function encode(data) {
  const base64 = btoa(await compress(JSON.stringify(data)));
  return encodeURIComponent("gz_" + base64);
}