​
Handle custom event from miniapp.

The custom events system is a powerful feature that enables bidirectional data communication between a miniapp and the host app. The miniapp can send data that the host app can recognize. Additionally, certain operations can be implemented at the native app level for enhanced functionality.

​
Examples

Calling custom event from miniapp: 
appboxo.send('AppBoxoWebAppCustomEvent', {
  type: 'any_string_identifier',  // Any string identifier to be handled by host app
  payload: {                      // Any payload data to be send to host app
    // Your data
  }
})
Calling custom event from miniapp with promise: 

const dataDTO = {
  type: 'custom_event_type', // custom event type
  payload: {data: 'data'}, // your data
}

appboxo.sendPromise('AppBoxoWebAppCustomEvent', dataDTO)
  .then(() => console.log('success'))  // success callback
  .catch(() => console.log('rejected'))  // reject callback
Receiving custom event sent from host app: 
appboxo.subscribe(event => {
  if (!event.detail) {
    return;
  }

  const { type, data } = event.detail;

  if (type === 'AppBoxoWebAppCustomEvent') {
    // Reading result of the Code Reader
    console.log(data.type);       // Custom event string identifier
    console.log(data.payload);    // Payload data
  }
});

​
Boxo Event Bridge

​
Introduction

Boxo Event Bridge is a bidirectional communication functionality that enables host apps and miniapps to exchange events and information seamlessly within the Boxo ecosystem.

​
Event Bridge flow

Here is a sequence flow for event communication process between a miniapp and a host app.
  1. An app (either hostapp or miniapp) creates an event with a specific event type and payload
  2. The app sends the event to the Boxo Platform via the Event Bridge API
  3. The Boxo Platform validates the event and authenticates the sender
  4. The Boxo Platform forwards the event to the recipient’s event receiver URL
  5. The recipient processes the event and returns a response
  6. The Boxo Platform captures the response and forwards it to the original sender
  7. The original sender receives the response and can take appropriate actions

​
Setting up the backend

*Note: Feature must be enabled in Dashboard Data format JSON is used for data exchange. Event payloads can contain any valid JSON structure that both the sender and receiver agree upon.

​
1. “Event Receiver” Endpoint

This endpoint allows your app to receive events from the Boxo Platform. URL and METHOD: This endpoint must handle a HTTPS POST request URL to endpoint must be provided in Dashboard Headers:
KeyValue
Authorization<prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)>
Content-typeapplication/json
  • Default <prefix>: Token. Access token prefix can be set in Boxo Connect.
  • hostapp_client_id and hostapp_secret_key must be provided in Dashboard
Body
FieldData typeDescription
app_idStringMiniapp identifier
client_idStringHostapp identifier
event_typeStringEvent type identifying the purpose of the event
payloadObjectEvent data containing information specific to the event
Response:
  • Response status must be 200 in all cases
  • Response body can contain any valid JSON that will be forwarded to the event sender
Request Example: 
curl --location --request POST '[YOUR_SERVER_URL]/api/event-receiver/'\
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{BASE64_ENCODED_CLIENT_ID_AND_CLIENT_SECRET}}' \
--data-raw '{
    "app_id": "{{MINIAPP_ID}}",
    "client_id": "{{CLIENT_ID}}",
    "event_type": "user_profile_updated",
    "payload": {
        "user_id": "user123",
        "name": "John Doe",
        "email": "john@example.com"
    }
}'

​
2. Sending Events API

This endpoint allows your app to send events to miniapps through the Boxo Platform. URL and METHOD This is HTTPS POST /api/v1/event-bridge/hostapp/ endpoint Headers
KeyValue
Authorization<prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)>
Content-typeapplication/json
  • Default <prefix>: Token. Access token prefix can be set in Boxo Connect.
  • hostapp_client_id and hostapp_secret_key must be provided in Dashboard
Body
FieldData typeDescription
app_idStringMiniapp identifier (recipient)
client_idStringHostapp identifier (sender)
event_typeStringEvent type identifying the purpose of the event
payloadObjectEvent data containing information specific to the event
Response
  • Response status will be 200 if the event was delivered successfully
  • Response body will contain the response from the miniapp’s event receiver endpoint
Request Example 
curl --location --request POST 'https://api.boxo.io/api/v1/event-bridge/hostapp/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{BASE64_ENCODED_CLIENT_ID_AND_CLIENT_SECRET}}' \
--data-raw '{
    "app_id": "{{MINIAPP_ID}}",
    "client_id": "{{CLIENT_ID}}",
    "event_type": "payment_completed",
    "payload": {
        "transaction_id": "tx_12345",
        "amount": 100.50,
        "currency": "USD",
        "status": "completed"
    }
}'

​
Common Event Types

Here are some common event types that can be used for communication between host apps and miniapps:

​
Host App to Miniapp Events

Event TypeDescriptionExample Payload
user_profile_updatedUser profile information has been updated{"user_reference": "123", "email": "example@example.com"}

​
Miniapp to Host App Events

Event TypeDescriptionExample Payload
order_status_updateMiniapp order fulfillment status{"order_payment_id": "order_123", "fulfillment_status": "delivering"}

​
Error Handling

If an error occurs during event processing, the Boxo Platform will return an appropriate error response:
Error CodeDescription
EVENT_RECEIVER_DISABLEDEvent receiver is not enabled for the recipient
INVALID_EVENT_DATAThe event data format is invalid
EVENT_DELIVERY_FAILEDFailed to deliver the event to the recipient
UNAUTHORIZEDSender is not authorized to send events

​
Best Practices

  1. Event Types: Use consistent event types that clearly indicate the purpose of the event
  2. Minimal Payloads: Keep event payloads as small as possible, including only necessary information
  3. Error Handling: Implement proper error handling for event processing failures
  4. Idempotency: Design event handlers to be idempotent to handle potential duplicate events
  5. Timeouts: Implement reasonable timeouts for event processing to avoid blocking operations
By following these guidelines, you can create a robust event-driven communication system between your host app and miniapps using Boxo Event Bridge.