1. User opens host app and launches miniapp: The user initiates the miniapp from within the host app.
2. User proceeds with miniapp flow: The user navigates through the miniapp as intended.
3. User selects products and clicks on BUY: The user chooses items and confirms their purchase.
4. Miniapp sends custom event with product details, order, and amount: The miniapp sends the order details, including the products and total amount, through a custom event.
5. Host app receives custom event and shows a confirmation screen for purchase: The host app processes the custom event and displays a purchase confirmation screen on top of the active miniapp.
6. Host app performs purchasing operation and sends back a custom event to the miniapp: The host app completes the purchase and sends a custom event back to the miniapp, containing either transaction details and a success message or a failure message.
7. Miniapp receives the custom event and shows confirmation/failure screen: The miniapp processes the response and displays either a success or failure screen based on the transaction outcome.
8. If the transaction is successful, the miniapp saves the transaction details: For future reference and monthly reconciliation, the miniapp saves the successful transaction details.

​

Examples

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
  }
})

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

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

​

Event Bridge flow

1. The Miniapp creates an event with a specific event type and payload.
2. The Miniapp server sends the event to the Boxo Platform through the Event Bridge API.
3. The Boxo Platform validates the event and forwards it to the Host app server.
4. The Host app server processes the event and returns a response to the Boxo Platform.
5. The Boxo Platform forwards the response back to the Miniapp server.
6. The Miniapp server processes the response and takes appropriate actions.

1. The Host app creates an event for a specific miniapp.
2. The Host app server sends the event to the Boxo Platform.
3. The Boxo Platform forwards the event to the Miniapp server.
4. The Miniapp server processes the event and returns a response.
5. The Boxo Platform forwards the response back to the Host app server.

​

Setting up the backend

​

1. “Send Event” Request

• 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.

curl --location --request POST '[BOXO_PLATFORM_SERVER_URL]/api/v1/event-bridge/miniapp/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "app_id": "{{MINIAPP_ID}}",
    "client_id": "{{CLIENT_ID}}",
    "event_type": "order_created",
    "payload": {
        "order_id": "ord_12345",
        "amount": 100.50,
        "currency": "USD",
        "items": [
            {
                "product_id": "prod_123",
                "quantity": 2,
                "price": 50.25
            }
        ]
    }
}'

{
    "status": "received",
    "message": "Event processed successfully",
    "reference_id": "evt_987654"
}

{
    "error_code": "EVENT_RECEIVER_DISABLED",
    "error_message": "Event receiver is not enabled for the specified host app"
}

​

2. “Event Receiver” Endpoint

• We suggest whitelisting Boxo platform IP addresses for this endpoint.

• Response status must be 200 in all cases
• Response body can contain any valid JSON that will be forwarded to the host app

curl --location --request POST '[YOUR_SERVER_URL]/api/event-receiver/' \
--header 'Authorization: Basic {{BASE64_ENCODED_APP_ID_AND_SECRET_KEY}}' \
--header 'Content-Type: application/json' \
--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"
    }
}'

{
    "status": "processed",
    "message": "User profile update acknowledged"
}

​

Common Event Types

​

Miniapp to Host App Events

​

Host App to Miniapp Events

​

Error Handling

​

Best Practices

1. Event Types: Use descriptive event types that clearly communicate the purpose of the event
2. Efficient Payloads: Keep event payloads as small as possible while including all necessary information
3. Error Handling: Implement proper error handling for event failures and retry mechanisms where appropriate
4. Idempotency: Design event handlers to be idempotent to handle potential duplicate events
5. Event Documentation: Document all event types and their expected payloads for better integration with host apps
6. Response Times: Process events quickly and respond within reasonable timeframes to avoid timeouts
7. Validation: Validate incoming events before processing to ensure data integrity

​

SDK Integration

// Listen for events from the host app
appboxoSdk.on('hostAppEvent', (eventData) => {
  const { eventType, payload } = eventData;
  
  // Handle different event types
  switch (eventType) {
    case 'user_profile_updated':
      updateUserProfile(payload);
      break;
    case 'location_updated':
      updateUserLocation(payload);
      break;
    // Handle other event types
    default:
      console.log('Received unknown event:', eventType);
  }
});

// Send events to the host app
appboxoSdk.sendEvent({
  eventType: 'order_created',
  payload: {
    orderId: 'ord_12345',
    amount: 100.50,
    currency: 'USD'
  }
}).then((response) => {
  console.log('Event sent successfully:', response);
}).catch((error) => {
  console.error('Failed to send event:', error);
});