The custom events system is a powerful feature that enables two sided data communication between a miniapp and a host app. The miniapp can send any data that can be recognised by the host app. Further, certain operations can be implemented on the native app level.
One possible scenario is when the user pays for the miniapp product on the level of the host app by using a host app’s payment system. The possible flow would be:
Here’s a revised version of the flow for clarity:
This flow ensures that the interaction between the miniapp and host app is smooth and that purchase transactions are accurately tracked.
Calling custom event from miniapp:
Calling custom event from miniapp with promise:
Receiving custom event sent from host app:
Boxo Event Bridge is a bidirectional communication functionality that enables miniapps to exchange events and information with host apps seamlessly through the Boxo platform. This feature allows miniapps to send notifications, request data, or respond to events initiated by the host app, creating a more integrated and interactive user experience.
Here is a diagram illustrating the event communication process between a miniapp and a host app.
Here is the streamlined process for event communication in the Boxo ecosystem:
The Miniapp creates an event with a specific event type and payload.
The Miniapp server sends the event to the Boxo Platform through the Event Bridge API.
The Boxo Platform validates the event and forwards it to the Host app server.
The Host app server processes the event and returns a response to the Boxo Platform.
The Boxo Platform forwards the response back to the Miniapp server.
The Miniapp server processes the response and takes appropriate actions.
Alternatively, the process can start with the host app creating an event:
The Host app creates an event for a specific miniapp.
The Host app server sends the event to the Boxo Platform.
The Boxo Platform forwards the event to the Miniapp server.
The Miniapp server processes the event and returns a response.
The Boxo Platform forwards the response back to the Host app server.
Note: Feature must be enabled in Dashboard Partnership
Data format The Boxo platform uses JSON format for data exchange. Event payloads can contain any valid JSON structure that follows the agreed-upon schema between the miniapp and host app.
This endpoint is on the Boxo platform. Send a request to deliver an event to a host app.
URL and METHOD:
This is HTTPS POST /api/v1/event-bridge/miniapp/
endpoint
IP address of requesting services must be provided in Dashboard for whitelisting or Request Signaturing must be enabled
Headers
Key | Value |
---|---|
Content-type | application/json |
Body:
Field | Data type | Optional | Description |
---|---|---|---|
app_id | String | No | Miniapp identifier |
client_id | String | No | Hostapp identifier |
event_type | String | No | Type of event (e.g., “order_created”) |
payload | Object | No | Event data in JSON format |
Response:
Response status will be 400
in case there is error_code
Response body: The response body will contain the host app’s response to the event, or an error message if delivery failed.
Field | Data type | Optional | Description |
---|---|---|---|
error_code | String | Yes | Error code if event delivery failed |
error_message | String | Yes | Detailed error message |
… | … | … | Additional fields from host app response |
Request Example:
Response Example:
Success response (containing host app’s response):
Error response:
Set up this endpoint to receive events from host apps through the Boxo platform.
URL and METHOD: This endpoint must handle a HTTPS POST request URL to endpoint must be provided in Dashboard
Headers:
Key | Value |
---|---|
Authorization | Basic <base64 encoded(app_id:secret_key)> |
Content-type | application/json |
app_id
and secret_key
will be provided in Dashboard
Body:
Field | Data type | Description |
---|---|---|
app_id | String | Miniapp identifier |
client_id | String | Hostapp identifier |
event_type | String | Type of event (e.g., “user_updated”) |
payload | Object | Event data in JSON format |
Response:
Response status must be 200
in all cases
Response body can contain any valid JSON that will be forwarded to the host app
Request Example:
Response Example:
Here are some common event types that can be used for communication between miniapps and host apps:
Event Type | Description | Example Payload |
---|---|---|
order_created | A new order has been created in the miniapp | {"order_id": "ord_123", "amount": 50.25} |
product_viewed | User has viewed a product in the miniapp | {"product_id": "prod_123", "category": "shoes"} |
cart_updated | User’s shopping cart has been updated | {"cart_id": "cart_123", "item_count": 3} |
content_shared | User has shared content from the miniapp | {"content_id": "cont_123", "content_type": "image"} |
checkout_started | User has initiated the checkout process | {"cart_id": "cart_123", "amount": 75.00} |
Event Type | Description | Example Payload |
---|---|---|
user_profile_updated | User profile information has been updated | {"user_id": "123", "updated_fields": ["email"]} |
location_updated | User’s location has been updated | {"latitude": 37.7749, "longitude": -122.4194} |
app_state_change | The state of the host app has changed | {"new_state": "background", "timestamp": 123456} |
language_changed | User has changed their language preference | {"language_code": "es", "locale": "es_MX"} |
theme_changed | User has changed their theme preference | {"theme": "dark", "color_scheme": "blue"} |
If an error occurs during event processing, the Boxo Platform will return an appropriate error response:
Error Code | Description |
---|---|
EVENT_RECEIVER_DISABLED | Event receiver is not enabled for the host app |
INVALID_EVENT_DATA | The event data format is invalid |
EVENT_DELIVERY_FAILED | Failed to deliver the event to the host app |
UNAUTHORIZED | Miniapp is not authorized to send events |
INTEGRATION_DISABLED | Event bridge is not enabled for this integration |
For client-side event handling in your miniapp, you can use the Boxo JS SDK:
By utilizing the Boxo Event Bridge, your miniapp can create seamless integrations with host apps, improving user experience and enabling more advanced functionality through real-time communication.
The custom events system is a powerful feature that enables two sided data communication between a miniapp and a host app. The miniapp can send any data that can be recognised by the host app. Further, certain operations can be implemented on the native app level.
One possible scenario is when the user pays for the miniapp product on the level of the host app by using a host app’s payment system. The possible flow would be:
Here’s a revised version of the flow for clarity:
This flow ensures that the interaction between the miniapp and host app is smooth and that purchase transactions are accurately tracked.
Calling custom event from miniapp:
Calling custom event from miniapp with promise:
Receiving custom event sent from host app:
Boxo Event Bridge is a bidirectional communication functionality that enables miniapps to exchange events and information with host apps seamlessly through the Boxo platform. This feature allows miniapps to send notifications, request data, or respond to events initiated by the host app, creating a more integrated and interactive user experience.
Here is a diagram illustrating the event communication process between a miniapp and a host app.
Here is the streamlined process for event communication in the Boxo ecosystem:
The Miniapp creates an event with a specific event type and payload.
The Miniapp server sends the event to the Boxo Platform through the Event Bridge API.
The Boxo Platform validates the event and forwards it to the Host app server.
The Host app server processes the event and returns a response to the Boxo Platform.
The Boxo Platform forwards the response back to the Miniapp server.
The Miniapp server processes the response and takes appropriate actions.
Alternatively, the process can start with the host app creating an event:
The Host app creates an event for a specific miniapp.
The Host app server sends the event to the Boxo Platform.
The Boxo Platform forwards the event to the Miniapp server.
The Miniapp server processes the event and returns a response.
The Boxo Platform forwards the response back to the Host app server.
Note: Feature must be enabled in Dashboard Partnership
Data format The Boxo platform uses JSON format for data exchange. Event payloads can contain any valid JSON structure that follows the agreed-upon schema between the miniapp and host app.
This endpoint is on the Boxo platform. Send a request to deliver an event to a host app.
URL and METHOD:
This is HTTPS POST /api/v1/event-bridge/miniapp/
endpoint
IP address of requesting services must be provided in Dashboard for whitelisting or Request Signaturing must be enabled
Headers
Key | Value |
---|---|
Content-type | application/json |
Body:
Field | Data type | Optional | Description |
---|---|---|---|
app_id | String | No | Miniapp identifier |
client_id | String | No | Hostapp identifier |
event_type | String | No | Type of event (e.g., “order_created”) |
payload | Object | No | Event data in JSON format |
Response:
Response status will be 400
in case there is error_code
Response body: The response body will contain the host app’s response to the event, or an error message if delivery failed.
Field | Data type | Optional | Description |
---|---|---|---|
error_code | String | Yes | Error code if event delivery failed |
error_message | String | Yes | Detailed error message |
… | … | … | Additional fields from host app response |
Request Example:
Response Example:
Success response (containing host app’s response):
Error response:
Set up this endpoint to receive events from host apps through the Boxo platform.
URL and METHOD: This endpoint must handle a HTTPS POST request URL to endpoint must be provided in Dashboard
Headers:
Key | Value |
---|---|
Authorization | Basic <base64 encoded(app_id:secret_key)> |
Content-type | application/json |
app_id
and secret_key
will be provided in Dashboard
Body:
Field | Data type | Description |
---|---|---|
app_id | String | Miniapp identifier |
client_id | String | Hostapp identifier |
event_type | String | Type of event (e.g., “user_updated”) |
payload | Object | Event data in JSON format |
Response:
Response status must be 200
in all cases
Response body can contain any valid JSON that will be forwarded to the host app
Request Example:
Response Example:
Here are some common event types that can be used for communication between miniapps and host apps:
Event Type | Description | Example Payload |
---|---|---|
order_created | A new order has been created in the miniapp | {"order_id": "ord_123", "amount": 50.25} |
product_viewed | User has viewed a product in the miniapp | {"product_id": "prod_123", "category": "shoes"} |
cart_updated | User’s shopping cart has been updated | {"cart_id": "cart_123", "item_count": 3} |
content_shared | User has shared content from the miniapp | {"content_id": "cont_123", "content_type": "image"} |
checkout_started | User has initiated the checkout process | {"cart_id": "cart_123", "amount": 75.00} |
Event Type | Description | Example Payload |
---|---|---|
user_profile_updated | User profile information has been updated | {"user_id": "123", "updated_fields": ["email"]} |
location_updated | User’s location has been updated | {"latitude": 37.7749, "longitude": -122.4194} |
app_state_change | The state of the host app has changed | {"new_state": "background", "timestamp": 123456} |
language_changed | User has changed their language preference | {"language_code": "es", "locale": "es_MX"} |
theme_changed | User has changed their theme preference | {"theme": "dark", "color_scheme": "blue"} |
If an error occurs during event processing, the Boxo Platform will return an appropriate error response:
Error Code | Description |
---|---|
EVENT_RECEIVER_DISABLED | Event receiver is not enabled for the host app |
INVALID_EVENT_DATA | The event data format is invalid |
EVENT_DELIVERY_FAILED | Failed to deliver the event to the host app |
UNAUTHORIZED | Miniapp is not authorized to send events |
INTEGRATION_DISABLED | Event bridge is not enabled for this integration |
For client-side event handling in your miniapp, you can use the Boxo JS SDK:
By utilizing the Boxo Event Bridge, your miniapp can create seamless integrations with host apps, improving user experience and enabling more advanced functionality through real-time communication.