🔌 Bridge Protocol
🔍 Overview
type field prefixed with SANAL_.window.postMessage(json, '*') inside the WebView, or iframe.contentWindow.postMessage(json, '*') on web.window.SanalBridge.postMessage(json) (Flutter), ReactNativeWebView.postMessage (React Native), or window.parent.postMessage (iframe).📱 Embed the widget
Flutter
webview_flutter to pubspec.yaml. Register the channel name SanalBridge exactly (case-sensitive).INTERNET permission in AndroidManifest.xml.Web (iframe)
React Native
onMessage. Send to the widget with window.postMessage(json, '*') via injectJavaScript.➡️ Host → Widget
SANAL_INIT
SANAL_READY. Provides the user session. Processed once per widget session.{
"type": "SANAL_INIT",
"payload": {
"userId": "YOUR_USER_ID",
"authToken": "YOUR_JWT_OR_SESSION_TOKEN",
"language": "en"
}
}| Field | Required | Description |
|---|---|---|
userId | Yes | Platform customer ID |
authToken | Yes | Token for Sanal API calls |
aiUserId | No | AI user ID; defaults to userId |
language | No | en or ar |
address | No | Pre-selected delivery address |
location | No | { "lat", "long" } for AI context |
SANAL_CART_SYNC
{
"type": "SANAL_CART_SYNC",
"payload": {
"merchantId": "YOUR_MERCHANT_ID",
"items": [
{
"id": "line-1",
"uuid": "stable-uuid-per-line",
"product_id": "prod_123",
"variant_sku": null,
"modifiers": [],
"name": "Product name",
"price": 25.0,
"image": "https://...",
"quantity": 1,
"merchantId": "YOUR_MERCHANT_ID",
"merchantName": "Store name"
}
]
}
}SANAL_SEND_MESSAGE (optional)
{
"type": "SANAL_SEND_MESSAGE",
"payload": { "message": "Show me popular items" }
}⬅️ Widget → Host
| Message | Payload | Host action |
|---|---|---|
SANAL_READY | — | Send SANAL_INIT, then SANAL_CART_SYNC |
SANAL_CART_ADD | uuid, quantity, modifiers, variant_groups, variant_combinations | Add to your cart → SANAL_CART_SYNC |
SANAL_CART_REMOVE | uuid | Remove line → SANAL_CART_SYNC |
SANAL_CART_CHANGE | uuid, quantity, variantSku, modifiers | Update line → SANAL_CART_SYNC |
SANAL_CART_REQUEST | — | Reply with SANAL_CART_SYNC |
SANAL_NAVIGATE_CHECKOUT | — | Open your checkout |
SANAL_NAVIGATE_PRODUCT | productId | Open product screen |
SANAL_NAVIGATE_MERCHANT | merchantId | Open merchant screen |
SANAL_NAVIGATE_ADDRESSES | — | Open address screen |
SANAL_CLOSE_REQUESTED | — | Close chat screen |
SANAL_CART_ADD (production)
uuid and variant/modifier data.{
"type": "SANAL_CART_ADD",
"payload": {
"uuid": "new-line-uuid",
"quantity": 1,
"modifiers": [],
"variant_groups": [],
"variant_combinations": []
}
}| Field | Type | Description |
|---|---|---|
uuid | string | Cart line ID assigned by the widget; use for SANAL_CART_REMOVE / SANAL_CART_CHANGE |
quantity | number | Units to add |
modifiers | array | Selected modifier IDs |
variant_groups | array | Selected variant group data |
variant_combinations | array | Selected variant combination data |
SANAL_CART_SYNC with your full cart (including display fields your app owns).🧩 Flutter — send and receive
_onCartAdd, _onCartRemove, _onCartChange, _sendInit, _syncCart, and navigation using your own cart and routing.📋 Message summary
SANAL_INIT, SANAL_CART_SYNC, SANAL_SEND_MESSAGESANAL_READY, SANAL_CART_ADD, SANAL_CART_REMOVE, SANAL_CART_CHANGE, SANAL_CART_REQUEST, SANAL_NAVIGATE_*, SANAL_CLOSE_REQUESTED