Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.go.gbgplc.com/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the security model for the TypeScript Bridge SDK across each embedding environment. The threat model differs sharply between native WebViews and iframes — native platforms enforce origin scoping at the OS level, whereas iframes require explicit origin validation in the bridge config.

​
Transport security by environment

EnvironmentSecurity modelOrigin validation
iOS (WKWebView)Messages scoped to loaded web content. OS enforces that only the WebView’s content can send messages.Built-in by the platform
Android (WebView)Messages scoped via @JavascriptInterface. Only JavaScript inside the WebView can call interface methods.Built-in by the platform
iframeUses postMessage which supports cross-origin communication. Origin validation is required.Must be configured
StandaloneNo communication occurs. Messages are silently dropped.N/A

​
iframe origin validation

When running in an iframe, the bridge validates message origins in both directions.

​
Incoming messages (host to web)

Configure iframeAllowedOrigins to restrict which parent origins can send messages: 
const bridge = NativeBridge.getInstance({
  iframeAllowedOrigins: ['https://app.example.com'],
});
If iframeAllowedOrigins is empty (default), messages from any origin are accepted.
In production, always specify allowed origins for iframe embeddings.

​
Outgoing messages (web to host)

Configure iframeTargetOrigin to restrict where messages are sent: 
const bridge = NativeBridge.getInstance({
  iframeTargetOrigin: 'https://app.example.com',
});
Defaults to window.location.origin. This prevents messages from being intercepted by a malicious parent frame on a different origin. Combine the two settings: list every parent origin you accept messages from in iframeAllowedOrigins, and pin iframeTargetOrigin to the single origin you send messages to. In practice this means including staging in iframeAllowedOrigins (so you can dev/test against it) while still scoping the target origin to production: 
const bridge = NativeBridge.getInstance({
  iframeAllowedOrigins: ['https://app.example.com', 'https://staging.example.com'],
  iframeTargetOrigin: 'https://app.example.com',
});
iframeAllowedOrigins controls who can talk to the bridge; iframeTargetOrigin controls who the bridge talks back to. Both must be set in production iframe deployments.

​
PII and sensitive data

​
What the bridge transmits

The bridge is a transport layer — it sends whatever data you put in the data field of requests and events.
Data typeTypical flowRecommendation
Captured images, base64Host to web in responseTransmitted in-memory; not persisted by the bridge
Journey IDsWeb to host in eventsNon-sensitive identifiers
TimestampsBoth directionsNon-sensitive
Theme/locale dataHost to web in eventsNon-sensitive
Error messagesHost to web in responsesShould not contain PII

​
Best practices

  1. Don’t include PII in event payloads — Journey events should contain IDs and metadata, not personally identifiable information.
  2. Images are transient — Base64 image data passes through the bridge but is not stored. The message log (capped at 500 entries) may temporarily contain image data.
  3. Don’t log message payloads in production — onMessageLog() and getMessageLog() are debugging tools. Avoid logging full payloads to external services.

​
Message integrity

The bridge does not sign or encrypt messages. The security model relies on:
  • Native platforms (iOS/Android): The OS ensures only the WebView’s content can communicate with the host.
  • iframe: Origin validation ensures messages only flow between trusted origins.

​
Content Security Policy

If your application uses CSP, ensure it allows the embedding via the frame-ancestors directive: 
Content-Security-Policy: frame-ancestors 'self' https://your-host-domain.com;

​
Token and credential handling

The bridge itself does not handle authentication tokens, API keys, or credentials. Do not send tokens or secrets through the bridge’s event or request system. If the host needs to provide an API token to the web app, do so via the initial page URL or configuration injection — not through bridge messages.

​
Version compatibility

The bridge includes a protocol version ('1.0') in every message. If the web SDK and host app have different protocol versions, messages with mismatched versions are still processed (with a console warning), providing forward compatibility.