Architecture
The Hacktionbase widget is an iframe embedded in your page by the SDK. It communicates with the SDK via the browser’s postMessage API.
┌──────────────────────────────────┐
│ Your Website │
│ │
│ ┌────────────────────────┐ │
│ │ Hacktionbase SDK │ │
│ │ (bubble + listeners) │ │
│ └──────────┬─────────────┘ │
│ │ postMessage │
│ ┌──────────▼─────────────┐ │
│ │ Widget iframe │ │
│ │ ({tenant}.hacktionbase.com) │
│ │ - Conversations │ │
│ │ - In-app messages │ │
│ └────────────────────────┘ │
└──────────────────────────────────┘
Components
The widget consists of two visible elements:
- Bubble — a floating button in the corner of the page. Clicking it toggles the panel open/closed.
- Panel — the iframe containing the widget UI (conversations, messages).
Lifecycle
Hacktionbase.init() fetches the widget configuration from the API- The SDK injects CSS, creates the bubble, and creates a hidden iframe
- When the iframe loads, it sends
hacktionbase:ready
- The SDK responds with config and session context
- The widget authenticates via the widget auth endpoint and receives a JWT
- The user can now open the panel, view conversations, and receive in-app messages
PostMessage protocol
All messages between the SDK and widget use a hacktionbase: prefix:
| Message | Description |
|---|
hacktionbase:widget_context | Session data (sessionId, anonymousId, userId, sdkKey, device info) |
hacktionbase:config | Widget appearance configuration |
hacktionbase:identify | User identification data |
| Message | Description |
|---|
hacktionbase:ready | Widget iframe has loaded |
hacktionbase:close | User clicked close button in the widget |
hacktionbase:widget_auth_success | Authentication complete (includes widget JWT) |
hacktionbase:show_modal | Trigger an in-app message modal in the host page |
hacktionbase:resize | Request panel height change |
All postMessage communication is origin-verified. The SDK only accepts messages from your tenant’s widget origin ({tenant}.hacktionbase.com).
