# API Reference
Source: https://boxo.mintlify.app/MiniApp API Reference/APIReference



## Miniapp initialization

### `AppBoxoWebAppInit`

An event to notify host app about miniapp's initialization

### `AppBoxoWebAppGetInitData`

Gets init data from host app

**Returns an object with:**

* ` app_id` Miniapp ID
* ` client_id` Host client ID
* ` payload` String consisting of encrypted user details
* ` data {[key: string]: any}` null custom data passed from Hostapp
* ` token` *optional* User session token if it is still active

<Check> **TIP** There is a shortcut `.getInitData()` that handles saving details above in cookies or localStorage and returns a Promise. </Check>

## Miniapp manipulation

### `AppBoxoWebAppOpenMiniApp`

Opens other miniapp based on provided application ID

**Parameters**

* `app_id` *required* Miniapp ID to open

### `AppBoxoWebAppCloseMiniApp`

Close current active miniapp

### `AppBoxoWebAppOnRestore`

Event that is fired when miniapp is restored.

Example:

```js theme={"system"}
appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type } = event.detail

  if (type === 'AppBoxoWebAppOnRestore') {
    // Miniapp restored
  }
})
```

## Authentication

### `AppBoxoWebAppLogin`

Login user using credentials given from host app

Example:

```js theme={"system"}
const login = async (data) => {
  const response = await appboxo.sendPromise('AppBoxoWebAppLogin', data)
  // Returns http response
  console.log(response)
}
```

<Check> **TIP** There is a shortcut that you can use: </Check>

```js theme={"system"}
appboxo.login(data).then(response => {
   console.log(response)
 }).catch(error => {
   console.log(error)
 })
```

### `AppBoxoWebAppLogout`

Logout and clear session token

Example:

```js theme={"system"}
const logout = async (data) => {
  await appboxo.sendPromise('AppBoxoWebAppLogout')
}
```

<Check> **TIP** There is a shortcut that you can use: </Check>

```js theme={"system"}
 appboxo.logout().then(() => {
   // logged out
 }).catch(error => {
   console.log(error)
})
```

### `AppBoxoWebAppClearToken`

Clears saved token in host app

### `AppBoxoWebAppSaveToken`

Saves provided token in host app

**Parameters**

* `token` *required* Token to save in host app

## Appboxo Pay

<Warning> **WARNING**
This event is available from version 1.3.13 and above </Warning>

### `AppBoxoWebAppPay`

Send payment event to host app

orderPaymentId:string, amount: number, orderId: string, currency: string, extraParams?: any

**Parameters**

* `orderPaymentId` *required* `string` Order payment identifier
* `miniappOrderId` *required* `number` Unique identifier for the current payment
* `amount` *required* `boolean` Payment amount
* `currency` *required* `string` Define currency code
* `extraParams` : `any` Any extra data

Example:

```js theme={"system"}
appboxoSdk.send('AppBoxoWebAppPay', {
  orderPaymentId: "xxx",
  amount: 199.00,
  miniappOrderId: "TM121248847",
  currency: "USD",
  extraParams: {}
})
```

To receive the result of the payment event, just subscribe to the same event. Host app will sending these as the response:

**Parameters**

* `orderPaymentId` : `string` Order payment identifier
* `miniappOrderId`: `number` Unique identifier for the current payment
* `hostappOrderId` : `number` Unique identifier from hostapp
* `amount` : `boolean` Payment amount
* `currency` : `string` Define currency code
* `status` : `string` Status of the payment
* `extraParams` : `any` Any extra data

Example:

```js theme={"system"}
const appboxoPaymentStatusHandler = (event) => {
  if (!event.detail) {
    return;
  }

  const { type, data } = event.detail;

  if (type === 'AppBoxoWebAppPay') {
    setResponse(data.status)
  }
}
```

## Tab bar

### `AppBoxoWebAppSetTabBar`

Initialized native tab bar component

**Parameters**

* `show` required `boolean` Defines TabBar visibility
* `activeTab` required `number` Active TabBar item id
* `list` required `Array<{ tabId: number, tabName: string, tabIcon: string }> Define tabs`
* `options` required `{ color: string, background: string, selectedColor: string, hasBorder: boolean, borderColor: string }` Tab bar options
* `badges` optional `Array<{ tabId: number, background: string, color: string, value?: string }>` Define tab item badges.

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetTabBar', {
  show: true,
  activeTab: 1,
  list: [
    {
      tabId: 1,
      tabName: 'Home',
      tabIcon: ICON_URL
    },
    {
      tabId: 2,
      tabName: 'About',
      tabIcon: ICON_URL
    },
    {
      tabId: 3,
      tabName: 'Services',
      tabIcon: ICON_URL
    }
  ],
  badges: [
    {
      tabId: 1,
      background: '#ff0000',
      color: '#ffffff',
      value: '4'
    },
    {
      tabId: 3,
      background: '#ff0000',
      color: '#ffffff',
      value: '1'
    }
  ],
  options: {
    color: '#aaaaaa',
    background: '#ffffff',
    selectedColor: '#2eb8da',
    hasBorder: true,
    borderColor: '#dddddd'
  }
})
```

Sending event with only required changes will preserve initial options:

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetTabBar', {
  activeTab: 2
})
```

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetTabBar', {
  options: {
    color: '#ffffff',
    background: '#000000',
    selectedColor: '#2eb8da',
    hasBorder: false
  }
})
```

### `AppBoxoWebAppTabBarItemClick`

Event that should be subscribed to in order to get active tab item click

Example:

```js theme={"system"}
appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type, data } = event.detail

  if (type === 'AppBoxoWebAppTabBarItemClick') {
    if (data.tabId) {
      // Active tab id received
    }
  }
})
```

## Navigation bar

### `AppBoxoWebAppSetNavigationBar`

Activates native navigation bar.

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetNavigationBar', {
  title: 'Light nav bar',     // Navigation bar title
  backButton: true,           // Controls back button visibility
  background: '#ffffff',      // Navigation bar background color
  frontColor: '#000000',      // Navigation bar and status bar accent color
  show: true                  // Controls navigation bar visibility,
  isBackgroundTransparent: true,        // When set to true, will make background transparent
  frontColorWhenTransparent: '#ffffff', // Navigation bar and status bar accent color when navigation has transparent background
  changeBackgroundOnScroll: true        // Will smoothly change backgroound from transparent to `background` color on scroll
})
```

Sending event with only required changes will preserve initial options:

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetNavigationBar', {
  title: 'Changed some time later'
})
```

## Action buttons

### `AppBoxoWebAppSetActionButton`

Changes actions button theme. By default it is dark.

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetActionButton', {
  isLight: true
})
```

## Loading indicator

### `AppBoxoWebAppLoadingIndicator`

Show native loading indicator.

**Important:** Loading indicator will timeout after 30 seconds with prompt to hide it if no event is dispatched to change it.

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppLoadingIndicator', {
  show: true
})
```

## QR code reader

### `AppBoxoWebAppOpenQRCodeReader`

Opens native QR code reader.

*This method will prompt a permission request for camera.*

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppOpenQRCodeReader');
```

Results from QR code reader are received by events: `AppBoxoWebAppOpenQRCodeReaderResult` or `AppBoxoWebAppOpenQRCodeReaderFailed`

Example:

```js theme={"system"}
// Subscribe to events to receive data
appboxo.subscribe(event => {
  if (!event.detail) {
    return;
  }

  const { type, data } = event.detail;

  if (type === 'AppBoxoWebAppOpenQRCodeReaderResult') {
    // Reading result of the QR Code Reader
    console.log(data.code_data);
  }

  if (type === 'AppBoxoWebAppOpenQRCodeReaderFailed') {
    // Catching the error
    console.log(data.error_type, data.error_data);
  }
});
```

## Haptic feedback

### `AppBoxoWebAppVibrate`

Triggers haptic engine on the device, if available.

**Parameters**

* `style` optional `'light' | 'medium' | 'heavy'` Controls strength of vibration, defaults to 'light'.
  Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppVibrate', {
  style: 'medium'
})
```

## Action sheet

### `AppBoxoWebAppShowActionSheet`

Shows native action sheet

**Parameters**

`header` *optional* `string` Action sheet header text
`list` *required* `Array<{ id: number, text: string, role?: 'cancel' | 'destructive' | 'selected' }>` Define action sheet items
Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppShowActionSheet', {
  header: 'Albums',
  list: [
    {
      id: 1,
      text: 'Delete',
      role:'destructive'
    },
    {
      id: 2,
      text: 'Selected',
      role:'selected'
    },
    {
      id: 3,
      text: 'Share',
    },
    {
      id: 4,
      text: 'Play',
    },
    {
      id: 5,
      text: 'Cancel',
      role: 'cancel'
    }
  ]
})
```

### `AppBoxoWebAppActionSheetItemClick`

Event that should be subscribed to in order to get action sheet item click

Example:

```js theme={"system"}
appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type, data } = event.detail

  if (type === 'AppBoxoWebAppActionSheetItemClick') {
    if (data.id) {
      // Action sheet item id received
    }
  }
})
```

## Geolocation

### `AppBoxoWebAppGetGeodata`

Requests user geodata.

*This method will prompt a permission request to access geolocation.*

Example:

```js theme={"system"}
const getGeodata = async () => {
  const data = await appboxo.sendPromise('AppBoxoWebAppGetGeodata');

  return {
    isAvailable: !!data.available,
    lat: parseFloat(data.lat),
    long: parseFloat(data.long)
  };
};
```

## Map

### `AppBoxoWebAppChooseLocation`

Open full screen map to choose location

*This method will prompt a permission request to access geolocation.*

Example:

```js theme={"system"}
const chooseLocation = async () => {
  const data = await appboxo.sendPromise('AppBoxoWebAppChooseLocation');

  return {
    latitude: parseFloat(data.latitude),
    longitude: parseFloat(data.longitude)
  };
};
```

### `AppBoxoWebAppOpenLocation`

Open full screen map to that shows markered location

*This method will prompt a permission request to access geolocation.*

Example:

```js theme={"system"}
const openLocation = async () => {
  const data = await appboxo.sendPromise('AppBoxoWebAppOpenLocation', {
    latitude: 42.5264986,
    longitude: 74.5788997,
    scale: 13
  });

  console.log(data)

  // Returns:
  // {
  //   result: true
  // }
};
```

## Alert

### `AppBoxoWebAppShowAlert`

Show native alert box

**Parameters**

`header` *optional* `string` Alert header text
`message` *optional* `string` Alert message
`buttons` *required* ` Array<{ id: number, text: string, role?: 'cancel' | 'destructive' }>` Define buttons

Example:

```js theme={"system"}
const showAlert = async () => {
  const data = await appboxo.sendPromise('AppBoxoWebAppShowAlert', {
    header: 'Native alert',
    message: 'This is a native alert box.',
    buttons: [
      {
        id: 1,
        text: 'Cancel',
        role:'destructive'
      },
      {
        id: 2,
        text: 'Ok'
      }
    ]
  });

  // Selected button
  const selectedButton = data.id
};
```

## Image gallery

### `AppBoxoWebAppShowImages`

Open full screen native image gallery

**Parameters**

`start_index` *optional* `number` Index to start showing from
`images` *required* `Array<string>` Image urls
Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppShowImages', {
  images: [
    // image urls
  ]
});
```

After image gallery is closed, same event will be dispatched back to miniapp with result data.

Example:

```js theme={"system"}
appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type, data } = event.detail

  if (type === 'AppBoxoWebAppShowImages') {
    if (data.result) {
      // Image gallery has been shown successfully
    } else {
      // There were problems loading provided images
    }
  }
})
```

## Storage

### `AppBoxoWebAppStorageGet`

Requests a value from the storage

**Parameters**

`keys` *required* `Array<string>` Keys for getting (\[a-zA-Z\_-0-9])

Example:

```js theme={"system"}
const getUserData = async () => {
  const userData = await appboxo.sendPromise('AppBoxoWebAppStorageGet', {
    keys: ['username', 'email']
  });

  console.log(userData)

  // Returns:
  // {
  //   keys: [
  //     {
  //       key: 'username',
  //       value: 'John'
  //     },
  //     {
  //       key: 'email',
  //       value: 'john@doe.com'
  //     }
  //   ]
  // }
};
```

### `AppBoxoWebAppStorageGetKeys`

Request list of keys of some stored values

**Parameters**

`count` *required* `number` Count of keys to get. Max value is 1000
`offset` *optional* `number` The offset required to fetch a specific subset of keys. Default: 0

Example:

```js theme={"system"}
const getStorageKeys = async () => {
  const storageKeys = await appboxo.sendPromise('AppBoxoWebAppStorageGetKeys', {
    count: 10
  });

  console.log(storageKeys);

  // Returns:
  // {
  //   keys: ['username', 'email']
  // }
};
```

### `AppBoxoWebAppStorageSet`

Stores value in storage

Parameters

`key` *required* `string` The key of value (\[a-zA-Z\_-0-9])
`value` *optional* `string` value

Example:

```js theme={"system"}
const saveData = async ({ key, value }) => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStorageSet', {
    key,
    value
  });

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppStorageRemove`

Removes value in storage

**Parameters**

`key` *required* `string` The key of value (\[a-zA-Z\_-0-9])

Example:

```js theme={"system"}
const removeData = async ({ key }) => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStorageRemove', { key });

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppStorageClear`

Clears all data in storage

Example:

```js theme={"system"}
const clearStorage = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStorageClear');

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

## Clipboard

### `AppBoxoWebAppGetClipboard`

Gets the content on the system clipboard.

Example:

```js theme={"system"}
const getClipboard = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppGetClipboard');

  console.log(response);

  // Returns:
  // {
  //   data: 'from clipboard or null'
  // }
};
```

### `AppBoxoWebAppSetClipboard`

Sets the content on the system clipboard.

Parameters

`data` *required* `string` Content to be copied to clipboard

Example:

```js theme={"system"}
const setClipboard = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppSetClipboard', {
    data: 'copied to clipboard'
  });

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

## System information

### `AppBoxoWebAppGetSystemInfo`

Gets system information.

Example:

```js theme={"system"}
const getSystemInfo = async () => {
  const systemInfo = await appboxo.sendPromise('AppBoxoWebAppGetSystemInfo');

  console.log(systemInfo);

  // Returns:
  // {
  //   brand: 'Apple Inc.',
  //   model: 'iPhone 7 Plus',
  //   pixelRatio: 3,
  //   screenWidth: 414,
  //   screenHeight: 736,
  //   windowWidth: 414,
  //   windowHeight: 672,
  //   statusBarHeight: 20,
  //   system: 'iOS 10.0.1',
  //   platform: 'iOS / iPhone OS',
  //   SDKVersion: 1.0.4,
  //   cameraAuthorized: true,
  //   locationAuthorized: false,
  //   locationEnabled: false,
  // }

};
```

## Accelerometer

### `AppBoxoWebAppStartAccelerometer`

Starts listening on acceleration data.

Example:

```js theme={"system"}
const startAccelerometer = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStartAccelerometer', {
    interval: 200 // Update interval in ms
  });

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppStopAccelerometer`

Stops listening on acceleration data.

Example:

```js theme={"system"}
const stopAccelerometer = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStopAccelerometer');

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppOnAccelerometerChange`

Listens on the acceleration data event. You can send AppBoxoWebAppStopAccelerometer event to stop listening.

Example:

```js theme={"system"}
appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type, data } = event.detail

  if (type === 'AppBoxoWebAppOnAccelerometerChange') {
    console.log(data.x)
    console.log(data.y)
    console.log(data.z)
  }
})
```

## Gyroscope

### `AppBoxoWebAppStartGyroscope`

Starts listening on gyroscope data.

Example:

```js theme={"system"}
const startAccelerometer = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStartGyroscope', {
    interval: 200 // Update interval in ms
  })

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppStopGyroscope`

Stops listening on gyroscope data.

Example:

```js theme={"system"}
const stopAccelerometer = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStopGyroscope');

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppOnGyroscopeChange`

Listens on the gyroscope data event. You can send AppBoxoWebAppStopGyroscope event to stop listening.

Example:

```js theme={"system"}
appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type, data } = event.detail

  if (type === 'AppBoxoWebAppOnGyroscopeChange') {
    console.log(data.x)
    console.log(data.y)
    console.log(data.z)
  }
})
```

## Compass

### `AppBoxoWebAppStartCompass`

Starts listening on compass data.

Example:

```js theme={"system"}
const startCompass = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStartCompass')

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppStopCompass`

Stops listening on compass data.

Example:

```js theme={"system"}
const stopCompass = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStopCompass');

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppOnCompassChange`

Listens on the compass data event. You can send AppBoxoWebAppStopCompass event to stop listening.

Example:

```js theme={"system"}
appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type, data } = event.detail

  if (type === 'AppBoxoWebAppOnCompassChange') {
    console.log(data.direction)
  }
})
```

## Background color

### `AppBoxoWebAppSetBackgroundColor`

Dynamically sets the background color of the window.

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetBackgroundColor', {
  color: '#ff0000'
});
```

## Status bar color

### `AppBoxoWebAppSetStatusBarColor`

Dynamically sets the status bar color

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetStatusBarColor', {
  color: '#ffffff'
})
```

## Tracking

### `AppBoxoWebAppTrack`

Send postback tracking data about transaction

Example:

```js theme={"system"}
const sendTransactionData = async (data) => {
  const response = await appboxo.sendPromise('AppBoxoWebAppTrack', data)
  // Returns http response
  console.log(response)
}

sendTransactionData({
  action: 'transaction',
  payload: {
    shipping: 5,
    tax: 0.57,
    discount: 2.25,
    currency_code: 'USD',
    customer: { // Optional
      first_name: 'John',
      last_name: 'Doe',
      email: 'jdoe@domain.com',
      ip_address: '234.192.4.75'
    },
    items: [
      {
        name: 'Product name',
        description: 'Product description',
        price: 8.80,
        amount: 2,
        total: 17.6,
        package_id: 1232
      }
    ]
  }
})
```

<Check> **TIP** There is a shortcut that you can use to send tracking data: </Check>

```js theme={"system"}
appboxo.track(data).then(response => {
  console.log(response)
}).catch(error => {
  console.log(error)
})
```

## Custom events

### `AppBoxoWebAppCustomEvent`

Send custom event to host app.

Example:

```js theme={"system"}
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
  }
})
```

## Download file

### `AppBoxoWebAppDownloadFile`

Send event to download file

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppDownloadFile', {
  url: 'url',  
  file_name: 'filename.png'
})
```

## Share text and file

### `AppBoxoWebAppShare`

Send event to open native share modal

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppShare', {
  text: 'text',   
  url: 'url',  
  file_name: 'filename.png'
})
```


# Authentication API Reference
Source: https://boxo.mintlify.app/MiniApp API Reference/AuthenticationAPIRef



### `appboxo.login(optionalProps)`

Sends a message to native client to open confirm modal with default confirmation message. Upon confirmation it sends request to platform and returns resolved authentication token promise to miniapp.

**Parameters**

* `optionalProps` *optional* Props to extend default login behavior

**optionalProps**

* `postConfirmCallback` *optional* Callback that is being called after confirm modal resolves

**Example**

```js theme={"system"}
try {
  const {
    // token string
    token
  } = await appboxo.login({
    postConfirmCallback: (isConfirmed) => { console.log('Confirmation status: ', isConfirmed) }
  });
} catch (error) {
  // Handling an error
}
```

### `appboxo.logout()`

Sends a message to native client to clear authentication tokens.


# Events API Reference
Source: https://boxo.mintlify.app/MiniApp API Reference/EventsAPI



## `.sendPromise(method[, params])`

Sends a message to native client and returns the `Promise` object with response data

**Parameters**

`method` *required* The Boxo JS SDK method
`params` *optional* Message data object

**Example**

```js theme={"system"}
// Sending event to client
appboxo
  .sendPromise('AppBoxoWebAppGetInitData')
  .then(data => {
    // Handling received data
    console.log(data.email);
  })
  .catch(error => {
    // Handling an error
  });
```

You can also use imperative way

```js theme={"system"}
try {
  const data = await appboxo.sendPromise('AppBoxoWebAppGetInitData');

  // Handling received data
  console.log(data.email);
} catch (error) {
  // Handling an error
}
```

## `.send(method[, params])`

Sends a message to native client

**Parameters**

* `method` *required* The Boxo JS SDK method
* `params` *optional* Message data object

**Example**

```js theme={"system"}
// App initialization
appboxo.send('AppBoxoWebAppInit');

// Opening images
appboxo.send('AppBoxoWebAppShowImages', {
  images: [
    "https://pp.userapi.com/c639229/v639229113/31b31/KLVUrSZwAM4.jpg",
    "https://pp.userapi.com/c639229/v639229113/31b94/mWQwkgDjav0.jpg",
    "https://pp.userapi.com/c639229/v639229113/31b3a/Lw2it6bdISc.jpg"
  ]
})
```

## `.subscribe(fn)`

Subscribes a function to events listening

**Parameters**

`fn` *required* Function to be subscribed to events

**Example**

```js theme={"system"}
// Subscribing to receiving events
appboxo.subscribe(event => {
  if (!event.detail) {
    return;
  }

  const { type, data } = event.detail;

  if (type === 'AppBoxoWebAppOpenQRCodeReaderResult') {
    // Reading result of the Code Reader
    console.log(data.code_data);
  }

  if (type === 'AppBoxoWebAppOpenQRCodeReaderFailed') {
    // Catching the error
    console.log(data.error_type, data.error_data);
  }
});

// Sending method
appboxo.send('AppBoxoWebAppOpenQRCodeReader', {});
```

## `.unsubscribe(fn)`

Unsubscribes a function from events listening

**Parameters**

* \`\`\`fn\`\` *required* Event subscribed function

**Example**

```js theme={"system"}
const fn = event => {
  // ...
};

// Subscribing
appboxo.subscribe(fn);

// Unsubscribing
appboxo.unsubscribe(fn);
```

## `.supports(method)`

Checks if an event is available on the current device

**Parameters**

* `method` *required* The Boxo JS SDK method

## `.isWebView()`

Returns `true` if Boxo JS SDK is running in mobile app, or `false` if not


# Android
Source: https://boxo.mintlify.app/changelog/android



## \[1.45.1] - 2026-07-29

* bump play-services-location to 21.3.0 and play-services-maps to 19.0.0

## \[1.45.0] - 2026-07-22

* scope miniapp theme (dark/light) to the miniapp without changing the host app theme

## \[1.44.0] - 2026-07-21

* fix crash when host app removes NFC or VIBRATE permission from merged manifest
* fix registerForActivityResult crash in QR scanner and map fragments

## \[1.43.1] - 2026-07-13

* fix window insets handling

## \[1.43.0] - 2026-06-12

* pass miniapp requiredFields to AuthListener.onAuth

## \[1.42.2] - 2026-06-04

* fix: saveState default logic

## \[1.42.1] - 2026-06-03

* add orderPaymentId field to PaymentData
* add lottie animation as a miniapp loader

## \[1.40.5] - 2026-05-07

* Add user interaction tracking
* enable background dimming for miniapps.

## \[1.40.4] - 2026-04-23

* fix background colors

## \[1.40.3] - 2026-04-20

* open miniapp as a dialog
* remove multitask mode

## \[1.39.1] - 2026-03-05

* fix getGeolocation result when FusedLocationProvider fails

## \[1.39.0] - 2026-02-26

* add support for dark and light splash screen colors

## \[1.38.0] - 2026-02-17

* make auth and location prompts configurable from miniapps

## \[1.37.1] - 2026-02-17

* fix crash on location request

## \[1.37.0] - 2026-01-30

* update session events
* add config for splash screen color
* fix status bar and logo position

## \[1.36.1] - 2026-01-26

* fix proguard rules

## \[1.36.0] - 2026-01-20

* update location permission pop-up
* support play-services-location and play-services-maps from version 17.0.0

## \[1.35.0] - 2025-11-26

* update default value for saveState
* add style\_5 for ActionButtons

## \[1.34.0] - 2025-11-18

* add esim direct install method

## \[1.33.2] - 2025-11-17

* add consent screen config

## \[1.33.1] - 2025-10-15

* rename clearLocalStorageKeysOnClose to noCacheLocalStorageKeys

## \[1.33.0] - 2025-10-15

* add config to clear localStorage keys on miniapp close

## \[1.32.2] - 2025-09-30

* add Accept-Language header to http requests

## \[1.32.1] - 2025-09-12

* merge AppBoxoAppShareBase64 with AppBoxoAppShare

## \[1.32.0] - 2025-09-11

* add share base64 file method

## \[1.31.0] - 2025-09-03

* add loading progress bar configs

## \[1.30.6] - 2025-08-27

* remove test dependencies

## \[1.30.5] - 2025-08-26

* fix auth bug
* fix statusbar and navigation bar

## \[1.30.4] - 2025-08-20

* fix crashes when changing the system theme

## \[1.30.3] - 2025-08-19

* fix status bar icons color for dark mode

## \[1.30.2] - 2025-08-13

* some fixes

## \[1.30.0] - 2025-08-07

* add setAuthTokens method

## \[1.29.0] - 2025-07-30

* support dark mode logo

## \[1.28.0] - 2025-07-18

* enable resizeable activity

## \[1.26.0] - 2025-06-02

* target SDK downgraded to 34 to resolve compatibility issues

## \[1.25.0] - 2025-05-27

* updated android target sdk to 35
* removed android.support dependencies; Jetifier is no longer required.

## \[1.24.0] - 2025-05-21

* fix custom action button for style
* add RESOURCE\_PROTECTED\_MEDIA\_ID permission to WebView

## \[1.23.0] - 2025-04-10

* rename Appboxo to Boxo
* improve whitelisted url validation ( 'www' subdomain check)

## \[1.22.0] - 2025-04-09

* add new style for actionButtons (style\_4)
* improve launch animations
* fix sensor events

## \[1.21.0] - 2025-04-03

* add launch UI animations
* change loader animation
* improve session analytics
* show error message with code only for sandbox

## \[1.20.1] - 2025-03-25

* proguard rules

## \[1.20.0] - 2025-03-24

* add page animation to miniapp config

## \[1.19.0] - 2025-03-12

* add events for native pullToRefresh

## \[1.18.0] - 2025-03-10

* add close button to error page
* update some ui elements

## \[1.17.0] - 2025-02-26

* add camera to file picker if mime type is image/\*
* fix AppBoxoWebAppStorageGet result
* update text on qr scanner

## \[1.16.2] - 2025-02-19

* fix status and navigation bars

## \[1.16.1] - 2025-02-18

* fix screen size with bottom navigation bar

## \[1.16.0] - 2025-02-17

* Screen move up with keyboard
* Consent screen for landscape mode
* fix open location

## \[1.15.0] - 2025-02-13

* Add list of user fields to consent screen

## \[1.14.0] - 2025-01-07

* Fix problem with cookies and storage on logout

## \[1.13.0] - 2024-12-16

* LTR/RTL support by language

## \[1.12.1] - 2024-11-21

* fix open\_miniapp\_duration on reload

## \[1.12.0] - 2024-11-18

* new action button style (style\_3)

## \[1.11.2] - 2024-11-05

* change action buttons color for dark theme

## \[1.11.1] - 2024-11-01

* fix crash on loading dialog
* show internet error only for main frame

## \[1.11.0] - 2024-10-25

* no internet connection page
* open\_miniapp\_duration to GetInitData

## \[1.10.0] - 2024-10-21

* add maintenance mode

## \[1.9.0] - 2024-10-18

* add support eSim flag to AppBoxoWebAppGetSystemInfo

## \[1.8.3] - 2024-10-18

* reload after clear cache

## \[1.8.2] - 2024-10-16

* change miniapp settings expiration time to 60sec by default

## \[1.8.1] - 2024-10-11

* add progressbar to share file
* more button icon for style\_2

## \[1.8.0] - 2024-10-10

* add config fields to OpenMiniapp from miniapp
* add new menu style (style\_2)

## \[1.7.0] - 2024-09-27

* add new menu style

## \[1.6.0] - 2024-09-25

* add showAboutPage flag to config
* add visible option to AppBoxoWebAppSetActionButton event
* fix open miniapp after closing miniapp

## \[1.5.21] - 2024-09-24

* system device hardware string

## \[1.5.20] - 2024-09-23

* remove http client cache

## \[1.5.19] - 2024-09-20

* AppBoxoWebAppShare to share file

## \[1.5.18] - 2024-09-13

* saveState flag to miniapp config

## \[1.5.17] - 2024-09-04

* Fix custom and payment event payload object's serialization

## \[1.5.16] - 2024-08-23

* Don't clear cache and localStorage on "Reload"

## \[1.5.15] - 2024-08-22

* AppBoxoWebAppDownloadFile to download file

## \[1.5.14] - 2024-08-22

* AppBoxoWebAppSetStatusBarColor to change status bar color

## \[1.5.13] - 2024-08-21

* clear cache and tokens when disabling User Data Sharing

## \[1.5.12] - 2024-08-20

* add language field to config to pass to miniapp
* add file download implementation
* save state when user close the miniapp

## \[1.5.11] - 2024-08-18

* set default empty video poster

## \[1.5.10] - 2024-08-15

* remove jcenter dependencies

## \[1.5.9] - 2024-08-12

* Sandbox mode

## \[1.5.8] - 2024-08-12

* Network timeouts

## \[1.5.7]

* close miniapp page on multitask mode

## \[1.5.6]

* consent t\&c, privacy text
* consent button color from hostapp colors

## \[1.5.4]

* updated Sentry endpoint

## \[1.5.3]

* add listeners to minapp opened from miniapp

## \[1.5.2]

* system info phone model to hardware codename

## \[1.5.1]

* enableSplash flag to miniapp configs
* fix close miniapp logic

## \[1.5.0]

* Consent Management
* Increase miniapp menu button size
* Changed icons

## \[1.4.14]

* fullscreen auth page
* url\_suffix
* default design for bottomsheet dialogs

## \[1.4.13] - 2021-12-09

* clear cache on reload
* disable forceDarkAllowed

## \[1.4.12] - 2021-11-15

* hide clear cache functionality

## \[1.4.11] - 2021-11-10

* appboxo logo

## \[1.4.10] - 2021-09-21

* remove the word "miniapp" from menu items
* clear cookies on clearCache

## \[1.4.9] - 2021-09-14

* onUserInteraction method to MiniappLifecycle
* clear localStorage on clearCache

## \[1.4.8] - 2021-08-26

* onActivityResult invoking from AppboxoActivity

## \[1.4.7] - 2021-08-06

* permissionsPage flag to config
* settings page moved to core

## \[1.4.6] - 2021-07-30

* isShopboxo flag moved to MiniappInfo
* crash on login

## \[1.4.5] - 2021-07-27

* onGeolocationPermissionsShowPrompt implementation

## \[1.4.4] - 2021-07-19

* Pull miniapp settings for active miniapp from platform every 30seconds and invalidate cache if it has changed

## \[1.4.3] - 2021-06-30

* custom url loading handler
* isShopboxo flag

## \[1.4.2] - 2021-06-18

* moves Payment to core module
* renamed BaseMiniapp to Miniapp

## \[1.4.1] - 2021-06-15

* added debug mode flag to Config for debugging webview
* added new auth flow
* added sandbox mode
* saving view states on changing screen orientation

## \[1.4.0] - 2021-05-26

* separated to light and full SDKs
* injecting script into miniapp that will come from platform
* support for android api 16
* proguard rules. --keepnames for all classes
* auto screen orientaion in LightSDK

## \[1.3.46] - 2021-05-13

* bug with similar miniapps in list

## \[1.3.45] - 2021-05-07

* hide 'install app' banner for Agoda

## \[1.3.44] - 2021-05-07

* support for android api 19

## \[1.3.43] - 2021-05-05

* "category" field to MiniappData

## \[1.3.42] - 2021-04-27

* getMiniapps() method (get approved miniapps)

## \[1.3.41] - 2021-04-21

* sets windowSoftInputMode "adjustResize"

## \[1.3.40] - 2021-04-12

* core version

## \[1.3.39] - 2021-03-16

* support multipleWindows mode for auth with socials
* switcher for appboxo branding, disable whitelisting url flags

## \[1.3.38] - 2021-03-02

* hash sum to analytics tracking request data
* disabled "about:blank"
* get browser\_fallback\_url from uri with scheme intent://

## \[1.3.37] - 2021-02-11

* removed params from getMiniapp method
* added new methods to Miniapp to setting auth payload, additional user data, custom data

## \[1.3.36] - 2021-01-29

* use "browser\_fallback\_url" from intent

## \[1.3.35] - 2021-01-27

* add extra url params on first launch

## \[1.3.34] - 2021-01-25

* json response with JSONObject
* crash on an incorrect app\_id with '/' symbol

## \[1.3.33] - 2020-12-23

* new method removeAllListeners()
* remove all listeners on close miniapp
* passing all listeners when miniapp opens another miniapp

## \[1.3.32] - 2020-12-07

* url change listener
* option to add third action menu
* extra query parameters to miniapp URL

## \[1.3.31] - 2020-11-17

* payment method

## \[1.3.30] - 2020-09-28

* http error handler
* fixed launch analytics

## \[1.3.29] - 2020-09-15

* closing all miniapps on logout
* renamed getMiniApp() to getMiniapp(), class MiniApp to Miniapp
* dark/light support

## \[1.3.28] - 2020-09-09

* changed text inside auth permission dialog

## \[1.3.27] - 2020-09-08

* single/multi-window support

## \[1.3.26] - 2020-09-04

* fixed initial action buttons theme
* fixed bug on click action buttons

## \[1.3.25] - 2020-08-26

* fixed clear cache

## \[1.3.24] - 2020-08-26

* fixed action buttons position
* fixed action buttons theme

## \[1.3.23] - 2020-08-26

* fixed reload miniapp

## \[1.3.22] - 2020-08-25

* floating action buttons

## \[1.3.21] - 2020-08-24

* removed internal modifier from MiniApp 'appId'
* miniapp error layout
* crash on load miniappsettings
* webView sound lags when app going background
* removed platform token from miniapp data

## \[1.3.20] - 2020-08-21

* additional user fields for auth in miniapps
* data field in miniapp from string to map
* don't show the login dialog again if it is already opened

## \[1.3.19] - 2020-08-07

* action button's style from miniapp settings

## \[1.3.18] - 2020-07-30

* miniapp lifecycle listener

## \[1.3.17] - 2020-07-24

* moved login action from jssdk
* moved transaction tracking from jssdk

## \[1.3.16] - 2020-07-07

* systemUiMode(light, dark) to system info
* language to system info
* error message when there is no integration
* Appboxo.hideAllMiniApps() method to minimizing all miniapp screens

## \[1.3.15] - 2020-07-01

* AppboxoActivity.doOnActivityResult(...) method

## \[1.3.14] - 2020-06-24

* miniapp settings caching
* pass "white\_label" field to miniapp settings
* file chooser support
* new methods Appboxo.getMiniApp(...) with params (authPayload - for auth, data - optional custom data to open miniapp).
* fixed bug on reload & clear cache
* Appboxo.createMiniApp(appId, payload)

## \[1.3.11] - 2020-06-11

* custom url schemes handler
* miniapp close animation
* fixed webview error handler
* fixed miniappSettings

## \[1.3.10] - 2020-05-29

* MiniApp config class with colors
* fade in to top effect when miniapps are switched
* onRestore method
* required fields from miniapp settings

## \[1.3.9] - 2020-05-22

* Miniapp settings
* Compass
* Instant miniapp reopening
* Background color of the window
* AppBoxoWebAppShowImages result callback return type
* Render NavBar only when miniapp is loaded

## \[1.3.7] - 2020-05-15

* Bottom context menu
* Status bar based on values from miniapp settings
* Accelerometer
* Gyroscope

## \[1.3.5] - 2020-05-08

* Landscape mode
* Open location
* Choose location
* Haptic Feedback duration
* NavigationBar title padding without icon


# Capacitor JS
Source: https://boxo.mintlify.app/changelog/capacitor



## \[0.15.0]

* bump native sdk versions (android 1.45.1, ios 1.29.0)

## \[0.14.0]

* add orderPaymentId field to Payment

## \[0.13.1]

* add lottie animation support for miniapp splash loading indicator

## \[0.12.0]

* remove multitask mode

## \[0.11.0]

* add splash screen configuration options
* fix sandbox mode

## \[0.10.0]

* saveState is false by default
* add style\_5 for ActionButtons
* \[android] add esim direct install
* update native sdk versions

## \[0.9.1]

* fix ios build

## \[0.9.0]

* add setAuthTokens method
* update native sdk versions

## \[0.8.5]

* fix bug on auth \[android]

## \[0.8.4]

* fix crashes when changing the system theme

## \[0.8.3]

* fix ui elements in dark mode

## \[0.8.2]

* support dark mode logo

## \[0.8.1]

* upgraded to target api 35 \[android]

## \[0.8.0]

* upgrade to Cap7

## \[0.7.1]

* add miniapp page animation

## \[0.7.0]

* add new menu style
* improved whitelisted url behavior

## \[0.6.0]

* add native pull to refresh
* add camera option to file picker
* other UI improvements

## \[0.5.0]

* Added list of user fields to consent screen
* Some improvements in native sdk

## \[0.4.0] 2025-01-23

* LTR/RTL support by language
* Fix problem with cookies and storage on logout
* Multiline error popup

## \[0.3.3] 2024-11-28

* add new menu style
* fix open\_miniapp\_duration on reload

## \[0.3.2] 2024-11-5

* \[android] change action button color for dark theme

## \[0.3.1] 2024-11-1

* no internet connection page
* fix crash on auth

## \[0.3.0] 2024-10-22

* clear cache with reload
* add support eSim flag (android)
* add maintenance mode

## \[0.2.8] 2024-10-16

* add miniapp settings expiration time to configs

## \[0.2.7] 2024-10-11

* changed more icon for style\_2
* added progressbar for share event

## \[0.2.6] 2024-10-10

* add new menu style (style\_2)

## \[0.2.5] 2024-10-01

* add new menu style (style\_1)

## \[0.2.4] 2024-09-26

* update native sdk dependencies
* add aboutPage flag to show/hide "About Page" on miniapp menu

## \[0.2.3] 2024-09-24

* update native sdk dependencies

## \[0.2.1] 2024-09-20

* add native share modal

## \[0.2.0] 2024-09-18

* upgrade to Cap6

## \[0.1.8] - cap5 2024-10-16

* add new menu style (style\_2)

## \[0.1.7] - cap5

* add new menu style (style\_1)

## \[0.1.6] - cap5

* add aboutPage flag to config
* update native sdk dependencies

## \[0.1.5] - cap5

* add native share modal

## \[0.1.4] - 2024-09-13

* add saveState flag to openMiniapp

## \[0.1.3] - 2024-08-22

* add language field to config to pass to miniapp
* add file download implementation
* save state when user close the miniapp
* clear cache and tokens when disabling User Data Sharing
* add event to change status bar color

## \[0.1.2] - 2024-08-19

* set empty video poster as default \[android]

## \[0.1.1]  2024-08-12

* Add sandbox mode
* Update network timeouts \[android]

## \[0.1.0] 2024-08-12

* Close miniapp if webview can't go back on press back button ## \[ios]
* Fix play video inline \[ios]
* Fix hide/show miniapp \[ios]

## \[0.0.5] 2024-08-12

* Revert renaming package for \[ios]

## \[0.0.4] 2024-08-12

* Add event listener type
* Downgrade capacitor version and rename package


# Expo
Source: https://boxo.mintlify.app/changelog/expo



## \[0.15.0]

* bump native sdk versions (android 1.45.1, ios 1.29.0)

## \[0.14.0]

* add orderPaymentId field to Payment

## \[0.13.1]

* add lottie animation support for miniapp splash loading indicator

## \[0.12.0]

* remove multitask mode

## \[0.11.0]

* add splash screen configuration options

## \[0.10.0]

* saveState is false by default
* add style\_5 for ActionButtons
* android: esim direct install

## \[0.9.2]

* android: add Consent screen config

## \[0.9.1]

* ios: fix Consent screen

## \[0.9.0]

* ios: add Consent screen config

## \[0.8.0]

* add setAuthTokens method
* bump native sdk versions

## \[0.7.0]

* bump native sdk versions

## \[0.6.3]

* add app.plugin.js

## \[0.6.2]

* Some improvements in native sdk

## \[0.6.1]

* add miniapp page animation

## \[0.6.0]

* add new menu style
* Added list of user fields to consent screen
* add native pull to refresh
* add camera option to file picker
* other improvements in native sdk

## \[0.5.0]

* Added list of user fields to consent screen
* LTR/RTL support by language
* Some improvements in native sdk

## \[0.4.2]

* add new menu style
* fix open\_miniapp\_duration on reload

## \[0.4.1]

* no internet connection page
* fix crash on auth

## \[0.4.0]

* clear cache with reload
* add support eSim flag (android)
* add maintenance mode

## \[0.3.0]

* add new menu style (style\_2)
* add progressbar for share event

## \[0.2.0]

* add new menu style

## \[0.1.2]

* update native sdk dependencies
* add show AboutPage flag to config

## \[0.1.1]

* add native share modal
* fix navigation bar issue on ios


# Flutter
Source: https://boxo.mintlify.app/changelog/flutter



## 0.18.0

* bump native sdk versions (android 1.45.1, ios 1.29.0)

## 0.17.0

* add orderPaymentId field to Payment

## 0.16.1

* add lottie animation support for miniapp splash loading indicator

## 0.15.0

* remove multitask mode

## 0.14.0

* add splash screen configuration options

## 0.13.1

* saveState is false by default

## 0.13.0

* update native Boxo SDK versions

## 0.12.0

* add setAuthTokens method
* update native Boxo SDK versions

## 0.11.0

* update native Boxo SDK versions

## 0.10.0

* update native Boxo SDK versions

## 0.9.0

* update native Boxo SDK versions
* fix build errors for android

## 0.8.1

* improvements in native sdk

## 0.8.0

* add native pull to refresh
* add camera option to file picker
* other improvements in native sdk

## 0.7.0

* add list of user fields to consent screen
* Some improvements in native sdk

## 0.6.2

* add new menu style
* fix open\_miniapp\_duration on reload

## 0.6.1 - Nov 4, 2024

* no internet connection page
* fix crash on auth

## 0.6.0 - Oct 22, 2024

* clear cache with reload
* add support eSim flag (android)
* add maintenance mode

## 0.5.0 - Oct 14, 2024

* add new menu style (style\_2)
* miniapp can open another miniapp with configs
* add progressbar to share file

## 0.4.0 - Oct 1, 2024

* add new menu style

## 0.3.0 - Sep 26, 2024

* updated native sdk dependencies
* add show About page to config

## 0.2.15 - Sep 24, 2024

* fix device model value \[android]
* fix native action bar \[ios]
* fix reload \[android]
* add native share modal
* add saveState param to openMiniapp

## 0.2.11 - Sep 4, 2024

* changed android native sdk to 1.5.17 \[android]

## 0.2.10 - Aug 27, 2024

* add language field to config to pass to miniapp
* add file download implementation
* save state when user close the miniapp
* clear cache and tokens when disabling User Data Sharing
* add event to change status bar color

## 0.2.9 - Aug 19, 2024

* changed android native sdk to 1.5.11 \[android]

## 0.2.8 - Aug 17, 2024

* changed android native sdk to 1.5.10 \[android]
* removed jcenter

## 0.2.7 - Aug 9, 2024

* play video inline \[ios]

## 0.2.6 - Aug 2, 2024

* close miniapp if webview can't go back on press back button \[ios]
* fixed hide/show miniapp \[ios]

## 0.2.5 - Jul 31, 2024

* updated sandbox mode

## 0.2.4 - Jul 31, 2024

* fixed hide all miniapps and reopen last miniapp immediately \[ios]

## 0.2.3 - Jul 26, 2024

* updated network timeouts

## 0.2.2 - Jul 26, 2024

* fix close miniapp page on multitask mode \[android]

## 0.2.1 - Jul 25, 2024

* added consent t\&c and privacy texts

## 0.2.0 - Jul 19, 2024

* Consent Management
* added enableSplash flag to miniapp configs
* UI changes

## 0.1.17 - Oct 12, 2020

* renamed methods for ios sdk

## 0.1.16 - Oct 8, 2020

* renamed AppboxoSdk class to Appboxo

## 0.1.15 - Oct 8, 2020

* renamed hideAllMiniApps function to hideMiniapps

## 0.1.14 - Sep 21, 2020

* fixed overriding global theme config with empty argument of openMiniapp function
* fixed react native channels bug

## 0.1.13 - Sep 17, 2020

* renamed function openMiniApp to openMiniapp
* added support dark mode for miniapps

## 0.1.12 - Sep 9, 2020

* added logout()
* added single/multitask mode

## 0.1.11 - Sep 3, 2020

* Changed necessary constructor fields for CustomEvent class to required

## 0.1.10 - Sep 3, 2020

* support ios 10

## 0.1.9 - 	Jul 13, 2020

* support lifecycle hooks for ios and android
* added 'additional\_user\_fields' param to openMiniApp()

## 0.1.7 - Oct 8, 2020

* added hideAllMiniApps()

## 0.1.5 - Jul 2, 2020

* added 'data' param to openMiniApp()
* removed openMiniAppWithCustomEvents()

## 0.1.4 - Jul 1, 2020

* support custom events for ios

## 0.1.2 - Jun 29, 2020

* support custom events for Android

## 0.1.0 - May 6, 2020


# iOS SDK
Source: https://boxo.mintlify.app/changelog/ios-sdk



## \[1.29.0] - 2026-06-12

### Added

* pass miniapp requiredFields to MiniappDelegate.onAuth
* expand AppBoxoWebAppGetMiniappSettings metadata (status, webview\_frame\_size, orientation, action button position/theme, status bar background, miniapp info, hostapp menu style)

## \[1.28.1] - 2026-06-03

### Fixed

* use transactionToken from old JSSDK as a orderPaymentId

## \[1.28.0] - 2026-05-29

### Added

* orderPaymentId to PaymentData

## \[1.27.7] - 2026-05-21

### Fixed

* Bundle for SPM

## \[1.27.6] - 2026-05-15

### Fixed

* Remove cached miniapp settings on logout

## \[1.27.5] - 2026-05-15

### Added

* Lottie progress animation

## \[1.26.1] - 2026-04-27

### Fixed

* Miniapp save state behavior

## \[1.26.0] - 2026-02-27

### Added

* Support location request modal dark mode

## \[1.25.0] - 2026-02-26

### Added

* Support for dark and light splash screen colors

## \[1.24.0] - 2026-02-25

### Added

* Clear local storage keys on miniapp close

## \[1.23.0] - 2026-02-17

### Added

* Request Location and consent screen config from miniapp

## \[1.22.0] - 2026-01-30

### Added

* Config for splash screen color
* session\_id for session events

## \[1.21.0] - 2025-11-26

### Added

* style\_5 for ActionButton

### Changed

* saveState default value false

## \[1.20.0] - 2025-11-19

### Fixed

* Memory leaks

## \[1.19.1] - 2025-10-31

### Fixed

* Consent Screen multiline texts

## \[1.19.0] - 2025-10-13

### Added

* Open app settings
* Get location optimization

## \[1.18.0] - 2025-10-01

### Added

* ConsentScreenConfig

## \[1.17.0] - 2025-09-12

### Added

* Share base64 file

## \[1.16.0] - 2025-09-03

### Added

* Loading progressbar config

## \[1.15.0] - 2025-09-02

### Added

* Remove all miniapp states when changing language

### Fixed

* UIKit open url bug

## \[1.14.0] - 2025-08-27

### Added

* support min ios 13.0
* Miniapp async delegate

## \[1.13.0] - 2025-08-20

### Added

* Get miniapp view controller

### Fixed

* onPause and onClose lyfecycle events for save state

## \[1.12.0] - 2025-08-19

### Added

* Dark mode progress view

### Fixed

* Dark mode status bar

## \[1.11.0] - 2025-08-07

### Added

* setAuthTokens method to miniapp

## \[1.10.3] - 2025-07-31

### Fixed

* Dark mode SSO

### Added

* Dark mode logo

## \[1.10.2] - 2025-07-16

### Fixed

* Close miniapp animation

## \[1.10.1] - 2025-04-22

### Added

* Add style option to AppBoxoWebAppSetActionButton

## \[1.10.0] - 2025-04-15

### Changed

* Rename SDK from AppBoxoSDK to BoxoSDK

## \[1.9.3] - 2025-04-10

### Fixed

* White listing url behavior

## \[1.9.2] - 2025-04-10

### Added

* New style\_4

### Changed

* White listed urls validation
* Page animation duration 0.3s

### Fixed

* QR code scanner

## \[1.9.1] - 2025-04-03

### Changed

* Show detailed error message only for sandbox

## \[1.9.0] - 2025-04-03

### Added

* Miniapp launch animations
* session\_start and session\_end analytic events

## \[1.8.5] - 2025-03-26

### Added

* Miniapp slide in animation

### Fixed

* Send session analytics
* Loading progress animation

## \[1.8.4] - 2025-03-19

### Added

* Pull to refresh

## \[1.8.3] - 2025-03-10

### Added

* Error page close button

## \[1.8.2] - 2025-02-18

### Added

* SSO required fields

## \[1.8.1] - 2025-01-22

### Changed

* Multiline error popup

## \[1.8.0] - 2025-01-09

### Fixed

* Fix deleting cookies and local storage on logout

## \[1.7.7] - 2024-12-15

### Added

* Support LTR/RTL semantic regardless of the hostapp

## \[1.7.6] - 2024-12-02

### Fixed

* String encoding from ascii to utf8

## \[1.7.5] - 2024-11-21

### Added

* New style\_3

### Fixed

* Reload miniapp

## \[1.7.4] - 2024-10-30

### Added

* open\_miniapp\_duration to GetInitData

### Changed

* No internet connection errors

## \[1.7.3] - 2024-10-22

### Added

* Maintenance mode

### Changed

* Reload miniapp on clear cache

## \[1.7.2] - 2024-10-16

### Changed

* Miniapp expiration time 1 min
* Set reloadIgnoringLocalCacheData URLRequest cachePolicy

## \[1.7.1] - 2024-10-11

### Added

* Loading Indicator for download and share file

### Changed

* Update style\_2 more button to gear button

### Fixed

* Send sdk version

## \[1.7.0] - 2024-10-09

### Added

* New menu style\_2
* AppBoxoWebAppOpenMiniApp params

### Changed

* Removed miniapp settings update timer

### Fixed

* Close and open miniapp immediately
* Set miniapp delegate on miniapp orientation change
* Dismiss popups on orientation change

## \[1.6.0] - 2024-10-01

### Added

* New menu style

## \[1.5.16] - 2024-09-25

### Added

* Added showAboutPage config
* Hide action buttons
* Miniapp urlSuffix

## \[1.5.15] - 2024-09-23

### Fixed

* WebView top padding

## \[1.5.14] - 2024-09-20

### Added

* Share file

### Changed

* Revert: Share file instead open File manager on download file

## \[1.5.13] - 2024-09-19

### Changed

* Share file instead open File manager on download file

## \[1.5.12] - 2024-09-13

### Added

* Miniapp saveState config

## \[1.5.11] - 2024-08-26

### Added

* Download file event

### Fixed

* Change status bar color

## \[1.5.10] - 2024-08-22

### Added

* Add language field to Config
* Add change status bar color
* Clear cache and token when disable user consent

## \[1.5.9] - 2024-08-20

### Changed

* Save miniapp state on close miniapp

## \[1.5.8] - 2024-08-09

### Added

* allowsInlineMediaPlayback true

## \[1.5.7] - 2024-07-31

### Change

* CLose miniapp on back button press
* Hide/show miniapps refactored

## \[1.5.6] - 2024-07-31

### Change

* Sandbox mode and staging

## \[1.5.5] - 2024-07-31

### Added

* Esim direct install

### Fixes

* Hide all miniapps and reopen last miniapp immediately

## \[1.5.4] - 2024-07-25

### Added

* Consent links
* apply primary color for SSO allow button

## \[1.5.3] - 2024-07-23

### Changed

* Sentry endpoint

## \[1.5.2] - 2024-07-17

### Fixes

* system info data

## \[1.5.1] - 2024-07-16

### Added

* enableSplash option to miniapp config

### Changed

* Remove miniapp state on close miniapp

## \[1.5] - 2024-07-15

### Changed

* System info: model

## \[1.4.27] - 2024-07-09

### Fixed

* Settings: Camera icon

## \[1.4.26] - 2024-07-09

### Added

* Consent Management

### Changed

* Increase miniapp menu button size

## \[1.4.25] - 2024-06-07

### Fixed

* Don't clear miniapp states on hideAllMiniapp

## \[1.4.24] - 2024-06-03

### Added

* SSO allow haptic feedback

## \[1.4.23] - 2024-05-07

### Added

* Prepare miniapps

## \[1.4.22] - 2024-04-17

### Changed

* Revert Hide splash screen when webview starts loading

## \[1.4.21] - 2024-04-16

### Changed

* Hide SSO loading progress
* Hide splash screen when webview starts loading

## \[1.4.20] - 2024-03-27

### Added

* miniappSettingsExpirationTime field to Config

## \[1.4.19] - 2024-03-22

### Added

* Cache miniapp settings with completion handler

## \[1.4.18] - 2024-03-19

### Added

* Cache miniapp settings

## \[1.4.17] - 2024-02-27

### Changed

* Remove user info permission
* Remove miniapp state on call close

### Fixed

* Call completionHandler for runJavaScriptAlertPanelWithMessage

## \[1.4.16] - 2024-02-17

### Fixed

* SSO modal

## \[1.4.15] - 2024-02-15

### Changed

* Powered by boxo logo
* Hide loader view on half web content loaded
* SSO modal

### Fixed

* Image caching

## \[1.4.14] - 2023-12-15

### Added

* User agent
* Safe area size

## \[1.4.13] - 2023-11-15

### Fixed

* Action button size

## \[1.4.12] - 2021-11-16

### Changed

* Build sdk with Xcode 11.7 version

## \[1.4.11] - 2021-11-15

### Fixed

* logout on miniapp is not open

## \[1.4.10] - 2021-11-15

### Added

* showClearCache option

### Changed

* Powered by appboxo icon

### Fixed

* Hide miniapps on logout

## \[1.4.9] - 2021-10-08

### Fixed

* Update miniapp settings every 30 sec

## \[1.4.8] - 2021-09-21

### Added

* onUserInteraction method to miniapp delegate
* Show js prompts
* Clear cookies & local storage on clear cache

### Changed

* Simplify miniapp menu

### Fixed

* Hide branding
* About page constraints

## \[1.4.7] - 2021-09-13

### Fixed

* clear cookies and local storage on logout

## \[1.4.6] - 2021-08-06

### Added

* permissionsPage option to hide Settings menu

### Changed

* dismiss cookies and local storage on clear cache

## \[1.4.5] - 2021-08-03

### Fixed

* Show logo in confirm view
* Status bar color

## \[1.4.4] - 2021-07-21

### Added

* Pull miniapp settings every 30 seconds and reload if needed

## \[1.4.3] - 2021-07-02

### Added

* New webview allow/cancel request delegate method
* is\_shopboxo field

### Fixed

* Action button top anchor for ios 11

## \[1.4.2] - 2021-06-18

### Changed

* isSandbox field renamed to sandboxMode in Config
* Payment flow
* Custom event redesigned

## \[1.4.1] - 2021-06-15

### Changed

* Auth flow
* Auto orientation

## \[1.4.0] - 2021-05-27

### Added

* Get approved miniapps
* Hide branding option
* Inject js script

## \[1.3.39] - 2021-03-17

### Added

* Hide/show appboxo branding
* Disable whitelisting urls

### Fixed

* Recaptha
* Support multiple window mode for auth with socials

## \[1.3.38] - 2021-03-01

### Added

* Sentry

### Changed

* Removed params from getMiniapp method
* Added new methods to Miniapp to setting auth payload, additional user data, custom data

### Fixed

* Open new tab requests

## \[1.3.37] - 2021-01-25

### Fixed

* Whitelisted urls
* Json response with dictionary
* Handle request errors
* MiniappConfig refactored

## \[1.3.36] - 2020-12-18

### Added

* url change handler
* option to add third action menu
* extra query parameters to miniapp URL

## \[1.3.35] - 2020-11-18

### Added

* Payment method

## \[1.3.34] - 2020-09-30

### Fixed

* Border for fixed action buttons view

## \[1.3.33] - 2020-09-29

### Changed

* Login error body

### Fixed

* Http Content-type header

## \[1.3.32] - 2020-09-24

### Changed

* Classes renamed

### Fixed

* Action buttons constraints

## \[1.3.31] - 2020-09-15

### Added

* Support dark mode

## \[1.3.30] - 2020-09-11

### Added

* Support ios simulator

## \[1.3.29] - 2020-09-09

### Added

* Design for Dark mode
* Show miniapp name on popup menu

## \[1.3.28] - 2020-09-03

### Added

* Dynamic floating action menu
* Allow swipe back for webview
* Enable select text in webview

## \[1.3.27] - 2020-09-03

## \[1.3.26] - 2020-09-03

### Changed

* Support ios 10

## \[1.3.25] - 2020-08-24

### Fixed

* Open miniapp from miniapp

## \[1.3.24] - 2020-08-24

\###Changed

* Minimal support ios 11

### Fixed

* Miniapp lifecycle

## \[1.3.23] - 2020-08-21

### Added

* support ios 9
* additional user fields for auth in miniapps

### Changed

* data field in miniapp from string to map

## \[1.3.21] - 2020-07-30

### Added

* added miniapp lifecycle

### Changed

* changed License to Apache 2.0

## \[1.3.20] - 2020-07-28

## \[1.3.19] - 2020-07-28

## \[1.3.18] - 2020-07-22

### Added

* added login/logout and transaction tracking in sdk
* added white\_listed\_urls in miniapp settings to filter miniapp domains
* added auth header on fetching miniapp settings

## \[1.3.16] - 2020-07-09

### Added

* Hide all opened miniapps
* Error message handler on fetch miniapp settings

## \[1.3.15] - 2020-06-18

## \[1.3.14] - 2020-06-18

### Added

* Objective-C support

## \[1.3.13] - 2020-06-12

### Added

* Miniapp session analytics
* Hostapp colors
* Handle sms,tel,mail url schemes

### Changed

* js body for AppBoxoWebAppGetMiniappSettings method

### Fixed

* Update opened miniapp payload
* Retry load current page

## \[1.3.11] - 2020-05-28

### Added

* AppBoxoWebAppOnRestore feature

### Changed

* Deploy.yml

## \[1.3.9] - 2020-05-22

### Added

* Miniapp settings
* Compass
* Instant miniapp reopening
* Background color of the window

### Changed

* AppBoxoWebAppShowImages result callback return type
* Render NavBar only when miniapp is loaded

### Fixed

* Landscape mode

## \[1.3.8] - 2020-05-14

### Added

* Gyroscope
* Accelerometer
* Status bar color based on miniapp settings
* CHANGELOG

### Fixed

* Loader view for landscape mode


# React Native
Source: https://boxo.mintlify.app/changelog/react-native-sdk



## \[1.15.2]

* bump native android sdk version to 1.45.1

## \[1.15.1]

* bump native sdk versions (android - 1.44.0, ios - 1.29.0)

## \[1.14.0]

* add orderPaymentId field to Payment

## \[1.13.1]

* add lottie animation support for miniapp splash loading indicator

## \[1.12.0]

* remove multitask mode

## \[1.11.0]

* add splash screen configuration options

## \[1.10.0]

* saveState is false by default
* android: add esim direct install
* add style\_5 for ActionButtons

## \[1.9.0]

* added setAuthTokens function
* updated native sdk versions

## \[1.8.0]

* update android native sdk

## \[1.7.2]

* update android native sdk
* fix exports

## \[1.7.1]

* improvements in native sdk

## \[1.7.0]

* add miniapp page animation
* add native pull to refresh
* add camera option to file picker
* other improvements in native sdk

## \[1.6.0]

* Added list of user fields to consent screen
* LTR/RTL support by language
* Some improvements in native sdk

## \[1.5.2] - 2024-11-21

* add new menu style
* fix send payment result(android)

## \[1.5.1] - 2024-11-04

* no internet connection page
* fix crash on auth

## \[1.5.0] - 2024-10-22

* add support eSim flag (android)
* add maintenance mode

## \[1.4.0] - 2020-10-21

* add new menu style (style\_2)
* added progressbar for share event
* add miniapp settings expiration time to configs
* reload after clear cache

## \[1.3.0] - 2024-10-01

* add new menu style

## \[1.2.0] - 2024-09-26

* add aboutPage flag to config
* update native sdk dependencies

## \[1.1.3] - 2024-09-20

* add share modal
* fix action bar on ios
* fix device model name on android

## \[1.1.2] - 2024-09-13

* add saveState param to openMiniapp

## \[1.1.1] - 2024-09-20

* add enableSplash param to openMiniapp

## \[1.1.0] - 2024-08-20

* native android sdk ver. 1.5.16
* native ios sdk ver. 1.5.11
* add Consent Management
* add language support
* add sandbox mode
* save state when user close the miniapp

## \[1.0.40] - 2023-11-24

* native ios sdk ver. 1.4.13
* native android sdk ver. 1.4.21


# Boxo Connect
Source: https://boxo.mintlify.app/host-apps/BoxoConnect



## Introduction

Boxo Connect is a **Single Sign-On (SSO)** functionality that enables the host app to securely pass user profile information, allowing seamless authorization within the mini app. In essence, the Boxo Platform facilitates the transfer of user data from the host app backend to the mini app backend, ensuring smooth user authentication and returning a session token for continued access.

<Tabs>
  <Tab title="BoxoConnect OAuth">
    This is the traditional OAuth flow where the host app backend provides auth codes and access tokens to the Boxo Platform.

    <Accordion title="OAuth Flow Diagram">
      Here is diagram showcasing the hostapp user authorization inside miniapp

      <img alt="AuthDiagram" />

      Authentication and User Authorization Flow

      <Steps>
        <Step title="User launches miniapp">
          The user opens the host app and launches the mini app.
        </Step>

        <Step title="User identification required">
          To proceed, the user must be identified (e.g., for product purchases or user registration).
        </Step>

        <Step title="Miniapp calls login">
          The mini app calls `Boxo.login()`.
        </Step>

        <Step title="User consent">
          The user is prompted to confirm access to their personal data required for authorization.
        </Step>

        <Step title="SDK retrieves auth code">
          The Boxo native SDK retrieves an authorization code from the host app and sends an HTTPS request to the Boxo platform.
        </Step>

        <Step title="Platform forwards auth code">
          The Boxo platform forwards the authorization code via an HTTPS request to the host app backend.
        </Step>

        <Step title="Backend validates and returns access token">
          The host app backend validates the authorization code and returns an access token.
        </Step>

        <Step title="Platform requests user data">
          The Boxo platform sends an HTTPS request with the access token to the host app backend to retrieve user data.
        </Step>

        <Step title="Backend returns user data">
          The host app backend validates the access token and returns user data.
        </Step>

        <Step title="Platform forwards user data to miniapp">
          The Boxo platform forwards the user data via an HTTPS request to the mini app backend.
        </Step>

        <Step title="Miniapp backend processes user">
          The mini app backend registers a new user or identifies an existing one, then issues an authorization token to the Boxo platform.
        </Step>

        <Step title="Authorization token returned to SDK">
          The Boxo platform returns the authorization token to the Boxo native SDK.
        </Step>

        <Step title="Token passed to miniapp">
          The authorization token is passed to the mini app.
        </Step>

        <Step title="Miniapp requests user data">
          The mini app sends a request with the authorization token to the mini app backend to retrieve user data.
        </Step>

        <Step title="Backend validates and returns data">
          The mini app backend validates the authorization token and returns the user data.
        </Step>

        <Step title="User successfully authorized">
          The user is successfully authorized and can proceed within the mini app.
        </Step>
      </Steps>
    </Accordion>

    <Accordion title="Setting up the backend">
      \*Note: Feature must be enabled in [Dashboard Partnership](https://dashboard.boxo.io/partnerships/)

      <img alt="AuthDiagram" />

      **Data format**

      Currently, data exchange is conducted in JSON format. String size limits are defined within the respective data types.

      <Accordion title="Get access token">
        This endpoint allows the Boxo platform to obtain an access token in exchange for an authorization code.

        **URL and METHOD**

        This endpoint must handle a HTTPS POST request URL to endpoint must be provided in [Dashboard](https://dashboard.boxo.io/host-apps/)

        <img alt="AuthDiagram" />

        **Headers**

        | Key                 | Value                                                             |
        | ------------------- | ----------------------------------------------------------------- |
        | Authorization       | `<prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)>` |
        | X-Miniapp-App-ID    | `<app_id - Miniapp identifier>`                                   |
        | X-Hostapp-Client-ID | `<client_id - Hostapp identifier>`                                |

        * Default `<prefix>`: Token. Access token prefix can be set in [Boxo Connect](https://dashboard.boxo.io/host-apps/).
        * `hostapp_client_id` and `hostapp_secret_key` must be provided in [Dashboard](https://dashboard.boxo.io/host-apps/)

        **Body**

        | Field      | Data type | Description                               |
        | ---------- | --------- | ----------------------------------------- |
        | auth\_code | String    | Auth code provided by hostapp to Boxo SDK |

        **Response**

        * Response status must be `200` in all cases
        * Response body:

        | Field           | Data type    | Optional                         | Description                                                                                                                                                       |
        | --------------- | ------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | `access_token`  | String(1000) | No, except `error_code` provided | Access token for get user data request. To use in payments requests enable `Use access token` in [Boxo Payments](https://dashboard.boxo.io/host-apps/).           |
        | `refresh_token` | String(1000) | Yes                              | Refresh token for get user data request. To use in payments requests enable `Use access token` in [Boxo Payments](https://dashboard.boxo.io/host-apps/).          |
        | `error_code`    | String       | Yes                              | If some error is occured error code should be provided. Example: `{"error_code": "INVALID_AUTH_CODE"}` All error codes can be found [here](/host-apps/ErrorCodes) |

        **Request Example:**

        ```text theme={"system"}
            curl --location --request POST '[YOUR_SERVER_URL]/api/get_access_token/' \
            --header 'Content-Type: application/json' \
            --header 'Authorization: Basic {{BASE64_ENCODED_CLIENT_ID_AND_CLIENT_SECRET}}' \
            --data-raw '{ "auth_code": "{{HOSTAPP_AUTH_CODE_THAT_COMES_FROM_SDK}}" }'
        ```
      </Accordion>

      <Accordion title="Get user data">
        This endpoint allows the Boxo platform to retrieve user data using an access token.

        **URL and METHOD**

        * This endpoint must handle a HTTPS GET request
        * URL to endpoint must be provided in [Dashboard](https://dashboard.boxo.io/host-apps/)

          <img alt="AuthDiagram" />

        **Headers**

        | Key                   | Value                              |
        | --------------------- | ---------------------------------- |
        | `Authorization`       | `Token <access_token>`             |
        | `X-Miniapp-App-ID`    | ` <app_id - Miniapp identifier>`   |
        | `X-Hostapp-Client-ID` | `<client_id - Hostapp identifier>` |

        **Response:**

        * Response status must be `200` in all cases
        * Response body:

        | Field        | Data type | Optional                         | Description                                                                                                                                                          |
        | ------------ | --------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
        | `user_data`  | UserData  | No, except `error_code` provided | Hostapp user data.                                                                                                                                                   |
        | `error_code` | String    | Yes                              | If some error is occured error code should be provided. Example: `{"error_code": "INVALID_ACCESS_TOKEN"}` All error codes can be found [here](/host-apps/ErrorCodes) |

        **UserData**

        | Field               | Data type   | Optional | Description                                |
        | ------------------- | ----------- | -------- | ------------------------------------------ |
        | `reference`         | String(100) |          | Reference to user in Hostapp Server        |
        | `email`             | String      | Yes      | Verified user email address                |
        | `phone`             | String      | Yes      | Verified user phone number in E.164 format |
        | `first_name`        | String      | Yes      | User's first name                          |
        | `last_name`         | String      | Yes      | User's last name                           |
        | `custom_attributes` | JSON        | Yes      | Custom attributes                          |

        <Warning>
          **WARNING** For Shopboxo miniapps either `email` or `phone` must be provided
        </Warning>

        **Request Example:**

        ```text theme={"system"}
            curl --location --request GET '[YOUR_SERVER_URL]/api/get_user_data/'\
            --header 'Content-Type: application/json' \
            --header 'Authorization: Token {{ACCESS_TOKEN}}'
        ```

        **Required fields**

        Each mini app requires a set of minimum fields to create a user within its system and generate a session for the newly created user. The specific required fields for each mini app can be found in its details on the Showroom page.

        Below is a list of all possible fields:

        * email
        * phone
        * first\_name
        * last\_name
      </Accordion>
    </Accordion>

    <Accordion title="Setting up the SDK">
      **Initialization**

      Parameter Descriptions:

      Within the SDK, there are specific parameters and methods that must be either provided or implemented to ensure proper functionality. `app_id` - Boxo miniapp app id

      To launch a specific mini app, you must first call the initialization method.

      <Tabs>
        <Tab title="iOS">
          ```swift theme={"system"}
          let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
          miniapp.delegate = self
          miniapp.open(viewController: self)
          ...
          extension ViewController : MiniappDelegate {
              func onAuth(miniapp: Miniapp) {
                  //get AuthCode from hostapp backend and send it to miniapp
                  miniapp.setAuthCode(authCode: "auth_code")
              }
          }
          ```
        </Tab>

        <Tab title="Android">
          ```kotlin theme={"system"}
          val miniapp = Boxo.getMiniapp("app_id")
          miniapp.setAuthListener { _, miniapp ->
              //get AuthCode from hostapp backend and send it to miniapp
              miniapp.setAuthCode("auth_code")
          }
          miniapp.open()
          ```
        </Tab>

        <Tab title="Flutter">
          ```dart theme={"system"}
          Boxo.openMiniapp('app_id');
          Boxo.lifecycleHooksListener(
              onAuth: (appId) { // called when authorization flow starts
                  //get AuthCode from hostapp backend and send it to miniapp
                  Boxo.setAuthCode('app_id', 'auth_code');
              }
          );
          ```
        </Tab>

        <Tab title="ReactNative">
          ```js theme={"system"}
          Boxo.openMiniapp('app_id')
          Boxo.lifecycleHooksListener({
              onAuth: (appId: string) => {
                  //get AuthCode from hostapp backend and send it to miniapp
                  Boxo.setAuthCode('app_id', 'auth_code');
              },    
          });
          ```
        </Tab>

        <Tab title="Capacitor">
          ```js theme={"system"}
          Boxo.openMiniapp({ appId: 'app_id'});
          Boxo.addListener('miniapp_lifecycle', event => {
            if (event.lifecycle == 'onAuth') {
              //get AuthCode from hostapp backend and send it to miniapp
              Boxo.setAuthCode({ appId: 'app_id', 'auth_code'});
            }
          });
          ```
        </Tab>

        <Tab title="Expo">
          ```js theme={"system"}
          Boxo.openMiniapp({ appId: 'app_id' })
          Boxo.addAuthListener((authEvent) => {
              //get AuthCode from hostapp backend and send it to miniapp
              Boxo.setAuthCode('app_id', 'auth_code')
          });
          ```
        </Tab>
      </Tabs>

      <Warning>
        **WARNING** When a user logs out of the host app, ensure that the WebView cache is cleared using the following commands: `Boxo.logout()` for Android or `Boxo.shared.logout()` for iOS so that the miniapps' storage is also cleared to log out the miniapp users as well.
      </Warning>
    </Accordion>

    <Accordion title="Get user consent">
      This is Boxo endpoint to get status of user consent in Boxo Platform

      **URL and METHOD**

      * This is HTTPS GET `/api/v1/accounts/consent/get_consent/` endpoint

      ### Query Parameters:

      | Parameter        | Data type | Optional | Description                         |
      | ---------------- | --------- | -------- | ----------------------------------- |
      | `client_id`      | String    |          | Hostapp identifier                  |
      | `app_id`         | String    |          | Miniapp identifier                  |
      | `user_reference` | String    |          | Reference to user in Hostapp Server |

      **Response:**

      ```text theme={"system"}
      {
         "is_consented": <Bool>
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="BoxoConnect Direct">
    This is the streamlined Direct flow where the host app backend directly sends user data to the Boxo Platform.

    <Accordion title="Direct Flow Diagram">
      Here is diagram showcasing the hostapp user authorization inside miniapp

      <img alt="AuthDiagram" />

      Authentication and User Authorization Flow

      <Steps>
        <Step title="User launches miniapp">
          The user opens the host app and launches the miniapp.
        </Step>

        <Step title="Miniapp identifies user needs">
          The miniapp determines that user identification is needed to proceed.
        </Step>

        <Step title="JS SDK login call">
          The miniapp calls `appboxosdk.login` JS SDK event to request login action.
        </Step>

        <Step title="Consent screen displayed">
          The user sees a consent dialog asking to "Allow miniapp to access your account information" with an "Allow" button.
        </Step>

        <Step title="Auth Gateway request">
          After user consent, the system makes a request to the host app's authentication gateway.
        </Step>

        <Step title="Host app sends user data">
          The host app backend sends the user data to the Boxo Platform **connect/** endpoint.
        </Step>

        <Step title="Platform forwards to miniapp">
          The Boxo Platform forwards the user data to the miniapp backend.
        </Step>

        <Step title="Miniapp generates auth token">
          The miniapp backend processes the user data and generates an authorization token.
        </Step>

        <Step title="Token returned to host app">
          The token is also provided back to the host app.
        </Step>

        <Step title="Token sent to miniapp">
          The authorization token is sent back through the chain to the miniapp frontend.
        </Step>

        <Step title="User authorized">
          The miniapp server authorizes the user using the token.
        </Step>

        <Step title="Flow completed">
          The user is successfully authorized and can continue using the miniapp.
        </Step>
      </Steps>

      This process ensures a secure and seamless flow for user authorization between the host app, Boxo platform, and miniapp.
    </Accordion>

    <Accordion title="Setting up the backend for Direct">
      \*Note: Feature must be enabled in [Dashboard Partnership](https://dashboard.boxo.io/partnerships/)

      <img alt="AuthDiagram" />

      **Data format**

      Currently, data exchange is conducted in JSON format. String size limits are defined within the respective data types.

      <Accordion title="Connect endpoint">
        This endpoint is called by the Super App (partner) server to connect a user to a miniapp on the Boxo Platform. On success, it returns an authorization token pair for the miniapp session.

        **URL and METHOD**

        * HTTPS POST `/api/v1/connect/` (Boxo Platform)

        **Headers**

        | Key          | Value              |
        | ------------ | ------------------ |
        | Content-type | `application/json` |

        > Authentication to this endpoint is managed via your partnership configuration in the Dashboard (e.g., IP whitelisting or [Request Signaturing](/host-apps/Signaturing)). Follow your integration setup.

        **Request Body**

        | Field       | Data type | Optional | Description             |
        | ----------- | --------- | -------- | ----------------------- |
        | `client_id` | String    | No       | Hostapp identifier      |
        | `app_id`    | String    | No       | Miniapp identifier      |
        | `user_data` | UserData  | No       | User information object |

        **UserData**

        | Field               | Data type | Optional | Description                                |
        | ------------------- | --------- | -------- | ------------------------------------------ |
        | `reference`         | String    | No       | Reference to user in Hostapp Server        |
        | `email`             | String    | Yes      | Verified user email address                |
        | `phone`             | String    | Yes      | Verified user phone number in E.164 format |
        | `first_name`        | String    | Yes      | User's first name                          |
        | `last_name`         | String    | Yes      | User's last name                           |
        | `custom_attributes` | JSON      | Yes      | Custom attributes                          |

        **Response**

        * Response status `200` for success, `400` for errors
        * Response body:

        **Success Response (200):**

        | Field           | Data type | Description   |
        | --------------- | --------- | ------------- |
        | `token`         | String    | Auth token    |
        | `refresh_token` | String    | Refresh token |

        **Error Response (400):**

        | Field               | Data type | Optional | Description                    |
        | ------------------- | --------- | -------- | ------------------------------ |
        | `error_code`        | String    | No       | Error code                     |
        | `error_message`     | String    | No       | Detailed error message         |
        | `exception`         | String    | Yes      | Exception details if available |
        | `custom_attributes` | Object    | Yes      | Additional error context       |

        **Request Example**

        ```text theme={"system"}
        curl --location --request POST '[BOXO_PLATFORM_SERVER_URL]/api/v1/connect/' \
          --header 'Content-Type: application/json' \
          --data-raw '{
            "client_id": "{{CLIENT_ID}}",
            "app_id": "{{MINIAPP_ID}}",
            "user": {
              "reference": "{{USER_REFERENCE}}",
              "email": "john@example.com",
              "phone": "+11234567890",
              "first_name": "John",
              "last_name": "Doe",
              "custom_attributes": {}
            }
          }'
        ```

        <Warning>
          **WARNING** For Shopboxo miniapps either `email` or `phone` must be provided
        </Warning>

        **Success Response (200)**

        ```text theme={"system"}
        {
          "token": "<AUTH_TOKEN>",
          "refresh_token": "<REFRESH_TOKEN>"
        }
        ```

        **Error Response (400)**

        ```text theme={"system"}
        {
          "error_code": "INVALID_INPUT",
          "error_message": "Missing required field: app_id",
          "exception": null,
          "custom_attributes": null
        }
        ```

        **Required fields**

        Each mini app requires a set of minimum fields to create a user within its system and generate a session for the newly created user. The specific required fields for each mini app can be found in its details on the Showroom page.

        Below is a list of all possible fields:

        * email
        * phone
        * first\_name
        * last\_name
        * custom\_attributes
      </Accordion>
    </Accordion>

    <Accordion title="Setting up the SDK for Direct">
      **Initialization**

      Parameter Descriptions:

      Within the SDK, there are specific parameters and methods that must be either provided or implemented to ensure proper functionality. `app_id` - Boxo miniapp app id

      To launch a specific mini app, you must first call the initialization method.

      <Tabs>
        <Tab title="iOS">
          ```swift theme={"system"}
          let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
          miniapp.delegate = self
          miniapp.open(viewController: self)
          ...
          extension ViewController : MiniappDelegate {

              func onAuth(miniapp: Miniapp) {
                  //send a request to backend to fetch tokens
                  miniapp.setAuthTokens(["token" : "<token>", "refresh_token" : "<refresh_token>"])
              }
          }
          ```
        </Tab>

        <Tab title="Android">
          ```kotlin theme={"system"}
          val miniapp = Boxo.getMiniapp("app_id")
          miniapp.setAuthListener { _, miniapp ->
              //send a request to backend to fetch tokens
              miniapp.setAuthTokens(mapOf(
                  "token" to "<token>",
                  "refresh_token" to "<refresh_token>"
              ))
          }
          miniapp.open()
          ```
        </Tab>

        <Tab title="Flutter">
          ```dart theme={"system"}
          Boxo.openMiniapp('app_id');
          Boxo.lifecycleHooksListener(
              onAuth: (appId) { // called when authorization flow starts
                  //send a request to backend to fetch tokens
                  Boxo.setAuthTokens({
                      'token': '<token>',
                      'refresh_token': '<refresh_token>'
                  });
              }
          );
          ```
        </Tab>

        <Tab title="ReactNative">
          ```js theme={"system"}
          Boxo.openMiniapp('app_id')
          Boxo.lifecycleHooksListener({
              onAuth: (appId: string) => {
                  //send a request to backend to fetch tokens
                  Boxo.setAuthTokens({
                      'token': '<token>',
                      'refresh_token': '<refresh_token>'
                  });
              },    
          });
          ```
        </Tab>
      </Tabs>

      <Warning>
        **WARNING** When a user logs out of the host app, ensure that the WebView cache is cleared using the following commands: `Boxo.logout()` for Android or `Boxo.shared.logout()` for iOS so that the miniapps' storage is also cleared to log out the miniapp users as well.
      </Warning>
    </Accordion>

    <Accordion title="Get user consent for Direct">
      This is Boxo endpoint to get status of user consent in Boxo Platform

      **URL and METHOD**

      * This is HTTPS GET `/api/v1/accounts/consent/get_consent/` endpoint

      ### Query Parameters:

      | Parameter        | Data type | Optional | Description                         |
      | ---------------- | --------- | -------- | ----------------------------------- |
      | `client_id`      | String    |          | Hostapp identifier                  |
      | `app_id`         | String    |          | Miniapp identifier                  |
      | `user_reference` | String    |          | Reference to user in Hostapp Server |
      | **Response:**    |           |          |                                     |

      ```text theme={"system"}
      {
         "is_consented": <Bool>
      }
      ```
    </Accordion>
  </Tab>
</Tabs>


# Boxo Payments
Source: https://boxo.mintlify.app/host-apps/BoxoPayments



## Introduction

Boxo Payments is an in-app payment functionality that enables host app users to complete payments for orders within the miniapp.

<Accordion title="Boxo Payments flow">
  Here is a diagram illustrating the payment process for a miniapp order using the host app's payment system.

  <img alt="AuthDiagram" />

  <Steps>
    <Step title="User initiates payment">
      The user navigates to the payment page in the miniapp and initiates the creation of an order.
    </Step>

    <Step title="Miniapp creates order request">
      The miniapp server creates the order and sends a **createOrderPayment** request to the Boxo Platform.
    </Step>

    <Step title="Platform initiates payment process">
      The Boxo Platform initiates the order payment process on the host app server.
    </Step>

    <Step title="Host app returns payment ID">
      The host app server returns an **orderPaymentID** to the Boxo Platform.
    </Step>

    <Step title="Platform forwards payment ID">
      The Boxo Platform then forwards the **orderPaymentID** to the miniapp server.
    </Step>

    <Step title="Miniapp receives payment ID">
      The miniapp server passes the **orderPaymentID** to the miniapp.
    </Step>

    <Step title="SDK receives payment request">
      The miniapp forwards the **orderPaymentID** to the Boxo JS SDK's `pay` method.
    </Step>

    <Step title="Native SDK displays confirmation">
      The **Boxo Native SDK** captures the Boxo JS SDK's pay event (with the **orderPaymentID**) and displays a payment confirmation page to the user.
    </Step>

    <Step title="User confirms payment">
      The user confirms the payment.
    </Step>

    <Step title="Host app processes payment">
      The host app processes the payment and sends the payment status as a response to the Boxo JS SDK pay event.

      * During this process, the host app server sends a callback to the Boxo Platform, which updates the order status in the miniapp backend.
    </Step>

    <Step title="Miniapp processes payment status">
      The miniapp processes the payment status received from the Boxo JS SDK event and confirms the order payment status on its server.
    </Step>

    <Step title="Payment status finalized">
      The miniapp finalizes the order payment status.

      * If the order is still processing at this stage, the miniapp will request the payment status from the Boxo Platform, which, in turn, will query the host app server for an update.
    </Step>

    <Step title="Display payment result">
      Finally, the miniapp displays the order payment status page to the user.
    </Step>
  </Steps>
</Accordion>

<Accordion title="Setting up the backend">
  \*Note: Feature must be enabled in [Dashboard Partnership](https://dashboard.boxo.io/partnerships/)

  <img alt="AuthDiagram" />

  **Data format**

  Currently, JSON is used for data exchange. Decimal values can be represented as floats, numbers, or strings, with a maximum of 20 digits in total and up to 2 digits after the decimal point. String size limits are defined within the data type specifications.

  <Accordion title="1. Create Order Payment Endpoint">
    This endpoint allows the Boxo Platform to create an order payment (refer to Step 3 in the diagram).

    **URL and METHOD:**

    This endpoint must handle a HTTPS POST request
    URL to endpoint must be provided in [Dashboard](https://dashboard.boxo.io/host-apps/)

    <img alt="AuthDiagram" />

    **Headers:**

    | Key             | Value                                                                                                                                                           |
    | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `Authorization` | `<prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)>` or token from [Get access token](/host-apps/BoxoConnect#get-access-token) can be used instead |
    | `Content-type`  | `application/json`                                                                                                                                              |
    | `X-User-ID`     | `<Hostapp user reference>`                                                                                                                                      |

    * Default `<prefix>`: `Token`. Access token prefix can be set in [Boxo Connect](https://dashboard.boxo.io/host-apps/).
    * To use user access token from Boxo Connect as authorization token enable `Use access token` in [Dashboard](https://dashboard.boxo.io/host-apps/).
    * `hostapp_client_id` and `hostapp_secret_key` must be provided in [Dashboard](https://dashboard.boxo.io/host-apps/)

    **Body**

    | Field    | Data type    | Description                            |
    | -------- | ------------ | -------------------------------------- |
    | `app_id` | String       | Miniapp identifier                     |
    | `order`  | OrderDetails | Order info (amount, currency and etc.) |

    **OrderDetails:**

    | Field                      | Data type    | Optional | Description                                                                                                                                                                                                                                                                |
    | -------------------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `currency`                 | String(20)   | No       | Currency code for the order (e.g., 'USD')                                                                                                                                                                                                                                  |
    | `amount`                   | Decimal      | No       | Total order amount (decimal with 2 decimal places)                                                                                                                                                                                                                         |
    | `subtotal_amount`          | Decimal      | Yes      | Subtotal before taxes and shipping (decimal with 2 decimal places)                                                                                                                                                                                                         |
    | `shipping_amount`          | Decimal      | Yes      | Shipping cost (decimal with 2 decimal places)                                                                                                                                                                                                                              |
    | `discount_amount`          | Decimal      | Yes      | Total discount applied (decimal with 2 decimal places)                                                                                                                                                                                                                     |
    | `tax_title`                | String(250)  | Yes      | Title/name of the tax                                                                                                                                                                                                                                                      |
    | `tax_amount`               | Decimal      | Yes      | Tax amount (decimal with 2 decimal places)                                                                                                                                                                                                                                 |
    | `taxes_included`           | Boolean      | Yes      | Boolean indicating if taxes are included in the price                                                                                                                                                                                                                      |
    | `wholesale_total`          | Decimal      | Yes\*    | Wholesale/settlement amount of the order, deducted from the partner team balance when the order is paid. Sent as provided by the miniapp and omitted when the miniapp does not provide it. \***Always present for partner teams on the [pre-paid model](#pre-paid-model)** |
    | `wholesale_total_currency` | String(20)   | Yes      | Currency of `wholesale_total`. Sent as provided by the miniapp and omitted when the miniapp does not provide it; the team balance currency is used for the deduction in that case                                                                                          |
    | `note`                     | Text         | Yes      | Additional notes for the order                                                                                                                                                                                                                                             |
    | `custom_attributes`        | JSON         | Yes      | JSON field for custom order attributes                                                                                                                                                                                                                                     |
    | `miniapp_order_id`         | String(255)  | Yes      | Order ID from the miniapp side                                                                                                                                                                                                                                             |
    | `hostapp_user_id`          | String(255)  | Yes      | User ID from the host app                                                                                                                                                                                                                                                  |
    | `items`                    | OrderItem\[] | Yes      | List of order items (see OrderItem below)                                                                                                                                                                                                                                  |
    | `shipping_address`         | Object       | Yes      | Shipping address details (see OrderShippingAddress below)                                                                                                                                                                                                                  |

    **OrderItem:**

    | Field                  | Data type   | Optional | Description                                       |
    | ---------------------- | ----------- | -------- | ------------------------------------------------- |
    | `product_name`         | String(250) | No       | Name of the product                               |
    | `product_variant_name` | String(250) | No       | Product variant name                              |
    | `product_sku`          | String(250) | No       | Product SKU/identifier                            |
    | `product_image_url`    | String(500) | No       | URL to product image                              |
    | `quantity`             | Integer     | No       | Quantity of the product (positive integer)        |
    | `price`                | Decimal     | No       | Price per item (decimal with 2 decimal places)    |
    | `discount`             | Decimal     | No       | Discount per item (decimal with 2 decimal places) |

    **OrderShippingAddress:**

    | Field           | Data type    | Optional | Description                                           |
    | --------------- | ------------ | -------- | ----------------------------------------------------- |
    | `address1`      | String(1000) | Yes      | Primary address line                                  |
    | `address2`      | String(1000) | Yes      | Secondary address line                                |
    | `first_name`    | String(250)  | Yes      | First name                                            |
    | `last_name`     | String(250)  | Yes      | Last name                                             |
    | `phone`         | String(250)  | Yes      | Phone number                                          |
    | `region_name`   | String(100)  | Yes      | Region/state name                                     |
    | `region_code`   | String(100)  | Yes      | Region/state code                                     |
    | `province_name` | String(250)  | Yes      | Province name                                         |
    | `province_code` | String(250)  | Yes      | Province code                                         |
    | `city`          | String(250)  | Yes      | City name                                             |
    | `country`       | String(250)  | Yes      | Country name                                          |
    | `postal_code`   | String(250)  | Yes      | Postal/ZIP code                                       |
    | `latitude`      | Decimal      | Yes      | Geographic latitude (-90 to 90, 15 decimal places)    |
    | `longitude`     | Decimal      | Yes      | Geographic longitude (-180 to 180, 15 decimal places) |

    **Response:**

    * Response status must be `200` in all cases
    * Response body:

    | Field               | Data type   | Optional                         | Description                                                                                                                                                        |
    | ------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `order_payment_id`  | String(250) | No, except `error_code` provided | Order payment identifier                                                                                                                                           |
    | `error_code`        | String      | Yes                              | If some error is occured error code should be provided. Example: `{"error_code": "INVALID_ORDER_DATA"}` All error codes can be found [here](/host-apps/ErrorCodes) |
    | `custom_attributes` | JSON        | Yes                              | JSON field for custom order attributes                                                                                                                             |

    **Request Example:**

    ```
        curl --location --request POST '[YOUR_SERVER_URL]/api/create-order-payment/'\
        --header 'Content-Type: application/json' \
        --header 'Authorization: Basic {{BASE64_ENCODED_CLIENT_ID_AND_CLIENT_SECRET}}' \
        --data-raw '{ "app_id": "{{MINIAPP_ID}}", "order": {
            "amount": "100.00",
            "currency": "USD",
            "miniapp_order_id": "{{ MINIAPP_ORDER_ID }}",
            "hostapp_user_id": "{{ HOSTAPP_USER_ID }}"
        }}'
    ```
  </Accordion>

  <Accordion title="2. Get Order Payment Status Endpoint">
    This endpoint is for Boxo platform to get order payment status

    **URL and METHOD**

    This endpoint must handle a HTTPS POST request
    Can be configured to be a GET method
    URL to endpoint must be provided in [Dashboard](https://dashboard.boxo.io/host-apps/)

    <img alt="AuthDiagram" />

    **Headers**

    | Key             | Value                                                                                                                                                           |
    | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `Authorization` | `<prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)>` or token from [Get access token](/host-apps/BoxoConnect#get-access-token) can be used instead |
    | `Content-type`  | `application/json`                                                                                                                                              |
    | `X-User-ID`     | `<Hostapp user reference>`                                                                                                                                      |

    Default `<prefix>`: `Token`. Access token prefix can be set in [Boxo Connect](https://dashboard.boxo.io/host-apps/).
    To use user access token from Boxo Connect as authorization token enable `Use access token` in [Dashboard](https://dashboard.boxo.io/host-apps/).
    `hostapp_client_id` and `hostapp_secret_key` must be provided in [Dashboard](https://dashboard.boxo.io/host-apps/)

    **Body**

    | Field              | Data type | Description              |
    | ------------------ | --------- | ------------------------ |
    | `app_id`           | String    | Miniapp identifier       |
    | `client_id`        | String    | Hostapp identifier       |
    | `order_payment_id` | String    | Order payment identifier |

    **Response**

    * Response status must be `200` in all cases
    * Response body

    | Field                 | Data type   | Optional                         | Description                                                                                                                                                     |
    | --------------------- | ----------- | :------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `app_id`              | String      | No, except `error_code` provided | Miniapp identifier                                                                                                                                              |
    | `client_id`           | String      | No, except `error_code` provided | Hostapp identifier                                                                                                                                              |
    | `order_payment_id`    | String      | No, except `error_code` provided | Order payment identifier                                                                                                                                        |
    | `payment_status`      | String(100) | No, except `error_code` provided | Order payment status: `in_process`, `paid`, `cancelled`, `failed`                                                                                               |
    | `payment_fail_reason` | String      | Yes                              | Order payment fail reason                                                                                                                                       |
    | `custom_attributes`   | JSON        | Yes                              | JSON field for custom order attributes                                                                                                                          |
    | `error_code`          | String      | Yes                              | If some error is occured error code should be provided. Example: `{"error_code": "ORDER_NOT_FOUND"}` All error codes can be found [here](/host-apps/ErrorCodes) |

    **Request Example**

    ```
        curl --location --request POST '[YOUR_SERVER_URL]/api/get-order-payment-status/'\
        --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}}", "order_payment_id": "{{ORDER_PAYMENT_ID}}"}'
    ```
  </Accordion>

  <Accordion title="3. Webhook Complete Order Payment">
    This endpoint is part of the Boxo Platform. It sends a request to the miniapp server to complete the order payment after the payment has been processed (refer to the step after 10 in the diagram).

    **URL and METHOD**

    This is HTTPS POST `/api/v1/orders/complete-order/` endpoint
    IP address of requesting services must be provided in [Dashboard](https://dashboard.boxo.io/host-apps/) for whitelisting or [Request Signaturing](/host-apps/Signaturing) must be enabled

    **Headers**

    | Key          | Value            |
    | ------------ | ---------------- |
    | Content-type | application/json |

    **Body**

    | Field                 | Data type   | Optional | Description                                                       |
    | --------------------- | ----------- | -------- | ----------------------------------------------------------------- |
    | `order_payment_id`    | String(250) | No       | Order payment identifier                                          |
    | `app_id`              | String      | No       | Miniapp identifier                                                |
    | `client_id`           | String      | No       | Hostapp identifier                                                |
    | `payment_status`      | String(100) | No       | Order payment status: `in_process`, `paid`, `cancelled`, `failed` |
    | `payment_fail_reason` | String      | Yes      | Order payment fail reason                                         |
    | `custom_attributes`   | JSON        | Yes      | Order custom attributes                                           |

    **Response:**

    * Response status will be `400` in case there is error\_code
    * Response body:

    | Field          | Data type | Description                                                                      |
    | -------------- | --------- | -------------------------------------------------------------------------------- |
    | code           | String    | Request result code example: `SUCCESS`                                           |
    | message        | String    | Result message                                                                   |
    | error\_code    | String    | Error code                                                                       |
    | error\_message | String    | Result error message. All error codes can be found [here](/host-apps/ErrorCodes) |

    **Request Example**

    ```
        curl --location --request POST '[BOXO_PLATFORM_SERVER_URL]/api/v1/orders/complete-order/' \
        --header 'Content-Type: application/json' \
        --data-raw '{
            "order_payment_id": "{{ORDER_PAYMENT_ID}}",
            "payment_status": "paid",
            "client_id": "{{CLIENT_ID}}",
            "app_id": "{{MINIAPP_ID}}"
        }'
    ```

    **Response Example**

    ```
        {
            "code": "SUCCESS",
            "message": "Success"
        }
    ```

    ```
        {
            "error_code": "ORDER_NOT_FOUND",
            "error_message": "No Order matches the given query."
        }
    ```
  </Accordion>
</Accordion>

## Pre-paid model

Platform partners can operate on a pre-paid basis. The partner team keeps a pre-paid balance with Boxo (topped up via wire transfer or crypto payment), and each paid order settles against that balance:

1. The pre-paid model is enabled for the partner team's organization (managed by Boxo).
2. Miniapps include `wholesale_total` (and optionally `wholesale_total_currency`) in each create order payment request. The platform rejects orders without it (`WHOLESALE_TOTAL_REQUIRED`) and orders exceeding the remaining balance (`INSUFFICIENT_BALANCE`).
3. When an order reaches the `paid` status, `wholesale_total` is deducted from the team balance.

The balance is deducted only for orders created by Boxo miniapps on **production** host apps — staging host apps never deduct the balance.

### Free orders without confirmation

Separately from the balance flow, a team-level setting `free_orders_without_confirmation` is available (managed by Boxo). It is a requirement for the pre-paid model:

* When enabled, orders created with `amount` = `0.00` are marked as `paid` on creation.
* Your create order payment endpoint is still called as usual and must return an `order_payment_id`, but the platform does not wait for your payment confirmation (webhook or status poll) for these orders.
* The pre-paid balance deduction of `wholesale_total` still applies to such orders.

<Accordion title="Setting up the SDK">
  Listening for Payment event

  <Tabs>
    <Tab title="iOS">
      ```swift theme={"system"}
      miniapp.delegate = self
      ...
      extension ViewController : MiniappDelegate {
          func didReceivePaymentEvent(miniapp: Miniapp, paymentData: PaymentData) {
              // Show payment processing screen and handle payment according to paymentData 
              // paymentData.amount
              // paymentData.miniappOrderId 
              // paymentData.currency
              // paymentData.orderPaymentId
              // Once payment is done, modify payment data and send result to mini app: 
              paymentData.status = "success" // change the payment status. "failed" in case payment failed, "cancelled" in case payment cancelled
              miniapp.sendPaymentEvent(paymentData: paymentData)
          }
      }
      ```
    </Tab>

    <Tab title="Android">
      Kotlin

      ```kotlin theme={"system"}
          Boxo.getMiniapp("[APP_ID]")
              .setPaymentEventListener { _, miniapp, paymentData ->
                  // Show payment processing screen and handle payment according to paymentData 
                  // paymentData.amount
                  // paymentData.miniappOrderId 
                  // paymentData.currency
                  // paymentData.orderPaymentId
                  // Once payment is done, modify payment data and send result to mini app: 
                  paymentData.status = "success" // change the payment status. "failed" in case payment failed, "cancelled" in case payment cancelled
                  miniapp.sendPaymentResult(paymentData)
              }.open()
      ```
    </Tab>

    <Tab title="Flutter">
      ```dart theme={"system"}
        @override
        void initState() {
          paymentSubscription = Boxo.paymentEvents().listen((PaymentEvent payment) async {
            Boxo.hideMiniapps(); // need to hide the miniapp before showing the payment page or popup
            // Show payment processing screen and handle payment according to paymentData
            // payment.amount
            // payment.miniappOrderId 
            // payment.currency
            // payment.orderPaymentId
            // Once payment is done, modify payment data and send result to miniapp: 
            NDialog(
              dialogStyle: DialogStyle(titleDivider: true),
              title: Text("Payment"),
              content: Text("Confirm payment"),
              actions: <Widget>[
                TextButton(
                    child: Text("Confirm"),
                    onPressed: () {
                      Navigator.pop(context);
                      //.. send request to handle payment to your backend
                      payment.status = 'success'; // change the payment status. "failed" in case payment failed, "cancelled" in case payment cancelled
                      Boxo.sendPaymentEvent(payment); // send payment result to miniapp
                      Boxo.openMiniapp(payment.appId); // need to open the miniapp
                    }),
                TextButton(
                    child: Text("Cancel"),
                    onPressed: () {
                      Navigator.pop(context);
                      payment.status = 'cancelled';
                      Boxo.sendPaymentEvent(payment);
                      Boxo.openMiniapp(payment.appId);
                    }),
              ],
            ).show(context);
          });
          Boxo.openMiniapp('[APP_ID]');
          super.initState();
        }
      ```
    </Tab>

    <Tab title="React Native">
      ```js theme={"system"}
        useEffect(() => {
          const paymentEventsSubscription = Boxo.paymentEvents.subscribe(
                (event) => {
                    // hide miniapp to return to the react-native app page
                   Boxo.hideMiniapps();
                    //payment data
                   const appId = event.app_id;
                   const paymentEvent = event.payment_event;
                   const orderPaymentId = paymentEvent.order_payment_id;
                   const amount = paymentEvent.amount;
                   const currency = paymentEvent.currency;
                   const extraParams = paymentEvent.extra_params;

                   // display payment screen
                   // after payment is completed
                   // open hidden miniapp 
                   Boxo.openMiniapp(appId);

                   //send payment result to miniapp
                   const newEvent = {
                     app_id: appId,
                     payment_event: {
                       ...event.payment_event,
                       status: // change the payment status. "failed" in case payment failed, "cancelled" in case payment cancelled
                     },
                   };
                   Boxo.paymentEvents.send(newEvent);
                },
                () => {},
              );
          return () => {
                  ...
                  paymentEventsSubscription();
              };
        }, []);
      ```
    </Tab>

    <Tab title="Capacitor">
      ```js theme={"system"}
      Boxo.addListener('payment_event', paymentData => {
        Boxo.hideMiniapps();
        // Show payment processing screen and handle payment according to paymentData 
        // paymentData.amount
        // paymentData.miniappOrderId 
        // paymentData.currency
        // paymentData.orderPaymentId
        // Once payment is done, modify payment data and send result to mini app: 
        paymentData.status = 'success'; // change the payment status. "failed" in case payment failed, "cancelled" in case payment cancelled
        Boxo.sendPaymentEvent(paymentData);
        Boxo.openMiniapp({ paymentData.appId });
      });
      ```
    </Tab>

    <Tab title="Expo">
      ```js theme={"system"}
      Boxo.addPaymentEventListener((paymentData) => {
        // Show payment processing screen and handle payment according to paymentData 
        // paymentData.amount
        // paymentData.miniappOrderId 
        // paymentData.currency
        // paymentData.orderPaymentId
        // Once payment is done, modify payment data and send result to mini app: 
        Boxo.hideMiniapps();
        paymentData.status = "success"; // change the payment status. "failed" in case payment failed, "cancelled" in case payment cancelled
        Boxo.sendPaymentEvent(paymentData);
        Boxo.openMiniapp({ appId: paymentData.appId })
      });
      ```
    </Tab>
  </Tabs>
</Accordion>


# Boxo SDK
Source: https://boxo.mintlify.app/host-apps/BoxoSDK



<Tabs>
  <Tab title="iOS SDK">
    ## iOS SDK

    <AccordionGroup>
      <Accordion title="Compatibility">
        Your project must target iOS 10 or later. Swift projects should use Swift 4.2 or later, and CocoaPods 1.8.1 or later is required.
      </Accordion>

      <Accordion title="Installation">
        <Tabs>
          <Tab title="Swift Package Manager installation">
            Add a package by selecting File → Add Packages… in Xcode's menu bar.

            Search for the BoxoSDK using the repo's URL:

            ```sh theme={"system"}
            https://github.com/Appboxo/boxo-ios-spm.git
            ```

            Next, set the **Dependency Rule** to be Up to Next Major Version.

            Then, select **Add Package**.
          </Tab>

          <Tab title="CocoaPods installation">
            Using [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) to create a Podfile if you don't already have one.

            ```sh theme={"system"}
            cd your-project-directory
            pod init
            ```

            Add the Boxo pod to your Podfile

            ```sh theme={"system"}
            pod 'BoxoSDK'
            ```

            Install the pods, then open your .xcworkspace file to see the project in Xcode:

            ```sh theme={"system"}
            pod install
            open your-project.xcworkspace
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="Launch miniapp">
        Import Boxo SDK in your ViewController:

        ```swift theme={"system"}
        import BoxoSDK 
        ```

        Initialize Boxo in your app by configuring a Boxo shared instance. Remember to replace `client_id` field with your `client_id`.

        ```swift theme={"system"}
        let config = Config(clientId: "client_id")
        Boxo.shared.setConfig(config: config)
        ```

        To launch the miniapp, you will need a UIViewController:

        #### UIKit

        To open miniapp write this code in your UIViewController:

        ```swift theme={"system"}
        let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
        miniapp.open(viewController: self)
        ```

        #### SwiftUI

        If you are using SwiftUI, you need to access the current UIViewController. There are many ways to obtain a UIViewController. Here is one of them:

        ```swift theme={"system"}
        struct ViewControllerFinder: UIViewControllerRepresentable {
            var onViewControllerFound: (UIViewController) -> Void

            func makeUIViewController(context: Context) -> UIViewController {
                let viewController = UIViewController()
                DispatchQueue.main.async {
                    self.onViewControllerFound(viewController)
                }
                return viewController
            }

            func updateUIViewController(_ uiViewController: UIViewController, context: Context) {}
        }
        ...
        struct ContentView: View {
            @State private var currentViewController: UIViewController?
            
            var body: some View {
                ViewControllerFinder { viewController in
                    currentViewController = viewController
                }
                Button(action: {
                    guard let currentViewController = currentViewController else { return }

                    let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
                    miniapp.open(viewController: currentViewController)
                }) {
                    Text("Open miniapp")
                }
            }
        }
        ```
      </Accordion>

      <Accordion title="SDK Configurations">
        Configure BoxoSDK with these settings to customize behavior, language, and UI elements.

        #### Language Configuration

        Use it to provide language to miniapp.  Default: 'en'

        ```swift theme={"system"}
        let config = Config(clientId: "CLIENT_ID")
        config.language = "en"
        Boxo.shared.setConfig(config: config)
        ```

        #### Consent Management

        ```swift theme={"system"}
        let config = Config(clientId: "CLIENT_ID")
        config.setUserId(id: "HOST_APP_USER_ID") //will be used for the consent screen
        Boxo.shared.setConfig(config: config)
        ```

        #### Miniapp Menu Customization

        ```swift theme={"system"}
        let config = Config(clientId: "CLIENT_ID")
        config.permissionsPage = false    // Hide "Settings"
        config.showClearCache = false   // Hide "Clear Cache"
        config.showAboutPage = false    // Show "About"
        Boxo.shared.setConfig(config: config)
        ```

        | **Parameter**     | **Description**         | **Default** |
        | :---------------- | :---------------------- | :---------- |
        | `permissionsPage` | Setting menu item       | `true`      |
        | `showClearCache`  | Clear Cache menu item   | `true`      |
        | `showAboutPage`   | About Miniapp menu item | `true`      |

        #### Sandbox Mode Configuration

        Control which miniapps are available in your development environment using the sandbox mode flag:

        ```swift theme={"system"}
        let config = Config(clientId: "CLIENT_ID")
        config.sandboxMode = true
        Boxo.shared.setConfig(config: config)
        ```

        Behavior: [Retrieve Miniapp List](/host-apps/BoxoSDK#retrieve-miniapp-list) will return miniapps with the statuses listed below.

        | **Sandbox Mode** | **Available Miniapp**  **Statuses** | **Use Case**                                                  |
        | :--------------- | :---------------------------------- | :------------------------------------------------------------ |
        | `true`           | `Approved` + `InTesting`            | Development environment - access to miniapps still in testing |
        | `false`          | `Approved` only                     | Production environment - only fully approved miniapps         |

        #### Theme Configuration

        Configure native component theming to match your app's design system or respect user preferences. The SDK provides comprehensive theme support for:

        * Splash screens
        * Native UI components
        * System dialogs and alerts

        **Theme Options**:

        | **Option** | **Description**                    |
        | :--------- | :--------------------------------- |
        | `SYSTEM`   | Automatically matches device theme |
        | `LIGHT`    | Forces light theme                 |
        | `DARK`     | Forces dark theme                  |

        Control theme behavior at both global and per-miniapp levels for maximum flexibility.

        **Global Theme (Affects all miniapps)**

        ```swift theme={"system"}
        let config = Config(clientId: "CLIENT_ID")
        config.theme = .System
        Boxo.shared.setConfig(config: config)
        ```

        **Per-Miniapp Theme Override**

        ```swift theme={"system"}
        // Override theme for specific miniapp
        miniapp.setConfig(config: MiniappConfig(theme: .Dark))
        ```
      </Accordion>

      <Accordion title="Miniapp Auth Flow">
        Handle authentication between your host app and miniapps:

        ```swift theme={"system"}
        miniapp.delegate = self
        ...
        extension ViewController : MiniappDelegate {
          func onAuth(miniapp: Miniapp, requiredFields: [String]) {
            // requiredFields - list of user data fields requested by the miniapp,
            // e.g. ["email", "phone"]. Empty if the miniapp doesn't require any.

            // 1. Fetch auth code from your backend
            let authCode = fetchAuthCodeFromBackend(requiredFields)

            // 2. Provide code to Miniapp
            miniapp.setAuthCode(authCode: authCode)
          }
        }
        ```

        If you don't need `requiredFields`, the shorter overload is still available:

        ```swift theme={"system"}
        miniapp.delegate = self
        ...
        extension ViewController : MiniappDelegate {
          func onAuth(miniapp: Miniapp) {
            miniapp.setAuthCode(authCode: fetchAuthCodeFromBackend())
          }
        }
        ```

        <Note>
          The `requiredFields` parameter is available starting from iOS SDK `1.29.0`.
        </Note>
      </Accordion>

      <Accordion title="User Logout & Data Clearing">
        When users log out of your host app, you must completely clear all miniapp session data

        ```swift theme={"system"}
        Boxo.shared.logout()
        ```
      </Accordion>

      <Accordion title="Miniapp URL Change Listener">
        To listen for any URL change events:

        ```swift theme={"system"}
        miniapp.delegate = self
        ...
        extension ViewController: MiniappDelegate {
            func didChangeUrlEvent(miniapp: Miniapp, url: URL) {
                // Listen for search URL
                if url.path.components(separatedBy: "/").contains("search") {
                    print("Search url: \(url)")
                }
            }
        }
        ```
      </Accordion>

      <Accordion title="Custom URL Parameters">
        Append additional query parameters to miniapp's initial URL for passing contextual data. This enables:

        * User-specific data injection
        * Campaign tracking
        * Contextual deep linking
        * A/B testing configuration

        ```swift theme={"system"}
        let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
        let miniappConfig = MiniappConfig()
        miniappConfig.setExtraParams(extraParams: ["user_id" : "u_12345", "campaign" : "summer_sale"])
        miniapp.setConfig(config: miniappConfig)
        ```

        Parameters will be automatically URL-encoded and appended as query parameters:

        ```
        https://miniapp.example.com?user_id=u_12345&campaign=summer_sale
        ```
      </Accordion>

      <Accordion title="Custom Event Handling">
        Establish two-way communication between your hostapp and miniapps using custom events. This system enables:

        * Real-time data exchange
        * User interaction tracking
        * Miniapp to host app callbacks
        * Dynamic content updates

        ```swift theme={"system"}
        miniapp.delegate = self
        ...
        func didReceiveCustomEvent(miniapp: Miniapp, customEvent: CustomEvent) {
            customEvent.payload = [
                "status" : "success",
                "code" : 200
            ]

            // Send response back to miniapp
            miniapp.sendCustomEvent(customEvent: customEvent)
        }
        ```
      </Accordion>

      <Accordion title="Adding Custom Action Menu">
        You can extend the miniapp’s native menu by adding your own custom action item by defining `.setCustomActionMenuItemImage`

        ```swift theme={"system"}
        let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
        let miniappConfig = MiniappConfig()
        miniappConfig.setCustomActionMenuItemImage(image: UIImage(named: "ic_custom_action_button"))
        miniapp.setConfig(config: miniappConfig)
        miniapp.delegate = self
        ...
        extension ViewController : MiniappDelegate {
            func didSelectCustomActionMenuItemEvent(miniapp: Miniapp) {
                // do something
            }
        }
        ```

        **Control Visibility:**

        ```
        // Hide the item
        miniapp.hideCustomActionMenuItem()

        // Show when needed
        miniapp.showCustomActionMenuItem()
        ```
      </Accordion>

      <Accordion title="Retrieve Miniapp List">
        Fetch the complete catalog of available miniapps with detailed metadata. This operation returns:

        * Basic miniapp information (id, name, description)
        * Logo
        * Category

        ```swift theme={"system"}
        Boxo.shared.getMiniapps { miniapps, error in
            miniapps.forEach { data in
                print(data.appId)
                print(data.name)
                print(data.longDescription)
                print(data.logo)
                print(data.category)
            }
        }
        ```
      </Accordion>

      <Accordion title="Splash Screen Configuration">
        When a miniapp is launched, Boxo displays a splash screen while the content is loading.
        You can customize the splash screen background color and the loading progress indicator for both **light** and **dark** themes.

        ### Background Colors

        Use the `splashBackgroundColors` property to configure splash background colors:

        ```swift theme={"system"}
        let config = Config(clientId: "CLIENT_ID")
        config.splashBackgroundColors = SplashBackgroundColors(light: UIColor.white, dark: UIColor.black)
        Boxo.shared.setConfig(config: config)
        ```

        ### Progress Bar Colors

        Use the `progressBarColors` property to configure progress bar colors:

        ```swift theme={"system"}
        let config = Config(clientId: "CLIENT_ID")
        config.progressBarColors = ProgressBarColors(lightIndicator: UIColor.red, lightTrack: UIColor.yellow, darkIndicator: UIColor.green, darkTrack: UIColor.orange)
        Boxo.shared.setConfig(config: config)
        ```

        ### Splash Behavior

        By default, the splash screen is shown automatically and hides when approximately 50% of the web content has loaded.

        You can control this behavior using `MiniappConfig`. For example, to disable the splash screen entirely:

        ```swift theme={"system"}
        let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
                    
        let miniappConfig = MiniappConfig()
        miniappConfig.enableSplash(isSplashEnabled: false)
        miniapp.setConfig(config: miniappConfig)

        miniapp.open(viewController: self)
        ```
      </Accordion>

      <Accordion title="Page Animation Configuration">
        Customize the animation effects to enhance the user experience by setting the appropriate page transition animation when opening a miniapp.

        You can choose from the following page animations:

        * `LEFT_TO_RIGHT` - The miniapp slides in from the left side of the screen to the right.
        * `RIGHT_TO_LEFT` - The miniapp slides in from the right side of the screen to the left.
        * `BOTTOM_TO_TOP`- The miniapp slides in from the bottom of the screen to the top.
        * `TOP_TO_BOTTOM` - The miniapp slides in from the top of the screen to the bottom.
        * `FADE_IN` - The miniapp fades in gradually from completely transparent to opaque.

        The `BOTTOM_TO_TOP` animation is the default page transition effect. You can easily change the animation to any of the other available options based on the user experience you want to provide.

        ```swift theme={"system"}
        let config = MiniappConfig()
        config.pageAnimation = PageAnimation.RIGHT_TO_LEFT

        let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
        miniapp.setConfig(config: config)
        miniapp.open(viewController: self)
        ```
      </Accordion>

      <Accordion title="Miniapp lifecycle events">
        Miniapp lifecycle events allow you to monitor key activities, such as `onLaunch`, `onResume`, `onPause`, `onClose`, `onError`, and `onUserInteraction`. These events help track the miniapp's behavior throughout its usage lifecycle.

        ```swift theme={"system"}
        miniapp.delegate = self
        ...
        extension ViewController: MiniappDelegate {
            func onLaunch(miniapp: Miniapp) {
                print("onLaunchMiniapp: \(miniapp.appId)")
            }

            func onResume(miniapp: Miniapp) {
                print("onResumeMiniapp: \(miniapp.appId)")
            }

            func onPause(miniapp: Miniapp) {
                print("onPauseMiniapp: \(miniapp.appId)")
            }

            func onClose(miniapp: Miniapp) {
                print("onCloseMiniapp: \(miniapp.appId)")
            }

            func onError(miniapp: Miniapp, message: String) {
                print("onErrorMiniapp: \(miniapp.appId) message: \(message)")
            }

            func onUserInteraction(miniapp: Miniapp) {
                print("onUserInteractionMiniapp: \(miniapp.appId)")
            }
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Android SDK">
    ## Android SDK

    Please see our [sample Android app](https://github.com/Appboxo/sample-android-hostapp) to learn more.

    <AccordionGroup>
      <Accordion title="Compatibility">
        Your project must target at least Android 5.0 (API level 21) or higher.

        The host Activity must extend `FragmentActivity` (for example, `AppCompatActivity`). A plain `Activity` without fragment support is not supported.
      </Accordion>

      <Accordion title="Installation">
        Latest version: ![Maven Central Version](https://img.shields.io/maven-central/v/io.boxo.sdk/boxo-android)

        To install Boxo SDK, add `io.boxo.sdk:boxo-android` to the `dependencies` block of your [app/build.gradle](https://developer.android.com/studio/build/dependencies) file:

        ```kotlin app/build.gradle.kts theme={"system"}
        ...
        dependencies {
        	implementation("io.boxo.sdk:boxo-android:1.x.x")
        }
        ```
      </Accordion>

      <Accordion title="Launch miniapp">
        1. Add to your existing `Application` class or create a new one if you don't have an `Application` class yet.

           ```kotlin MyApplication.kt theme={"system"}
           import android.app.Application
           import io.boxo.sdk.Boxo
           import io.boxo.sdk.Config

           class MyApplication : Application() {
               override fun onCreate() {
                   super.onCreate()
                   Boxo.init(this)
                       .setConfig(
                           Config.Builder()
                               .setClientId("client_id")
                               .build()
                       )
               }
           }
           ```
        2. Then register it in AndroidManifest.xml:

           ```AndroidManifest.xml theme={"system"}
           <application
           	android:name=".MyApplication"
           	...>
           ```
        3. Open miniapp

           ```kotlin theme={"system"}
           val miniapp = Boxo.getMiniapp(appId)
           miniapp.open()
           ```

        ```kotlin MainActivity.kt [expandable] theme={"system"}
        package io.boxo.launchminiapp

        import android.os.Bundle
        import androidx.fragment.app.FragmentActivity
        import androidx.activity.compose.setContent
        import androidx.activity.enableEdgeToEdge
        import androidx.compose.foundation.layout.Arrangement
        import androidx.compose.foundation.layout.Column
        import androidx.compose.foundation.layout.Spacer
        import androidx.compose.foundation.layout.fillMaxSize
        import androidx.compose.foundation.layout.fillMaxWidth
        import androidx.compose.foundation.layout.height
        import androidx.compose.foundation.layout.padding
        import androidx.compose.material3.Button
        import androidx.compose.material3.MaterialTheme.typography
        import androidx.compose.material3.Text
        import androidx.compose.runtime.Composable
        import androidx.compose.ui.Alignment
        import androidx.compose.ui.Modifier
        import androidx.compose.ui.tooling.preview.Preview
        import androidx.compose.ui.unit.dp
        import io.boxo.launchminiapp.ui.theme.LaunchminiappTheme
        import io.boxo.sdk.Boxo

        class MainActivity : FragmentActivity() {
            override fun onCreate(savedInstanceState: Bundle?) {
                super.onCreate(savedInstanceState)
                enableEdgeToEdge()
                setContent {
                    LaunchminiappTheme {
                        WelcomeScreen(
                            onOpenMiniappClick = {
                                Boxo.getMiniapp("appId").open()
                            }
                        )
                    }
                }
            }
        }

        @Composable
        fun WelcomeScreen(
            onOpenMiniappClick: () -> Unit,
            modifier: Modifier = Modifier
        ) {
            Column(
                modifier = modifier
                    .fillMaxSize()
                    .padding(24.dp),
                horizontalAlignment = Alignment.CenterHorizontally,
                verticalArrangement = Arrangement.Center
            ) {
                Text(
                    text = "Welcome",
                    style = typography.headlineMedium,
                    modifier = Modifier.padding(bottom = 16.dp)
                )
                Spacer(modifier = modifier.height(64.dp))
                Button(
                    onClick = onOpenMiniappClick,
                    modifier = Modifier
                        .fillMaxWidth()
                        .height(52.dp)
                ) {
                    Text("Open Miniapp")
                }
            }
        }

        @Preview(showBackground = true)
        @Composable
        fun WelcomeScreenPreview() {
            LaunchminiappTheme {
                WelcomeScreen(
                    onOpenMiniappClick = {}
                )
            }
        }
        ```
      </Accordion>

      <Accordion title="SDK Configurations">
        Configure BoxoSDK with these settings to customize behavior, language, and UI elements.

        #### Language Configuration

        Use it to provide language to miniapp.  Default: 'en'

        ```
        Boxo.init(this)
            .setConfig(
                Config.Builder()
                    .setLanguage("en")
                    .build()
            )
        ```

        #### System Behavior

        ```
        Boxo.setConfig(
            Config.Builder()
                .debug(BuildConfig.DEBUG)
                .build()
            )
        ```

        | **Parameter** | **Type** | **Description**                             | **Default** |
        | :------------ | :------- | :------------------------------------------ | :---------- |
        | `debug`       | Boolean  | Enables WebView debugging (Chrome DevTools) | `false`     |

        #### Miniapp Menu Customization

        ```
        Boxo.setConfig(
            Config.Builder()
                .permissionsPage(false)  // Hide "Settings"
                .showClearCache(false)   // Hide "Clear Cache"
                .showAboutPage(true)    // Show "About"
                .build()
            )
        ```

        | **Parameter**     | **Description**         | **Default** |
        | :---------------- | :---------------------- | :---------- |
        | `permissionsPage` | Setting menu item       | `true`      |
        | `showClearCache`  | Clear Cache menu item   | `true`      |
        | `showAboutPage`   | About Miniapp menu item | `true`      |

        #### Sandbox Mode Configuration

        Control which miniapps are available in your development environment using the sandbox mode flag:

        ```kotlin theme={"system"}
        Boxo.setConfig(
            Config.Builder()
                .sandboxMode(true)  // Enable sandbox mode
                .build()
        )
        ```

        Behavior: [Retrieve Miniapp List](/host-apps/BoxoSDK#retrieve-miniapp-list) will return miniapps with the statuses listed below.

        | **Sandbox Mode** | **Available Miniapp**  **Statuses** | **Use Case**                                                  |
        | :--------------- | :---------------------------------- | :------------------------------------------------------------ |
        | `true`           | `Approved` + `InTesting`            | Development environment - access to miniapps still in testing |
        | `false`          | `Approved` only                     | Production environment - only fully approved miniapps         |

        #### Theme Configuration

        Configure native component theming to match your app's design system or respect user preferences. The SDK provides comprehensive theme support for:

        * Splash screens
        * Native UI components
        * System dialogs and alerts

        **Theme Options**:

        | **Option** | **Description**                    |
        | :--------- | :--------------------------------- |
        | `SYSTEM`   | Automatically matches device theme |
        | `LIGHT`    | Forces light theme                 |
        | `DARK`     | Forces dark theme                  |

        Control theme behavior at both global and per-miniapp levels for maximum flexibility.

        **Global Theme (Affects all miniapps)**

        ```kotlin theme={"system"}
        Boxo.setConfig(Config.Builder()
            ...
        	.setTheme(Config.Theme.SYSTEM)  // DEFAULT: Follows system setting
            .build())
        ```

        **Per-Miniapp Theme Override**

        ```kotlin theme={"system"}
        // Override theme for specific miniapp
        Boxo.getMiniapp(appId)
            .setConfig(MiniappConfig.Builder()
                .setTheme(Config.Theme.LIGHT)  // Overrides global theme
                .build())
            .open()
        ```
      </Accordion>

      <Accordion title="Miniapp Auth Flow">
        Handle authentication between your host app and miniapps:

        ```kotlin theme={"system"}
        miniapp.setAuthListener { _, miniapp, requiredFields ->
            // requiredFields - list of user data fields requested by the miniapp,
            // e.g. ["email", "phone"]. Empty if the miniapp doesn't require any.

            // 1. Fetch auth code from your backend
            val authCode = fetchAuthCodeFromBackend(requiredFields)

            // 2. Provide code to Miniapp
            miniapp.setAuthCode(authCode)
        }
        ```

        If you don't need `requiredFields`, the shorter overload is still available:

        ```kotlin theme={"system"}
        miniapp.setAuthListener { _, miniapp ->
            miniapp.setAuthCode(fetchAuthCodeFromBackend())
        }
        ```

        <Note>
          The `requiredFields` parameter is available starting from Android SDK `1.43.0`.
        </Note>
      </Accordion>

      <Accordion title="User Logout & Data Clearing">
        When users log out of your host app, you must completely clear all miniapp session data

        ```kotlin theme={"system"}
        Boxo.logout()
        ```
      </Accordion>

      <Accordion title="Miniapp URL Change Listener">
        To listen for any URL change events use .setUrlChangeListener:

        ```kotlin theme={"system"}
        Boxo.getMiniapp(appId)
            .setUrlChangeListener { _, miniapp, uri ->
                Log.e("URL Path", uri.path)
                uri.queryParameterNames.forEach {
                    Log.e("URL params", "$it = ${uri.getQueryParameter(it)}")
                }
            }
            .open()
        ```
      </Accordion>

      <Accordion title="Custom URL Parameters">
        Append additional query parameters to miniapp's initial URL for passing contextual data. This enables:

        * User-specific data injection
        * Campaign tracking
        * Contextual deep linking
        * A/B testing configuration

        **Basic Implementation**

        ```kotlin theme={"system"}
        Boxo.getMiniapp(appId)
            .setConfig(
                MiniappConfig.Builder()
                    .setExtraUrlParams(
                        mapOf(
                            "user_id" to "u_12345",
                            "campaign" to "summer_sale"
                        )
                    )
                    .build()
            )
            .open()
        ```

        Parameters will be automatically URL-encoded and appended as query parameters:

        ```
        https://miniapp.example.com?user_id=u_12345&campaign=summer_sale
        ```
      </Accordion>

      <Accordion title="Custom Event Handling">
        Establish two-way communication between your hostapp and miniapps using custom events. This system enables:

        * Real-time data exchange
        * User interaction tracking
        * Miniapp to host app callbacks
        * Dynamic content updates

        ```kotlin theme={"system"}
        miniapp.setCustomEventListener { _, miniapp, event ->
            when (event.name) {
                "userAction" -> handleUserAction(event.payload)
                "requestData" -> sendResponseData(miniapp, event)
                else -> Log.w("CustomEvent", "Unhandled event: ${event.name}")
            }
        }

        // Send response back to miniapp
        private fun sendResponseData(miniapp: Miniapp, event: CustomEvent) {
            event.payload = mapOf(
                "status" to "success",
                "code" to 200
            )
            miniapp.sendEvent(event)
        }
        ```
      </Accordion>

      <Accordion title="Adding Custom Action Menu">
        You can extend the miniapp's native menu by adding your own custom action item. This is achieved through two simple steps:

        1. **Define the Menu Item**\
           Use `.setCustomActionMenuItem()` to specify your custom button's appearance
        2. **Handle User Interactions**\
           Implement `.setCustomActionMenuItemClickListener()` to respond when users tap your button

        ```kotlin theme={"system"}
        Boxo.getMiniapp(appId)
            .setConfig(
                MiniappConfig.Builder()
                    .setCustomActionMenuItem(R.drawable.ic_custom_menu)
                    .build()
            )
            .setCustomActionMenuItemClickListener { _, miniapp ->
                // do something
            }
            .open()
        ```

        **Control Visibility:**

        ```
        // Hide the item
        miniapp.hideCustomActionMenuItem()

        // Show when needed
        miniapp.showCustomActionMenuItem()
        ```
      </Accordion>

      <Accordion title="Retrieve Miniapp List">
        Fetch the complete catalog of available miniapps with detailed metadata. This asynchronous operation returns:

        * Basic miniapp information (id, name, description)
        * Logo
        * Category

        ```kotlin theme={"system"}
        Boxo.getMiniapps(object: MiniappListCallback{
                    override fun onFailure(e: Exception) {
                       Log.e("MiniappList", "Failed to load miniapps")
                    }

                    override fun onSuccess(miniapps: List<MiniappData>) {
                        miniapps.forEach { data->
                          print(data.appId)
                          print(data.name)
                          print(data.description)
                          print(data.logo)
                          print(data.category)
                        }
                    }
                })
        ```
      </Accordion>

      <Accordion title="Splash Screen Configuration">
        When a miniapp is launched, Boxo displays a splash screen while the content is loading.
        You can customize the splash screen background color and the loading progress indicator for both **light** and **dark** themes.

        ### Background Colors

        Use the `setSplashBackgroundColors` method in `Config.Builder` to configure splash background colors:

        ```kotlin theme={"system"}
        Boxo.init(this)
            .setConfig(
                Config.Builder()
                    .setSplashBackgroundColors(
                        light = "#6A22C9".toColorInt(),
                        dark  = "#C495FF".toColorInt()
                    )
                    .build()
            )
        ```

        ### Progress Bar Colors

        Use the `setProgressBarColors` method in `Config.Builder` to configure progress bar colors:

        ```kotlin theme={"system"}
        Boxo.init(this)
            .setConfig(
                Config.Builder()
                    .setProgressBarColors(
                        lightIndicator = "#000000".toColorInt(),
                        lightTrack     = "#DAD5D5".toColorInt(),
                        darkIndicator  = "#006DD1".toColorInt(),
                        darkTrack      = "#FFFFFF".toColorInt()
                    )
                    .build()
            )
        ```

        ### Splash Behavior

        By default, the splash screen is shown automatically and hides when approximately 50% of the web content has loaded.

        You can control this behavior using `MiniappConfig`. For example, to disable the splash screen entirely:

        ```kotlin theme={"system"}
        Boxo.getMiniapp(appId)
            .setConfig(
                MiniappConfig.Builder()
                    .enableSplash(false) // Disable splash screen
                    .build()
            )
            .open()
        ```
      </Accordion>

      <Accordion title="Page Animation Configuration">
        Customize the animation effects to enhance the user experience by setting the appropriate page transition animation when opening a miniapp.

        You can choose from the following page animations:

        * `LEFT_TO_RIGHT` - The miniapp slides in from the left side of the screen to the right.
        * `RIGHT_TO_LEFT` - The miniapp slides in from the right side of the screen to the left.
        * `BOTTOM_TO_TOP`- The miniapp slides in from the bottom of the screen to the top.
        * `TOP_TO_BOTTOM` - The miniapp slides in from the top of the screen to the bottom.
        * `FADE_IN` - The miniapp fades in gradually from completely transparent to opaque.

        The `BOTTOM_TO_TOP` animation is the default page transition effect. You can easily change the animation to any of the other available options based on the user experience you want to provide.

        ```
        Boxo.getMiniapp(appId)
            .setConfig(
                MiniappConfig.Builder()
                    ...
        			// Set the page animation to slide from right to left
                    .pageAnimation(PageAnimation.RIGHT_TO_LEFT)
                    .build()
            )
            .open()
        ```
      </Accordion>

      <Accordion title="Miniapp Lifecycle Events">
        Track key moments in a miniapp's execution by implementing the `LifecycleListener`. The callbacks `onLaunch`, `onResume`, `onPause`, `onClose`, `onError`, and `onUserInteraction` let you monitor the miniapp lifecycle and user touches.

        ```kotlin theme={"system"}
        miniapp.setLifecycleListener(object : Miniapp.LifecycleListener {
            override fun onLaunch(miniapp: Miniapp) {
        		// Triggers when miniapp begins launching via miniapp.open()
                // Ideal for analytics tracking and initial setup
            }

            override fun onResume(miniapp: Miniapp) {
        		// Called when miniapp returns to foreground
                // Use to resume paused operations
            }

            override fun onPause(miniapp: Miniapp) {
        		// Called when miniapp loses foreground focus
                // Pause ongoing operations
            }

            override fun onClose(miniapp: Miniapp) {
                // Triggers when:
                // - User taps close button
                // - Miniapp activity is destroyed
                // Clean up resources and finalize analytics
            }

            override fun onError(miniapp: Miniapp, message: String) {
                // Called when miniapp fails to launch due to internet connection issues
            }

            override fun onUserInteraction(miniapp: Miniapp) {
                // Called whenever a touch event is dispatched to the miniapp page
                // Useful for custom idle timeouts
            }
        })
        ```
      </Accordion>

      <Accordion title="Obfuscation Rules">
        To protect intellectual property, deter reverse engineering, and enhance code security

        ```js theme={"system"}
        -keepclassmembers class io.boxo.js.jsInterfaces.BoxoJsInterface{
            public *; 
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Flutter">
    ## Flutter

    A [Flutter plugin](https://pub.dev/packages/appboxo_sdk) to integrate Boxo for iOS and Android. Please see our [sample Flutter app](https://github.com/Appboxo/sample-flutter-app) to learn more.

    <AccordionGroup>
      <Accordion title="Installation">
        ![Pub Version](https://img.shields.io/pub/v/appboxo_sdk)

        Run this command:
        With Flutter:

        ```bash theme={"system"}
        flutter pub add appboxo_sdk
        ```

        This will add a line like this to your package's pubspec.yaml (and run an implicit <code>flutter pub get</code>):

        dependencies:
        appboxo\_sdk: ^0.8.0

        Add this line to android/gradle.properties

        ```
          android.enableJetifier=true
        ```
      </Accordion>

      <Accordion title="Launch Miniapp">
        ```
        import 'package:appboxo_sdk/boxo.dart';
        ```

        ```
        Boxo.setConfig( clientId: '[client_id]');
        ```

        ```
        Boxo.openMiniapp( appId );
        ```
      </Accordion>

      <Accordion title="Set Config">
        ```dart theme={"system"}
        import 'package:appboxo_sdk/boxo.dart';

        Boxo.setConfig(
            clientId: '[client_id]', // your Boxo client_id
            userId: '[hostapp_user_id]',// will be used for the consent screen
            language: 'en', // use it to provide language to miniapp. by default 'en'
            sandboxMode: false, // sandbox mode. By default 'false'
            theme: 'dark', // (optional) miniapp theme "dark" | "light" (by default is system theme),
            isDebug: true,  // by default 'false', enables webview debugging
            showClearCache: true,  // use it to hide "Clear cache" from Miniapp menu, by default 'true'
            showPermissionsPage: true, // use it to hide "Settings" from Miniapp menu, by default 'true'
            showAboutPage: true,  // show/hide "About page" on Miniapp menu, by default 'true'
            splashScreenOptions: {  // (optional) to customize the splash screen background and the loading progress indicator
                  'light_progress_indicator': '#000000',
                  'light_progress_track': '#FFFFFF',
                  'light_background': '#FFFFF',
                  'dark_progress_indicator': '#FFFFFF',
                  'dark_progress_track': '#000000',
                  'dark_background': '#000000'
                }
        );

        Boxo.openMiniapp(
            "[miniapp_id]", // your miniapp id
            data: {'key': 'value'}, // (optional) data as Map that is sent to miniapp
            theme: 'dark', // (optional) miniapp theme "dark" | "light" (by default is system theme)
            enableSplash:  false // (optional) to skip splash screen. if enabled, the splash screen will be hidden when 50% of web content is loaded. Otherwise, when the web page starts loading. By default is enabled.
        );

        Boxo.hideMiniapps(); //use it to close all miniapp screens

        Boxo.logout(); //On logout from your app, call it to clear all miniapps data.
        ```
      </Accordion>

      <Accordion title="Splash Screen Configuration">
        When a miniapp is launched, Boxo displays a splash screen while the content is loading.
        You can customize the splash screen background color and the loading progress indicator for both **light** and **dark** themes.

        ### Background and progress colors

        Pass `splashScreenOptions` to `Boxo.setConfig`. Keys use snake case and hex color strings:

        | Key                        | Description                           |
        | :------------------------- | :------------------------------------ |
        | `light_background`         | Splash background in light appearance |
        | `dark_background`          | Splash background in dark appearance  |
        | `light_progress_indicator` | Progress indicator color (light)      |
        | `light_progress_track`     | Progress track color (light)          |
        | `dark_progress_indicator`  | Progress indicator color (dark)       |
        | `dark_progress_track`      | Progress track color (dark)           |

        ```dart theme={"system"}
        Boxo.setConfig(
          clientId: '[client_id]',
          splashScreenOptions: {
            'light_background': '#FFFFFF',
            'dark_background': '#000000',
            'light_progress_indicator': '#000000',
            'light_progress_track': '#FFFFFF',
            'dark_progress_indicator': '#FFFFFF',
            'dark_progress_track': '#000000',
          },
        );
        ```

        ### Splash behavior

        By default, the splash screen is shown automatically and hides when approximately 50% of the web content has loaded.

        Pass `enableSplash` to `Boxo.openMiniapp` to control it for a single launch (for example, to turn it off):

        ```dart theme={"system"}
        Boxo.openMiniapp(
          '[miniapp_id]',
          enableSplash: false,
        );
        ```
      </Accordion>

      <Accordion title="Page Animation Configuration">
        Customize the animation effects when opening a miniapp by passing `pageAnimation` to `Boxo.openMiniapp`.

        You can choose from the following page animations:

        * `LEFT_TO_RIGHT` - The miniapp slides in from the left side of the screen to the right.
        * `RIGHT_TO_LEFT` - The miniapp slides in from the right side of the screen to the left.
        * `BOTTOM_TO_TOP` - The miniapp slides in from the bottom of the screen to the top.
        * `TOP_TO_BOTTOM` - The miniapp slides in from the top of the screen to the bottom.
        * `FADE_IN` - The miniapp fades in gradually from completely transparent to opaque.

        The `BOTTOM_TO_TOP` animation is the default page transition effect.

        ```dart theme={"system"}
        Boxo.openMiniapp(
          '[miniapp_id]',
          pageAnimation: 'RIGHT_TO_LEFT',
        );
        ```
      </Accordion>

      <Accordion title="Sandbox mode">
        sandboxMode: it should open miniapps in "Approved" and "InTesting" statuses [List of miniapps](/host-apps/BoxoSDK#get-list-of-miniapps-3) returns:

        * when true, miniapps in "Approved" and "InTesting" statuses
        * when false, miniapps only in "Approved" status
      </Accordion>

      <Accordion title="Get list of miniapps">
        ```dart theme={"system"}
        Boxo.miniapps().listen((result) {
          result.miniapps?.forEach((data) {
            print(data.appId);
            print(data.name);
            print(data.description);
            print(data.logo);
            print(data.category);
          });
          print('error - ${result.error}');
        });

        Boxo.getMiniapps();
        ```
      </Accordion>

      <Accordion title="To listen miniapp lifecycle events">
        ```dart theme={"system"}
        import 'package:flutter/material.dart';
        import 'package:appboxo_sdk/boxo.dart';

        void main() => runApp(MyApp());

        class MyApp extends StatefulWidget {
          @override
          _MyAppState createState() => _MyAppState();
        }

        class _MyAppState extends State<MyApp> {
          Future<void> Function() subscription;

          @override
          void dispose() {
            subscription();
            super.dispose();
          }

          @override
          void initState() {
            super.initState();
            subscription = Boxo.lifecycleHooksListener(
              onAuth: (appId) { // called when authorization flow starts
                //sample
                http.get(Uri.parse('get_auth_code_url'))
                        .then((response) {
                  if (response.statusCode >= 400) {
                    print('Error fetching auth code: ${response.body}');
                    Boxo.setAuthCode(appId, "");
                  } else {
                    Boxo.setAuthCode(appId, json.decode(response.body)["auth_code"]);
                  }
                });
              },
              onLaunch: (appId) {
                print(appId);
                print('onLaunch');
              },
              onResume: (appId) {
                print(appId);
                print('onResume');
              },
              onPause: (appId) {
                print(appId);
                print('onPause');
              },
              onClose: (appId) {
                print(appId);
                print('onClose');
              },
              onError: (appId, error) {
                print(appId);
                print(error);
                print('onError');
              },
              onUserInteraction: (appId) {
                print(appId);
                print('onUserInteraction');
              },
            );
          }

          @override
          Widget build(BuildContext context) {
            return MaterialApp(
              debugShowCheckedModeBanner: false,
              home: Scaffold(
                appBar: AppBar(
                  title: const Text('Boxo SDK Test'),
                ),
                body: Center(
                  child: MaterialButton(
                    onPressed: () {
                      Boxo.openMiniapp("[miniapp_id]"); //launch miniapp by id
                    },
                    padding: const EdgeInsets.all(16),
                    color: Colors.blue,
                    child: const Text(
                      'Run miniapp',
                      style: const TextStyle(
                        color: Colors.white,
                        fontSize: 16,
                      ),
                    ),
                  ),
                ),
              ),
            );
          }
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="React Native">
    ## React Native

    A react native wrapper over Boxo SDK for iOS and Android.

    <AccordionGroup>
      <Accordion title="Installation">
        ```
        yarn add @appboxo/react-native-sdk
        ```

        or

        ```
        npm install @appboxo/react-native-sdk
        ```

        Please make sure the "@appboxo/react-native-sdk" dependency is linked, if not please run:

        ```
        react-native link @appboxo/react-native-sdk
        ```

        Add this line to android/gradle.properties

        ```
          android.enableJetifier=true
        ```

        Next for iOS:

        ```
        cd ios && pod install
        ```
      </Accordion>

      <Accordion title="Launch Miniapp">
        ```
        import Boxo from '@appboxo/react-native-sdk';
        ```

        ```
        Boxo.setConfig( clientId );
        ```

        ```
        Boxo.openMiniapp( appId );
        ```
      </Accordion>

      <Accordion title="Usage">
        ```clike theme={"system"}
        import React from 'react';
        import Boxo from '@appboxo/react-native-sdk';
        import { StyleSheet, View, Button } from 'react-native';

        export default function App() {

          React.useEffect(() => {
            Boxo.setConfig(
              '[client_id]', { // your Boxo client_id
                userId: [hostapp_user_id], // will be used for the consent screen
                language: 'en', // to provide language to miniapp. by default 'en'
                sandboxMode: false, // sandbox mode. By default 'false'
                theme: 'light', // (optional) miniapp theme "dark" | "light" (by default is "system")
                isDebug: true,  // by default 'false', enables webview debugging
                showClearCache: true,  // use it to hide "Clear cache" from Miniapp menu, by default 'true'     
                showPermissionsPage: true, // use it to hide "Settings" from Miniapp menu, by default 'true'
                showAboutPage: true,  // show/hide "About page" on Miniapp menu, by default 'true'
                splashScreenOptions: {  // (optional) to customize the splash screen background and the loading progress indicator
                   lightProgressIndicator: "#000000",
                   lightProgressTrack: "#FFFFFF",
                   darkProgressIndicator: "#FFFFFF",
                   darkProgressTrack: "#000000",
                   lightBackground:"#FFFFFF",
                   darkBackground:"#000000"
                }
              }
            );
          }, [])

          const handleOpenMiniapp = () => {
            const options = {
              data: {'key': 'value'},           // (optional) data as {[key: string]: any} that is passed to miniapp in `.getInitData` call
              theme: 'dark',                    // (optional) miniapp theme "dark" | "light" | "system" (by default is value of "theme" argument in setConfig function)
              extraUrlParams: {param: 'test'},  // (optional) extra query params to append to miniapp URL (like: http://miniapp-url.com/?param=test)
              pageAnimation: 'RIGHT_TO_LEFT',   // (optional) launch transition, see Page Animation Configuration below
            }
            Boxo.openMiniapp(
              '[miniapp_id]',           // miniapp ID to be launched
              options                   // (optional) options
            );
          }

          return (
            <View style={styles.container}>
              <Button
                color="#841584"
                title="Launch miniapp"
                onPress={handleOpenMiniapp}
                accessibilityLabel="Launch miniapp"
            />
            </View>
          );
        }

        const styles = StyleSheet.create({
          container: {
            flex: 1,
            alignItems: 'center',
            backgroundColor: '#fff',
            justifyContent: 'center',
          },
        });
        ```
      </Accordion>

      <Accordion title="Splash Screen Configuration">
        When a miniapp is launched, Boxo displays a splash screen while the content is loading.
        You can customize the splash screen background color and the loading progress indicator for both **light** and **dark** themes.

        ### Background and progress colors

        Use `splashScreenOptions` in the second argument of `Boxo.setConfig`:

        | Property                 | Description                           |
        | :----------------------- | :------------------------------------ |
        | `lightBackground`        | Splash background in light appearance |
        | `darkBackground`         | Splash background in dark appearance  |
        | `lightProgressIndicator` | Progress indicator color (light)      |
        | `lightProgressTrack`     | Progress track color (light)          |
        | `darkProgressIndicator`  | Progress indicator color (dark)       |
        | `darkProgressTrack`      | Progress track color (dark)           |

        ```clike theme={"system"}
        Boxo.setConfig('[client_id]', {
          splashScreenOptions: {
            lightBackground: '#FFFFFF',
            darkBackground: '#000000',
            lightProgressIndicator: '#000000',
            lightProgressTrack: '#FFFFFF',
            darkProgressIndicator: '#FFFFFF',
            darkProgressTrack: '#000000',
          },
        });
        ```

        ### Splash behavior

        By default, the splash screen is shown automatically and hides when approximately 50% of the web content has loaded.

        Set `enableSplash` in the options object passed to `Boxo.openMiniapp` (for example, `false` to disable the splash for that launch):

        ```clike theme={"system"}
        Boxo.openMiniapp('[miniapp_id]', {
          enableSplash: false,
        });
        ```
      </Accordion>

      <Accordion title="Page Animation Configuration">
        Customize the animation effects when opening a miniapp by setting `pageAnimation` in the second argument of `Boxo.openMiniapp`.

        You can choose from the following page animations:

        * `LEFT_TO_RIGHT` - The miniapp slides in from the left side of the screen to the right.
        * `RIGHT_TO_LEFT` - The miniapp slides in from the right side of the screen to the left.
        * `BOTTOM_TO_TOP` - The miniapp slides in from the bottom of the screen to the top.
        * `TOP_TO_BOTTOM` - The miniapp slides in from the top of the screen to the bottom.
        * `FADE_IN` - The miniapp fades in gradually from completely transparent to opaque.

        The `BOTTOM_TO_TOP` animation is the default page transition effect.

        ```clike theme={"system"}
        Boxo.openMiniapp('[miniapp_id]', {
          pageAnimation: 'RIGHT_TO_LEFT',
        });
        ```
      </Accordion>

      <Accordion title="Miniapp lifecycle events">
        <Tip>
          **Important**
          Miniapp lifecycle events available in 1.0.8+ versions
        </Tip>

        ```clike theme={"system"}
        import React from 'react';
        import Boxo from '@appboxo/react-native-sdk';
        import { StyleSheet, View, Button } from 'react-native';

        export default function App() {

          React.useEffect(() => {
            Boxo.setConfig('[client_id]', false); //set your Boxo client id
            
            const subscription = Boxo.lifecycleHooksListener({
              onLaunch: (appId: string) => console.log('onLaunch', appId),  // called when the miniapp will launch with openMiniapp(...)
              onResume: (appId: string) => console.log('onResume', appId),  // called when the miniapp will start interacting with the user
              onPause: (appId: string) => console.log('onPause', appId),    // called when clicked close button in miniapp
              onClose: (appId: string) => console.log('onClose', appId),    // called when the miniapp loses foreground state
              onAuth: (appId: string) => console.log('onAuth', appId),    // called when authorization flow starts
              onError: (appId: string, error: string) => console.log('onError', appId, error),  // handle error
              onUserInteraction: (appId: string) => console.log('onUserInteraction', appId),  // called on touch events in the miniapp (e.g. custom idle timeouts)
            });

            return () => subscription();
          }, [])

          const handleOpenMiniapp = () => {
            Boxo.openMiniapp('[miniapp_id]');           // miniapp ID to be launched
          }

          return (
            <View style={styles.container}>
              <Button
                color="#841584"
                title="Launch miniapp"
                onPress={handleOpenMiniapp}
                accessibilityLabel="Launch miniapp"
            />
            </View>
          );
        }

        const styles = StyleSheet.create({
          container: {
            flex: 1,
            alignItems: 'center',
            backgroundColor: '#fff',
            justifyContent: 'center',
          },
        });
        ```
      </Accordion>

      <Accordion title="Append custom params to miniapp URL">
        <Tip>
          **Important**
          Custom params available in 1.0.26+ versions
        </Tip>

        To append any custom data as URL param to miniapp's URL use extraUrlParams:

        ```clike theme={"system"}
        const options = {
          extraUrlParams: {param: 'test'}  // (optional) extra query params to append to miniapp URL (like: http://miniapp-url.com/?param=test)
        }
        Boxo.openMiniapp(
          '[miniapp_id]',           // miniapp ID to be launched
          options                   // (optional) options
        );
        ```
      </Accordion>

      <Accordion title="Sandbox mode">
        sandboxMode: it should open miniapps in "Approved" and "InTesting" statuses [List of miniapps](/host-apps/BoxoSDK#get-list-of-miniapps-4) returns:

        * when true, miniapps in "Approved" and "InTesting" statuses
        * when false, miniapps only in "Approved" status
      </Accordion>

      <Accordion title="Get list of miniapps">
        ```clike theme={"system"}
        React.useEffect(() => {
            const miniappListSubscription = Boxo.miniapps.subscribe((miniapps: MiniappData[]) => {
                    setMiniapps(miniapps);
                }, (error) => {
                    console.log(error)
                },
                );
            Boxo.getMiniapps();
            return () => miniappListSubscription();
          }, [])
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Capacitor">
    ## Capacitor

    <AccordionGroup>
      <Accordion title="Installation">
        ```bash theme={"system"}
        npm install @appboxo/capacitor-boxo-sdk
        ```

        ```bash theme={"system"}
        npx cap sync
        ```
      </Accordion>

      <Accordion title="Launch Miniapp">
        ```
        import { Boxo } from 'capacitor-boxo-sdk';
        ```

        ```
        Boxo.setConfig({  clientId: clientId });
        ```

        ```
        Boxo.openMiniapp({ appId: appId });
        ```

        Example:

        ```index.html [expandable] theme={"system"}
        <!DOCTYPE html>
        <html lang="en" dir="ltr" class="hydrated">
          <head>
            <meta charset="UTF-8" />
            <title>Example Capacitor App</title>
            <meta
              name="viewport"
              content="viewport-fit=cover, width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
            />
            <meta name="format-detection" content="telephone=no" />
          </head>
          <body>
            <main>
              <h1>Capacitor Test App</h1>
              <p>Click to button to open Demo Miniapp</p>
              <button onclick="openMiniapp()">Open miniapp</button>
            </main>
            <script src="./js/example.js" type="module"></script>
          </body>
        </html>
        ```

        ```javascript js/example.js [expandable] theme={"system"}
        import { Boxo } from 'capacitor-boxo-sdk';

        const clientId = '';
        const appId = '';

        Boxo.setConfig({
          clientId: clientId
        });

        window.openMiniapp = () => {
          Boxo.openMiniapp({ appId: appId});
        };
        ```

        ### Set Config

        ```typescript theme={"system"}
        setConfig(options: ConfigOptions) => Promise<void>
        ```
      </Accordion>

      <Accordion title="Set Config">
        **Config Options**

        | Prop                          | Type                                       | Description                                                              |
        | ----------------------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
        | clientId                      | <code>string</code>                        | your client id from dashboard                                            |
        | userId                        | <code>string</code>                        | (optional) hostapp userId, will be used for the Consent Management       |
        | language                      | <code>string</code>                        | language value will be passed to the miniapp                             |
        | sandboxMode                   | <code>boolean</code>                       | switch to sandbox mode                                                   |
        | theme                         | <code>'light' \| 'dark' \| 'system'</code> | theme for splash screen and other native components used inside miniapp. |
        | isDebug                       | <code>boolean</code>                       | enables webview debugging                                                |
        | showPermissionsPage           | <code>boolean</code>                       | use it to hide "Settings" from Miniapp menu                              |
        | showClearCache                | <code>boolean</code>                       | use it to hide "Clear cache" from Miniapp menu                           |
        | showAboutPage                 | <code>boolean</code>                       | use it to hide "About Page" from Miniapp menu                            |
        | miniappSettingsExpirationTime | <code>number</code>                        | use it to change miniapp settings cache time in sec. Default:  60 sec    |
        | splashScreenOptions           | <code>SplashScreenOptions</code>           | (optional) setup splash screen configs                                   |

        **SplashScreenOptions**

        | Prop                   | Type                |
        | ---------------------- | ------------------- |
        | lightBackground        | <code>string</code> |
        | darkBackground         | <code>string</code> |
        | lightProgressIndicator | <code>string</code> |
        | lightProgressTrack     | <code>string</code> |
        | darkProgressIndicator  | <code>string</code> |
        | darkProgressTrack      | <code>string</code> |
      </Accordion>

      <Accordion title="Splash Screen Configuration">
        When a miniapp is launched, Boxo displays a splash screen while the content is loading.
        You can customize the splash screen background color and the loading progress indicator for both **light** and **dark** themes.

        ### Background and progress colors

        Call `Boxo.setConfig` with `splashScreenOptions` (hex strings). The same fields are listed in the Set Config section above.

        ```typescript theme={"system"}
        await Boxo.setConfig({
          clientId: clientId,
          splashScreenOptions: {
            lightBackground: '#FFFFFF',
            darkBackground: '#000000',
            lightProgressIndicator: '#000000',
            lightProgressTrack: '#FFFFFF',
            darkProgressIndicator: '#FFFFFF',
            darkProgressTrack: '#000000',
          },
        });
        ```

        ### Splash behavior

        By default, the splash screen is shown automatically and hides when approximately 50% of the web content has loaded.

        Pass `enableSplash` in `openMiniapp` to control splash for that launch (`false` disables it):

        ```typescript theme={"system"}
        await Boxo.openMiniapp({
          appId: appId,
          enableSplash: false,
        });
        ```
      </Accordion>

      <Accordion title="Page Animation Configuration">
        Customize the animation effects when opening a miniapp by setting `pageAnimation` in `openMiniapp` options.

        You can choose from the following page animations:

        * `LEFT_TO_RIGHT` - The miniapp slides in from the left side of the screen to the right.
        * `RIGHT_TO_LEFT` - The miniapp slides in from the right side of the screen to the left.
        * `BOTTOM_TO_TOP` - The miniapp slides in from the bottom of the screen to the top.
        * `TOP_TO_BOTTOM` - The miniapp slides in from the top of the screen to the bottom.
        * `FADE_IN` - The miniapp fades in gradually from completely transparent to opaque.

        The `BOTTOM_TO_TOP` animation is the default page transition effect.

        ```typescript theme={"system"}
        await Boxo.openMiniapp({
          appId: appId,
          pageAnimation: 'RIGHT_TO_LEFT',
        });
        ```
      </Accordion>

      <Accordion title="Miniapp Control">
        #### Open

        ```typescript theme={"system"}
        openMiniapp(options: OpenMiniappOptions) => Promise<void>
        ```

        Open miniapp with options

        **OpenMiniappOptions**

        | Prop           | Type                                                                                                        | Description                                                                                                                             |
        | -------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
        | appId          | <code>string</code>                                                                                         | miniapp id                                                                                                                              |
        | data           | <code>object</code>                                                                                         | (optional) data as Map that is sent to miniapp                                                                                          |
        | theme          | <code>'light' \| 'dark' \| 'system'</code>                                                                  | (optional) miniapp theme "dark" \| "light" (by default is system theme)                                                                 |
        | extraUrlParams | <code>object</code>                                                                                         | (optional) extra query params to append to miniapp URL (like: [http://miniapp-url.com/?param=test](http://miniapp-url.com/?param=test)) |
        | urlSuffix      | <code>string</code>                                                                                         | (optional) suffix to append to miniapp URL (like: [http://miniapp-url.com/?param=test](http://miniapp-url.com/?param=test))             |
        | colors         | <code><a href="#coloroptions">ColorOptions</a></code>                                                       | (optional) provide colors to miniapp if miniapp supports                                                                                |
        | enableSplash   | <code>boolean</code>                                                                                        | (optional) use to skip miniapp splash screen                                                                                            |
        | saveState      | <code>boolean</code>                                                                                        | (optional) use to save state on close miniapp                                                                                           |
        | pageAnimation  | <code>'BOTTOM\_TO\_TOP' \| 'TOP\_TO\_BOTTOM' \| 'LEFT\_TO\_RIGHT' \| 'RIGHT\_TO\_LEFT' \| 'FADE\_IN'</code> | (optional) use to change launch animation for miniapp                                                                                   |

        **ColorOptions**

        | Prop           | Type                |
        | -------------- | ------------------- |
        | primaryColor   | <code>string</code> |
        | secondaryColor | <code>string</code> |
        | tertiaryColor  | <code>string</code> |

        #### Close

        ```typescript theme={"system"}
        closeMiniapp(options: { appId: string; }) => Promise<void>
        ```

        close miniapp by appId

        #### Hide

        ```typescript theme={"system"}
        hideMiniapps() => Promise<void>
        ```

        Miniapp opens on a native screen. To show payment processing page need to hide miniapp screen.
      </Accordion>

      <Accordion title="Miniapp Auth Flow">
        Handle authentication between your host app and miniapps:

        ```typescript theme={"system"}
         setAuthCode(options: { appId: string; authCode: string; }) => Promise<void>
        ```
      </Accordion>

      <Accordion title="User Logout & Data Clearing">
        When users log out of your host app, you must completely clear all miniapp session data

        ```typescript theme={"system"}
        logout() => Promise<void>
        ```
      </Accordion>

      <Accordion title="Retrieve Miniapp List">
        ```typescript theme={"system"}
        getMiniapps() => Promise<MiniappListResult>
        ```

        Get list of miniapps

        **MiniappListResult**

        | Prop     | Type                        |
        | -------- | --------------------------- |
        | miniapps | <code>\[MiniappData]</code> |
        | error    | <code>string</code>         |

        **MiniappData**

        | Prop        | Type                |
        | ----------- | ------------------- |
        | appId       | <code>string</code> |
        | name        | <code>string</code> |
        | category    | <code>string</code> |
        | description | <code>string</code> |
        | logo        | <code>string</code> |
      </Accordion>

      <Accordion title="Miniapp Custom Events">
        ```typescript theme={"system"}
        addListener(eventName: 'custom_event', listenerFunc: (customEvent: CustomEvent) => void) => Promise<PluginListenerHandle>
        ```

        When host app user logs out, it is highly important to clear all miniapp storage data.

        | Param        | Type                                                                       |
        | ------------ | -------------------------------------------------------------------------- |
        | eventName    | <code>'custom\_event'</code>                                               |
        | listenerFunc | <code>(customEvent: <a href="#customevent">CustomEvent</a>) => void</code> |

        ```typescript theme={"system"}
        sendCustomEvent(customEvent: CustomEvent) => Promise<void>
        ```

        send custom event data to miniapp

        | Prop      | Type                |
        | --------- | ------------------- |
        | appId     | <code>string</code> |
        | requestId | <code>number</code> |
        | type      | <code>string</code> |
        | errorType | <code>string</code> |
        | payload   | <code>object</code> |
      </Accordion>

      <Accordion title="Miniapp Payment Events">
        ```typescript theme={"system"}
        addListener(eventName: 'payment_event', listenerFunc: (paymentEvent: PaymentEvent) => void) => Promise<PluginListenerHandle>
        ```

        | Param        | Type                                                                          |
        | ------------ | ----------------------------------------------------------------------------- |
        | eventName    | <code>'payment\_event'</code>                                                 |
        | listenerFunc | <code>(paymentEvent: <a href="#paymentevent">PaymentEvent</a>) => void</code> |

        ```typescript theme={"system"}
        sendPaymentEvent(paymentEvent: PaymentEvent) => Promise<void>
        ```

        send payment data to miniapp

        | Prop           | Type                |
        | -------------- | ------------------- |
        | appId          | <code>string</code> |
        | orderPaymentId | <code>string</code> |
        | miniappOrderId | <code>string</code> |
        | amount         | <code>number</code> |
        | currency       | <code>string</code> |
        | status         | <code>string</code> |
        | hostappOrderId | <code>string</code> |
        | extraParams    | <code>object</code> |
      </Accordion>

      <Accordion title="Miniapp Lifecycle Events">
        ```typescript theme={"system"}
        addListener(eventName: 'miniapp_lifecycle', listenerFunc: (lifecycle: LifecycleEvent) => void) => Promise<PluginListenerHandle>
        ```

        | Param        | Type                                                                           |
        | ------------ | ------------------------------------------------------------------------------ |
        | eventName    | <code>'miniapp\_lifecycle'</code>                                              |
        | listenerFunc | <code>(lifecycle: <a href="#lifecycleevent">LifecycleEvent</a>) => void</code> |

        **LifecycleEvent**

        | Prop      | Type                |
        | --------- | ------------------- |
        | appId     | <code>string</code> |
        | lifecycle | <code>string</code> |
        | error     | <code>string</code> |

        onLaunch - Called when the miniapp will launch with Boxo.open(...)
        onResume - Called when the miniapp will start interacting with the user
        onPause - Called when the miniapp loses foreground state
        onClose - Called when clicked close button in miniapp or when destroyed miniapp page
        onError - Called when miniapp fails to launch due to internet connection issues
        onUserInteraction - Called whenever a touch event is dispatched to the miniapp page
        onAuth - Called when the miniapp starts login and user allows it
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Expo">
    ## Expo

    [Expo plugin](https://www.npmjs.com/package/@appboxo/expo-boxo-sdk) to integrate Boxo for iOS and Android. Please see our [sample Expo app](https://github.com/Appboxo/expo-boxo-sdk/tree/main/example) to learn more.

    <AccordionGroup>
      <Accordion title="Installation">
        ```bash theme={"system"}
        npm install @appboxo/expo-boxo-sdk
        ```

        Configuration in app.json/app.config.js

        ```json theme={"system"}
        {
          "expo": {
            "plugins": [
              ["@appboxo/expo-boxo-sdk"]
            ]
          }
        }
        ```
      </Accordion>

      <Accordion title="Launch Miniapp">
        ```
        import * as Boxo from 'expo-boxo-sdk';
        ```

        ```
        Boxo.setConfig({  clientId: clientId });
        ```

        ```
        Boxo.openMiniapp({ appId: appId });
        ```
      </Accordion>

      <Accordion title="Set Config">
        ```typescript theme={"system"}
        setConfig(options: ConfigOptions)
        ```

        **ConfigOptions**

        | Prop                          | Type                                       | Description                                                              |
        | ----------------------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
        | clientId                      | <code>string</code>                        | your client id from dashboard                                            |
        | userId                        | <code>string</code>                        | (optional) hostapp userId, will be used for the Consent Management       |
        | language                      | <code>string</code>                        | language value will be passed to the miniapp                             |
        | sandboxMode                   | <code>boolean</code>                       | switch to sandbox mode                                                   |
        | theme                         | <code>'light' \| 'dark' \| 'system'</code> | theme for splash screen and other native components used inside miniapp. |
        | isDebug                       | <code>boolean</code>                       | enables webview debugging                                                |
        | showPermissionsPage           | <code>boolean</code>                       | use it to hide "Settings" from Miniapp menu                              |
        | showClearCache                | <code>boolean</code>                       | use it to hide "Clear cache" from Miniapp menu                           |
        | showAboutPage                 | <code>boolean</code>                       | use it to hide "About Page" from Miniapp menu                            |
        | miniappSettingsExpirationTime | <code>number</code>                        | use it to change miniapp settings cache time in sec. Default:  60 sec    |
        | splashScreenOptions           | <code>SplashScreenOptions</code>           | (optional) setup splash screen configs                                   |

        **SplashScreenOptions**

        | Prop                   | Type                |
        | ---------------------- | ------------------- |
        | lightBackground        | <code>string</code> |
        | darkBackground         | <code>string</code> |
        | lightProgressIndicator | <code>string</code> |
        | lightProgressTrack     | <code>string</code> |
        | darkProgressIndicator  | <code>string</code> |
        | darkProgressTrack      | <code>string</code> |
      </Accordion>

      <Accordion title="Splash Screen Configuration">
        When a miniapp is launched, Boxo displays a splash screen while the content is loading.
        You can customize the splash screen background color and the loading progress indicator for both **light** and **dark** themes.

        ### Background and progress colors

        Call `Boxo.setConfig` with `splashScreenOptions` (hex strings). The same fields are listed in the Set Config section above.

        ```typescript theme={"system"}
        Boxo.setConfig({
          clientId: clientId,
          splashScreenOptions: {
            lightBackground: '#FFFFFF',
            darkBackground: '#000000',
            lightProgressIndicator: '#000000',
            lightProgressTrack: '#FFFFFF',
            darkProgressIndicator: '#FFFFFF',
            darkProgressTrack: '#000000',
          },
        });
        ```

        ### Splash behavior

        By default, the splash screen is shown automatically and hides when approximately 50% of the web content has loaded.

        Pass `enableSplash` in `openMiniapp` to control splash for that launch (`false` disables it):

        ```typescript theme={"system"}
        Boxo.openMiniapp({
          appId: appId,
          enableSplash: false,
        });
        ```
      </Accordion>

      <Accordion title="Page Animation Configuration">
        Customize the animation effects when opening a miniapp by setting `pageAnimation` in `openMiniapp` options.

        You can choose from the following page animations:

        * `LEFT_TO_RIGHT` - The miniapp slides in from the left side of the screen to the right.
        * `RIGHT_TO_LEFT` - The miniapp slides in from the right side of the screen to the left.
        * `BOTTOM_TO_TOP` - The miniapp slides in from the bottom of the screen to the top.
        * `TOP_TO_BOTTOM` - The miniapp slides in from the top of the screen to the bottom.
        * `FADE_IN` - The miniapp fades in gradually from completely transparent to opaque.

        The `BOTTOM_TO_TOP` animation is the default page transition effect.

        ```typescript theme={"system"}
        Boxo.openMiniapp({
          appId: appId,
          pageAnimation: 'RIGHT_TO_LEFT',
        });
        ```
      </Accordion>

      <Accordion title="Miniapp Control">
        #### Open

        ```typescript theme={"system"}
        openMiniapp(options: MiniappOptions)
        ```

        Open miniapp with options

        **MiniappOptions**

        | Prop           | Type                                                                                                        | Description                                                                                                                             |
        | -------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
        | appId          | <code>string</code>                                                                                         | miniapp id                                                                                                                              |
        | data           | <code>object</code>                                                                                         | (optional) data as Map that is sent to miniapp                                                                                          |
        | theme          | <code>'light' \| 'dark' \| 'system'</code>                                                                  | (optional) miniapp theme "dark" \| "light" (by default is system theme)                                                                 |
        | extraUrlParams | <code>object</code>                                                                                         | (optional) extra query params to append to miniapp URL (like: [http://miniapp-url.com/?param=test](http://miniapp-url.com/?param=test)) |
        | urlSuffix      | <code>string</code>                                                                                         | (optional) suffix to append to miniapp URL (like: [http://miniapp-url.com/?param=test](http://miniapp-url.com/?param=test))             |
        | colors         | <code><a href="#coloroptions">ColorOptions</a></code>                                                       | (optional) provide colors to miniapp if miniapp supports                                                                                |
        | enableSplash   | <code>boolean</code>                                                                                        | (optional) use to skip miniapp splash screen                                                                                            |
        | saveState      | <code>boolean</code>                                                                                        | (optional) use to save state on close miniapp                                                                                           |
        | pageAnimation  | <code>'BOTTOM\_TO\_TOP' \| 'TOP\_TO\_BOTTOM' \| 'LEFT\_TO\_RIGHT' \| 'RIGHT\_TO\_LEFT' \| 'FADE\_IN'</code> | (optional) use to change launch animation for miniapp                                                                                   |

        **ColorOptions**

        | Prop           | Type                |
        | -------------- | ------------------- |
        | primaryColor   | <code>string</code> |
        | secondaryColor | <code>string</code> |
        | tertiaryColor  | <code>string</code> |

        #### Close

        ```typescript theme={"system"}
        closeMiniapp(appId: string)
        ```

        close miniapp by appId

        #### Hide

        ```typescript theme={"system"}
        hideMiniapps()
        ```

        Miniapp opens on a native screen. To show payment processing page need to hide miniapp screen.
      </Accordion>

      <Accordion title="Miniapp Auth Flow">
        Handle authentication between your host app and miniapps:

        ```typescript theme={"system"}
        Boxo.addAuthListener((authEvent) => {
            Boxo.setAuthCode(authEvent.appId, authCode)
        });
        ```
      </Accordion>

      <Accordion title="User Logout & Data Clearing">
        When users log out of your host app, you must completely clear all miniapp session data

        ```typescript theme={"system"}
        logout()
        ```
      </Accordion>

      <Accordion title="Retrieve Miniapp List">
        ```typescript theme={"system"}
        Boxo.addMiniappListListener((result) => {
          console.log(result.miniapps);
        });
        ```

        Get list of miniapps

        **MiniappListResult**

        | Prop     | Type                        |
        | -------- | --------------------------- |
        | miniapps | <code>\[MiniappData]</code> |
        | error    | <code>string</code>         |

        **MiniappData**

        | Prop        | Type                |
        | ----------- | ------------------- |
        | appId       | <code>string</code> |
        | name        | <code>string</code> |
        | category    | <code>string</code> |
        | description | <code>string</code> |
        | logo        | <code>string</code> |
      </Accordion>

      <Accordion title="Miniapp Custom Events">
        ```typescript theme={"system"}
        Boxo.addCustomEventListener((customEvent) => {
          ..handle custom event
          Boxo.sendCustomEvent(customEvent);
        });
        ```

        Send custom event data to miniapp

        | Prop      | Type                |
        | --------- | ------------------- |
        | appId     | <code>string</code> |
        | requestId | <code>number</code> |
        | type      | <code>string</code> |
        | errorType | <code>string</code> |
        | payload   | <code>object</code> |
      </Accordion>

      <Accordion title="Miniapp Payment Events">
        ```typescript theme={"system"}
        Boxo.addPaymentEventListener((paymentData) => {
          Boxo.hideMiniapps();
          .. show payment page
          paymentData.status = "success";
          ..confirm payment
          Boxo.sendPaymentEvent(paymentData);
          Boxo.openMiniapp({ appId: paymentData.appId })
        });
        ```

        send payment data to miniapp

        | Prop           | Type                |
        | -------------- | ------------------- |
        | appId          | <code>string</code> |
        | orderPaymentId | <code>string</code> |
        | miniappOrderId | <code>string</code> |
        | amount         | <code>number</code> |
        | currency       | <code>string</code> |
        | status         | <code>string</code> |
        | hostappOrderId | <code>string</code> |
        | extraParams    | <code>object</code> |
      </Accordion>

      <Accordion title="Miniapp Lifecycle Events">
        ```typescript theme={"system"}
        Boxo.addMiniappLifecycleListener((lifecycleData) => {
          console.log(lifecycleData);
        });
        ```

        **LifecycleEvent**

        | Prop      | Type                |
        | --------- | ------------------- |
        | appId     | <code>string</code> |
        | lifecycle | <code>string</code> |
        | error     | <code>string</code> |

        onLaunch - Called when the miniapp will launch with Boxo.open(...)
        onResume - Called when the miniapp will start interacting with the user
        onPause - Called when the miniapp loses foreground state
        onClose - Called when clicked close button in miniapp or when destroyed miniapp page
        onError - Called when miniapp fails to launch due to internet connection issues
        onUserInteraction - Called whenever a touch event is dispatched to the miniapp page
        onAuth - Called when the miniapp starts login and user allows it
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Web SDK">
    ## Web SDK

    A JavaScript SDK for embedding miniapps into desktop web applications using iframe communication. Please see our [sample web app](https://github.com/Appboxo/sample-web-hostapp) to learn more.

    <AccordionGroup>
      <Accordion title="Installation">
        ```bash theme={"system"}
        npm install @appboxo/web-sdk
        ```

        or

        ```bash theme={"system"}
        pnpm install @appboxo/web-sdk
        ```
      </Accordion>

      <Accordion title="Launch Miniapp">
        ```typescript theme={"system"}
        import { AppboxoWebSDK } from "@appboxo/web-sdk";

        const sdk = new AppboxoWebSDK({
          clientId: "your-client-id",
          appId: "your-app-id"
        });

        // Mount miniapp
        await sdk.mount({
          container: document.getElementById("miniapp")
        });
        ```
      </Accordion>

      <Accordion title="Configuration">
        ```typescript theme={"system"}
        const sdk = new AppboxoWebSDK({
          clientId: string;      // Required
          appId: string;         // Required
          userId?: string;       // Optional, user reference identifier
          baseUrl?: string;      // Optional, default: "https://dashboard.boxo.io/api/v1"
          sandboxMode?: boolean;  // Optional, default: false
          debug?: boolean;       // Optional, default: false. When true, enables all console logs for debugging
          locale?: string;       // Optional, locale/language code (e.g., 'en', 'en-US', 'ru', 'zh-CN')
          theme?: 'dark' | 'light' | 'system'; // Optional, theme/color scheme preference (default: 'system')
          allowedOrigins?: string[]; // Optional, restrict message events to specific origins. Empty array allows all origins
          onGetAuthCode?: () => Promise<string>; // Optional, for automatic auth code retrieval
          onGetAuthTokens?: () => Promise<LoginResponse>; // Optional, for direct auth tokens
          onPaymentRequest?: (params: PaymentRequest) => Promise<PaymentResponse>; // Optional, for handling payment requests
        });
        ```

        #### Locale/Language

        Set the locale/language code to pass to the miniapp. The locale will be included in the InitData response.

        ```typescript theme={"system"}
        // Set locale during initialization
        const sdk = new AppboxoWebSDK({
          clientId: "your-client-id",
          appId: "your-app-id",
          locale: "en-US"  // or 'ru', 'zh-CN', etc.
        });

        // Or set locale dynamically
        sdk.setLocale("ru");
        ```

        The locale is passed to the miniapp via `InitData.data.locale` on the next `AppBoxoWebAppGetInitData` request.

        **Important Notes:**

        * If you call `setLocale()` after the miniapp has already loaded, the locale will be included in the next InitData request. The miniapp may need to reload or request InitData again to receive the updated locale.
        * To ensure the locale is available immediately, set it during SDK initialization or before calling `mount()`.

        #### Debug Mode

        Control console logging for debugging:

        ```typescript theme={"system"}
        const sdk = new AppboxoWebSDK({
          clientId: "your-client-id",
          appId: "your-app-id",
          debug: true  // Enable debug mode
        });
        ```

        **About `debug` mode:**

        * `debug: false` (default): No console logs are output. Suitable for production.
        * `debug: true`: All SDK operations are logged to console. Useful for development and troubleshooting.
        * The `debug` option does not affect SDK functionality - it only controls console logging.

        #### Allowed Origins

        Control which origins can send messages to the SDK for security:

        ```typescript theme={"system"}
        const sdk = new AppboxoWebSDK({
          clientId: "your-client-id",
          appId: "your-app-id",
          allowedOrigins: ["https://miniapp.example.com"]  // Restrict to specific origins
        });
        ```

        **Important Notes:**

        * Empty array `[]` (default): Allows all origins (flexible for different deployment URLs)
        * Set specific origins: Only messages from listed origins will be accepted
        * `allowedOrigins` should be the miniapp's origin (where iframe loads from), NOT `window.location.origin`
      </Accordion>

      <Accordion title="Miniapp Auth Flow">
        Handle authentication between your host app and miniapps. The SDK supports multiple authentication methods:

        **OAuth flow (using auth code):**

        ```typescript theme={"system"}
        // Set auth code explicitly
        const authCode = await fetch('/api/auth-code').then(r => r.json());
        sdk.setAuthCode(authCode);
        ```

        Or provide a callback:

        ```typescript theme={"system"}
        const sdk = new AppboxoWebSDK({
          clientId: "your-client-id",
          appId: "your-app-id",
          onGetAuthCode: async () => {
            const res = await fetch('/api/generate-auth-code');
            return (await res.json()).auth_code;
          }
        });
        ```

        **Direct auth flow (using tokens):**

        ```typescript theme={"system"}
        // Set tokens directly
        const tokens = await getTokensFromBackend();
        sdk.setAuthTokens(tokens.access_token, tokens.refresh_token);
        ```

        Or use callback:

        ```typescript theme={"system"}
        const sdk = new AppboxoWebSDK({
          clientId: "your-client-id",
          appId: "your-app-id",
          onGetAuthTokens: async () => {
            const res = await fetch('/api/get-miniapp-tokens');
            const result = await res.json();
            return {
              token: result.access_token,
              refresh_token: result.refresh_token
            };
          }
        });
        ```

        Or register an auth listener:

        ```typescript theme={"system"}
        sdk.onAuth(async () => {
          const response = await fetch('/api/get-miniapp-tokens');
          const tokens = await response.json();
          sdk.setAuthTokens(tokens.access_token, tokens.refresh_token);
        });
        ```

        The SDK will try these in order:

        1. Pre-set tokens (`setAuthTokens`)
        2. Direct auth callback (`onGetAuthTokens`)
        3. OAuth auth code (`setAuthCode` or `onGetAuthCode` callback)
      </Accordion>

      <Accordion title="Payment Processing">
        When a miniapp calls `appboxo.pay()`, the SDK will call your `onPaymentRequest` callback. Process the payment and return the result.

        Payment status values: `'success'`, `'failed'`, or `'cancelled'`.

        ```typescript theme={"system"}
        const sdk = new AppboxoWebSDK({
          clientId: "your-client-id",
          appId: "your-app-id",
          onPaymentRequest: async (paymentData) => {
            // Process payment with your backend
            const response = await fetch('/api/payments/process', {
              method: 'POST',
              body: JSON.stringify(paymentData)
            });
            const result = await response.json();
            
            return {
              ...paymentData,
              status: result.status, // 'success', 'failed', or 'cancelled'
              hostappOrderId: result.orderId,
              transactionId: result.transactionId, // optional
            };
          },
        });

        // Optional: listen for payment completion
        sdk.onPaymentComplete((success, data) => {
          if (success) {
            console.log('Payment succeeded:', data);
          }
        });
        ```

        **Important Notes:**

        * When `onPaymentRequest` is set, the SDK automatically tells the miniapp it supports `AppBoxoWebAppPay`, so it can call `appboxo.pay()`.
        * **If `onPaymentRequest` is not configured**, payment requests will fail. Enable `debug: true` to see error messages.
      </Accordion>

      <Accordion title="Dark mode">
        Controls miniapp theming to match your host app's design system or respect user preferences. The theme preference is passed to the miniapp via InitData and the miniapp is automatically notified when the theme changes.

        ```typescript theme={"system"}
        // Set theme during initialization
        const sdk = new AppboxoWebSDK({
          clientId: "your-client-id",
          appId: "your-app-id",
          theme: "dark"  // or 'light', 'system'
        });

        // Or set theme dynamically
        sdk.setTheme("light");
        ```

        **Theme values:**

        * `'dark'`: Force dark mode
        * `'light'`: Force light mode
        * `'system'`: Use system preference (default)

        The theme is passed to the miniapp via `InitData.data.theme` on the next `AppBoxoWebAppGetInitData` request. If you call `setTheme()` after the miniapp has already loaded, the SDK will automatically notify the miniapp about the theme change via `postMessage`, allowing the miniapp to respond immediately without waiting for the next InitData request.

        **Important Notes:**

        * To ensure the theme is available immediately, set it during SDK initialization or before calling `mount()`.
        * The miniapp must implement theme handling logic to receive and apply the theme from `InitData.data.theme`.
      </Accordion>

      <Accordion title="User Logout & Data Clearing">
        When users log out of your host app, you must completely clear all miniapp session data.

        ```typescript theme={"system"}
        sdk.logout();
        ```

        This clears the host app's `localStorage`, `sessionStorage`, and SDK's internal `authCode` and `authTokens`.
      </Accordion>

      <Accordion title="Mount Miniapp">
        The SDK provides a helper method to mount miniapps. The miniapp URL will be automatically fetched from the API:

        ```typescript theme={"system"}
        await sdk.mount({
          container: '#miniapp-container',
          className: 'miniapp-iframe'
        });
        ```

        Or manually set iframe:

        ```typescript theme={"system"}
        const iframe = document.createElement('iframe');
        iframe.src = await sdk.getMiniappUrl();
        document.getElementById('miniapp').appendChild(iframe);

        sdk.setIframe(iframe);
        sdk.initialize();
        ```

        **Styling:**

        When using the `mount` helper, styling is handled via CSS:

        ```css theme={"system"}
        .miniapp-container {
          width: 100%;
          height: 500px;
        }

        .miniapp-iframe {
          width: 100%;
          height: 100%;
          border: none;
        }
        ```
      </Accordion>

      <Accordion title="Retrieve Miniapp List">
        Fetch the complete catalog of available miniapps with detailed metadata.

        ```typescript theme={"system"}
        // Note: This feature may require additional API integration
        // Check SDK documentation for latest implementation
        ```
      </Accordion>

      <Accordion title="Custom Events">
        Establish two-way communication between your host app and miniapps using custom events.

        ```typescript theme={"system"}
        sdk.onEvent('custom_event', (event) => {
          // Handle custom event from miniapp
          console.log('Custom event received:', event);
          
          // Send response back to miniapp if needed
          // (implementation depends on SDK version)
        });
        ```
      </Accordion>

      <Accordion title="Methods">
        | Method                                | Description                                                                 |
        | ------------------------------------- | --------------------------------------------------------------------------- |
        | `setAuthCode(code)`                   | Set authentication code                                                     |
        | `setAuthTokens(token, refreshToken?)` | Set authentication tokens directly                                          |
        | `setLocale(locale)`                   | Set locale/language code (e.g., 'en', 'en-US', 'ru', 'zh-CN')               |
        | `setTheme(theme)`                     | Set theme/color scheme preference ('dark' \| 'light' \| 'system')           |
        | `onAuth(callback)`                    | Register callback for authentication events                                 |
        | `mount(config)`                       | Create iframe and initialize SDK                                            |
        | `getMiniappUrl()`                     | Fetch miniapp URL from API settings endpoint                                |
        | `setIframe(iframe)`                   | Set iframe element manually                                                 |
        | `initialize()`                        | Start listening for events                                                  |
        | `onEvent(type, handler)`              | Register custom event handler                                               |
        | `onLoginComplete(callback)`           | Login completion callback                                                   |
        | `onPaymentComplete(callback)`         | Payment completion callback                                                 |
        | `logout()`                            | Clear host app's localStorage, sessionStorage, and SDK's internal auth data |
        | `destroy()`                           | Clean up resources                                                          |
      </Accordion>

      <Accordion title="Events">
        SDK handles these miniapp events:

        * `AppBoxoWebAppLogin` - User authentication
        * `AppBoxoWebAppPay` - Payment processing
        * `AppBoxoWebAppGetInitData` - Initial data request
        * `AppBoxoWebAppCustomEvent` - Custom events
      </Accordion>

      <Accordion title="Lifecycle Events">
        Track key moments in a miniapp's execution:

        ```typescript theme={"system"}
        // Login completion
        sdk.onLoginComplete((success, data) => {
          if (success) {
            console.log('Login succeeded:', data);
          } else {
            console.log('Login failed:', data);
          }
        });

        // Payment completion
        sdk.onPaymentComplete((success, data) => {
          if (success) {
            console.log('Payment succeeded:', data);
          } else {
            console.log('Payment failed:', data);
          }
        });
        ```
      </Accordion>

      <Accordion title="React Examples">
        ### OAuth Flow Example

        ```tsx theme={"system"}
        import { useEffect, useRef, useState } from "react";
        import { AppboxoWebSDK } from "@appboxo/web-sdk";
        import type { PaymentRequest, PaymentResponse } from "@appboxo/web-sdk";

        function OAuthExample() {
          const containerRef = useRef<HTMLDivElement>(null);
          const sdkRef = useRef<AppboxoWebSDK | null>(null);
          const [isMounted, setIsMounted] = useState(false);

          useEffect(() => {
            const sdk = new AppboxoWebSDK({
              clientId: "your-client-id",
              appId: "your-app-id",
              debug: false,
              allowedOrigins: [], // Empty array allows all origins
              onPaymentRequest: async (paymentData: PaymentRequest): Promise<PaymentResponse> => {
                const response = await fetch('/api/payments/process', {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: JSON.stringify(paymentData)
                });
                const result = await response.json();
                
                return {
                  ...paymentData,
                  status: result.status,
                  hostappOrderId: result.hostappOrderId,
                };
              },
            });

            // Set auth code (OAuth flow)
            sdk.setAuthCode("your-auth-code");

            sdk.onLoginComplete((success, data) => {
              console.log('Login:', success ? 'success' : 'failed', data);
            });

            sdk.onPaymentComplete((success, data) => {
              console.log('Payment:', success ? 'success' : 'failed', data);
            });

            sdkRef.current = sdk;

            const mountMiniapp = async () => {
              if (containerRef.current) {
                try {
                  await sdk.mount({
                    container: containerRef.current,
                    className: "miniapp-iframe"
                  });
                  setIsMounted(true);
                } catch (err) {
                  console.error('Failed to mount miniapp:', err);
                }
              }
            };

            mountMiniapp();

            return () => {
              sdk.destroy();
            };
          }, []);

          return (
            <div>
              <div ref={containerRef} style={{ width: '100%', height: '500px' }} />
              <p>Status: {isMounted ? "Mounted" : "Mounting..."}</p>
            </div>
          );
        }
        ```

        ### Direct Auth Flow Example

        ```tsx theme={"system"}
        import { useEffect, useRef, useState } from "react";
        import { AppboxoWebSDK } from "@appboxo/web-sdk";
        import type { PaymentRequest, PaymentResponse } from "@appboxo/web-sdk";

        function DirectAuthExample() {
          const containerRef = useRef<HTMLDivElement>(null);
          const sdkRef = useRef<AppboxoWebSDK | null>(null);
          const [isMounted, setIsMounted] = useState(false);

          useEffect(() => {
            const sdk = new AppboxoWebSDK({
              clientId: "your-client-id",
              appId: "your-app-id",
              debug: false,
              // Alternative: Use onGetAuthTokens callback
              // onGetAuthTokens: async () => {
              //   const response = await fetch('/api/get-miniapp-tokens');
              //   const result = await response.json();
              //   return { token: result.access_token, refresh_token: result.refresh_token };
              // }
            });

            // Direct auth flow - onAuth lifecycle hook
            sdk.onAuth(async () => {
              // Your backend calls Boxo Dashboard connect endpoint to get miniapp tokens
              const response = await fetch('/api/get-miniapp-tokens', {
                headers: { 'Authorization': `Bearer ${yourToken}` }
              });
              const tokens = await response.json();
              sdk.setAuthTokens(tokens.access_token, tokens.refresh_token);
            });

            // Alternative: Pre-set tokens if you already have them
            // const tokens = await getTokensFromBackend();
            // sdk.setAuthTokens(tokens.access_token, tokens.refresh_token);

            sdk.onLoginComplete((success, data) => {
              console.log('Login:', success ? 'success' : 'failed', data);
            });

            sdkRef.current = sdk;

            const mountMiniapp = async () => {
              if (containerRef.current) {
                try {
                  await sdk.mount({
                    container: containerRef.current,
                    className: "miniapp-iframe"
                  });
                  setIsMounted(true);
                } catch (err) {
                  console.error('Failed to mount miniapp:', err);
                }
              }
            };

            mountMiniapp();

            return () => {
              sdk.destroy();
            };
          }, []);

          return (
            <div>
              <div ref={containerRef} style={{ width: '100%', height: '500px' }} />
              <p>Status: {isMounted ? "Mounted" : "Mounting..."}</p>
            </div>
          );
        }
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>


# Custom Events System
Source: https://boxo.mintlify.app/host-apps/CES



<Accordion title="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.

  [Custom events example](/miniapp/CES)

  <Tabs>
    <Tab title="iOS">
      ```swift theme={"system"}
      miniapp.delegate = self
      ...
      extension ViewController : MiniappDelegate {
          func didReceiveCustomEvent(miniapp: Miniapp, customEvent: CustomEvent) {
              customEvent.payload = [
                  "message" : "text",
                  "id" : 123,
                  "checked" : true
              ]
              miniapp.sendCustomEvent(customEvent: customEvent)
          }
      }
      ```
    </Tab>

    <Tab title="Android">
      ```kotlin theme={"system"}
      miniApp.setCustomEventListener { _, miniapp, customEvent ->
          //doSomething
          customEvent.payload = mapOf("message" to "text",
                                      "id" to 123,
                                      "checked" to true)
          miniapp.sendEvent(customEvent)
      }
      ```

      **java**

      ```java theme={"system"}
      miniapp.setCustomEventListener(new Miniapp.CustomEventListener() {
          @Override
          public void handle(@NotNull BoxoFragment boxoFragment, @NotNull MiniApp miniapp, @NotNull CustomEvent customEvent) {
              Map<String, Object> payload = new HashMap<>();
              payload.put("message", "message");
              payload.put("id", 123);
              payload.put("checked", true);
              customEvent.setPayload(payload);
              miniapp.sendEvent(customEvent);
          }
      });
      ```
    </Tab>

    <Tab title="Flutter">
      Handle custom events by listening to `.customEvents()`.

      Example receiving and sending back same event:

      ```
      Appboxo.customEvents().listen((CustomEvent event) {
        if (event.appId == 'app123456') {
          event.payload = {"foo": "bar"};
          Appboxo.sendEvent(event);
        }
      });
      ```

      For cases when you want to hide all miniapps when a custom event is received, you can call `Appboxo.hideMiniapps()`;

      Example:

      ```clike theme={"system"}
      import 'package:flutter/material.dart';
      import 'package:appboxo_sdk/appboxo_sdk.dart';

      void main() => runApp(MyApp());

      class MyApp extends StatefulWidget {
        @override
        _MyAppState createState() => _MyAppState();
      }

      class _MyAppState extends State<MyApp> {
        @override
        void initState() {
          super.initState();
          Appboxo.setConfig("CLIENT_ID");
          Appboxo.customEvents().listen((CustomEvent event) {
            if (event.appId == 'app123456') {
              Appboxo.hideMiniapps();
              Future.delayed(const Duration(milliseconds: 2000), () {
                Appboxo.openMiniapp("app123456", "");
                event.payload = {"complete": "ok"};
                Appboxo.sendEvent(event);
              });
            }
          });
        }

        @override
        Widget build(BuildContext context) {
          return MaterialApp(
            home: Scaffold(
              appBar: AppBar(
                title: const Text('Appboxo SDK Test'),
              ),
              body: Center(
                child: RaisedButton(
                  onPressed: () {
                    Appboxo.openMiniapp("app123456", "");
                  },
                  child: Text("Miniapp"),
                ),
              ),
            ),
          );
        }
      }
      ```
    </Tab>

    <Tab title="React Native">
      Handling custom events in React Native is straightforward. Use customEvents to both subscribe to and send custom events between the miniapp and the host app.

      Example:

      ```clike theme={"system"}
         appboxo.customEvents
            .subscribe<'eventType', { payloadKey: 'payloadData' }>(event => {
              const modifiedEvent = {
                app_id: '[miniap_id]', // miniapp id
                custom_event: {
                  error_type: undefined, // throw the error with non empty 'error_type'
                  payload: {payloadKey: 'payloadData'}, // payload data to send to miniapp
                  request_id: '1', // event requet id
                  type: 'eventType', // event type
                },
              }
              appboxo.customEvents.send(modifiedEvent) // your data that you want to send back to miniapp
            })
      ```

      > TIP
      >
      > Please don't forget to unsubscribe from events

      Usage:

      ```clike theme={"system"}
      import React from 'react';
      import appboxo from '@appboxo/react-native-sdk';
      import { StyleSheet, View, Button } from 'react-native';

      type eventType = 'eventType';
      type eventPayload = { payloadKey: 'payload' };

      export default function App() {

        React.useEffect(() => {
          appboxo.setConfig('[client_id]');  //set your Appboxo client_id

          const eventPayloadData = { payloadKey: 'payload' };

          const subscription = appboxo.customEvents
            .subscribe<eventType, eventPayload>( //listen custom event from miniapp
              event => {
                const modifiedEvent = {
                  app_id: '[miniap_id]', // miniapp id
                  custom_event: {
                    request_id: event.custom_event.request_id, // event requet id
                    payload: eventPayloadData, // payload data to send to miniapp
                    type: eventType, // event type
                  },
                };
                appboxo.customEvents.send(modifiedEvent); //send custom event to miniapp
              },
              (errorType?: string) => {
                console.error(errorType || 'Something went wrong!'); //handle error
              }     
            );

          return () => subscription(); //unsubscribe from custom events

        }, []);

        const handleOpenMiniapp = () => {
          appboxo.openMiniapp('[miniapp_id]', '[auth_payload]');  //launch miniapp by id with auth payload
        }

        return (
          <View style={styles.container}>
            <Button
              color="#841584"
              title="Launch miniapp"
              onPress={handleOpenMiniapp}
              accessibilityLabel="Launch miniapp"
            />
          </View>
        );
      }

      const styles = StyleSheet.create({
        container: {
          flex: 1,
          alignItems: 'center',
          backgroundColor: '#fff',
          justifyContent: 'center',
        },
      });
      ```
    </Tab>
  </Tabs>
</Accordion>

# Boxo Event Bridge

***

<Accordion title="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
</Accordion>

<Accordion title="Setting up the backend">
  \*Note: Feature must be enabled in [Dashboard](https://dashboard.boxo.io/host-apps/)

  **Data format**

  JSON is used for data exchange. Event payloads can contain any valid JSON structure that both the sender and receiver agree upon.

  <Accordion title="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](https://dashboard.boxo.io/host-apps/)

    **Headers:**

    | Key             | Value                                                             |
    | --------------- | ----------------------------------------------------------------- |
    | `Authorization` | `<prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)>` |
    | `Content-type`  | `application/json`                                                |

    * Default `<prefix>`: `Token`. Access token prefix can be set in [Boxo Connect](https://dashboard.boxo.io/host-apps/).
    * `hostapp_client_id` and `hostapp_secret_key` must be provided in [Dashboard](https://dashboard.boxo.io/host-apps/)

    **Body**

    | Field        | Data type | Description                                             |
    | ------------ | --------- | ------------------------------------------------------- |
    | `app_id`     | String    | Miniapp identifier                                      |
    | `client_id`  | String    | Hostapp identifier                                      |
    | `event_type` | String    | Event type identifying the purpose of the event         |
    | `payload`    | Object    | Event 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"
        }
    }'
    ```
  </Accordion>

  <Accordion title="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/events/hostapp/` endpoint

    **Headers**

    | Key             | Value                                                             |
    | --------------- | ----------------------------------------------------------------- |
    | `Authorization` | `<prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)>` |
    | `Content-type`  | `application/json`                                                |

    * Default `<prefix>`: `Token`. Access token prefix can be set in [Boxo Connect](https://dashboard.boxo.io/host-apps/).
    * `hostapp_client_id` and `hostapp_secret_key` must be provided in [Dashboard](https://dashboard.boxo.io/host-apps/)

    **Body**

    | Field               | Data type        | Description                                             |
    | ------------------- | ---------------- | ------------------------------------------------------- |
    | `app_id`            | String           | Miniapp identifier (recipient)                          |
    | `client_id`         | String           | Hostapp identifier (sender)                             |
    | `event_type`        | String           | Event type identifying the purpose of the event         |
    | `external_event_id` | String(Optional) | Event ID from Hostapp                                   |
    | `payload`           | Object           | Event 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/events/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"
        }
    }'
    ```
  </Accordion>
</Accordion>

<Accordion title="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 Type             | Description                               | Example Payload                                             |
  | ---------------------- | ----------------------------------------- | ----------------------------------------------------------- |
  | `user_profile_updated` | User profile information has been updated | `{"user_reference": "123", "email": "example@example.com"}` |

  ### Miniapp to Host App Events

  | Event Type            | Description                      | Example Payload                                                         |
  | --------------------- | -------------------------------- | ----------------------------------------------------------------------- |
  | `order_status_update` | Miniapp order fulfillment status | `{"order_payment_id": "order_123", "fulfillment_status": "delivering"}` |
</Accordion>

<Accordion title="Error Handling">
  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 recipient |
  | `INVALID_EVENT_DATA`      | The event data format is invalid                |
  | `EVENT_DELIVERY_FAILED`   | Failed to deliver the event to the recipient    |
  | `UNAUTHORIZED`            | Sender is not authorized to send events         |
</Accordion>

<Accordion title="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.
</Accordion>


# Deeplinks
Source: https://boxo.mintlify.app/host-apps/DeepLink



## Deeplinks

The deeplink URL should include the miniapp ID and the relevant URL route if needed to land the user on a specific page.

The user will first deeplink to the host app, which then parses the deeplink to obtain the miniapp ID and the path to the page.

***

## Open the homepage of the miniapp

### iOS

```swift theme={"system"}
Boxo.shared.getExistingMiniapp(appId: "app_id")?.close()
        
let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
let config = MiniappConfig()
config.saveState = false
miniapp.setConfig(config: config)
miniapp.open(viewController: self)
```

### Android

```kotlin theme={"system"}
val appId = "<app_id>" // Get miniapp appId from deeplink
Boxo.getExistingMiniapp(appId)?.close()
Boxo.getMiniapp(appId)
    .setConfig(
        MiniappConfig.Builder()
            .saveState(false)
            .build()
    )
    .open()
```

### Capacitor

```javascript theme={"system"}
const appId = "<app_id>";  // Get miniapp appId from deeplink
Boxo.closeMiniapp({ appId: appId });
Boxo.openMiniapp({ appId: appId, saveState: false });
```

### React Native

```javascript theme={"system"}
Boxo.closeMiniapp('[miniapp_id]');
Boxo.openMiniapp('[miniapp_id]', { saveState: false });
```

### Flutter

```dart theme={"system"}
const appId ="[app_id]"; // Get miniapp appId from deeplink
Boxo.closeMiniapp(appId);
Boxo.openMiniapp(appId, saveState: false);
```

***

## Open a specific page within the miniapp

### iOS

```swift theme={"system"}
Boxo.shared.getExistingMiniapp(appId: "app_id")?.close()
        
let miniapp = Boxo.shared.getMiniapp(appId: "app_id")

let config = MiniappConfig()
config.saveState = false
miniapp.setData(data: ["deeplink" : "/help"]) // Example: '/path?id=123'
miniapp.setConfig(config: config)
miniapp.open(viewController: self)
```

### Android

```kotlin theme={"system"}
val appId = "<app_id>" // Get miniapp appId from deeplink
Boxo.getExistingMiniapp(appId)?.close()
Boxo.getMiniapp(appId)
    .setConfig(
        MiniappConfig.Builder()
            .setData(mapOf("deeplink" to "/help"))
            .saveState(false)
            .build()
    )
    .open()
```

### Capacitor

```javascript theme={"system"}
const appId = "<app_id>";  // Get miniapp appId from deeplink
Boxo.closeMiniapp({ appId: appId });
Boxo.openMiniapp({
    appId: appId,
    data: {'deeplink': '/help'}, // Example: '/path?id=123'
    saveState: false
});
```

### React Native

```javascript theme={"system"}
Boxo.closeMiniapp('[miniapp_id]');
Boxo.openMiniapp('[miniapp_id]',
 {
  data:{ deeplink:'/help' }, // Example: '/path?id=123'
  saveState: false
});
```

### Flutter

```dart theme={"system"}
const appId ="[app_id]"; // Get miniapp AppId from deeplink
Boxo.closeMiniapp(appId);
Boxo.openMiniapp(appId, data: {'deeplink': '/help'}, saveState: false);
```


# Error Codes
Source: https://boxo.mintlify.app/host-apps/ErrorCodes



| Error code                                     | Error message                                                                  |
| ---------------------------------------------- | ------------------------------------------------------------------------------ |
| NO\_INTEGRATION                                | No accepted integration exist. Do not retry.                                   |
| NOT\_IMPLEMENTED                               | Feature is not implemented. Do not retry.                                      |
| PROCESS\_FAIL                                  | General business failure occurred. Do not retry.                               |
| UNKNOWN\_ERROR                                 | Unknown error. Please try again later.                                         |
| UNEXPECTED\_RESPONSE\_ERROR                    | Unexpected response from the upstream service. See Dashboard Logs for details. |
| EXPIRED\_AUTH\_CODE                            | Auth code expired. Please try again.                                           |
| INVALID\_AUTH\_CODE                            | Invalid auth code. Please try again.                                           |
| EXPIRED\_ACCESS\_TOKEN                         | Access token expired. Please try again.                                        |
| INVALID\_ACCESS\_TOKEN                         | Invalid access token. Please try again.                                        |
| INVALID\_USER\_DATA                            | Invalid user data. Please try again.                                           |
| ACCESS\_DENIED                                 | Access denied.                                                                 |
| HOSTAPP\_NOT\_FOUND                            | No Hostapp client matches the given query.                                     |
| MINIAPP\_NOT\_FOUND                            | No Miniapp matches the given query.                                            |
| ORDER\_NOT\_FOUND                              | No Order matches the given query.                                              |
| INVALID\_PAYMENT\_STATUS                       | Cannot set this status to order payment.                                       |
| NOT\_A\_WHITELISTED\_IP                        | Not a whitelisted IP address. Please provide IP address in Dashboard.          |
| INVALID\_ORDER\_DATA                           | Invalid request body.                                                          |
| RESPONSE\_ATTRIBUTE\_MISSING                   | Missing response attribute: .                                                  |
| INVALID\_SIGNATURE                             | Invalid request signature.                                                     |
| MISSING\_HEADER                                | Missing required header: .                                                     |
| NOT\_IMPLEMENTED\_FOR\_THIS\_MINIAPP\_CATEGORY | Feature not implemented for this Miniapp category.                             |
| INVALID\_RESPONSE\_CONTENT\_TYPE               | Invalid response content type.                                                 |
| MISSING\_REQUEST\_SIGNATURE\_SETTINGS          | Request signature settings are not configured.                                 |
| HOSTAPP\_INTEGRATION\_NOT\_SET                 | Feature not integrated. Enable  in Hostapp settings.                           |
| MINIAPP\_INTEGRATION\_NOT\_SET                 | Feature not integrated. Enable  in Miniapp settings.                           |
| INTEGRATION\_ENABLED\_NOT\_SET                 | Feature disabled. Enable  in Integration settings.                             |
| HOSTAPP\_ENABLED\_NOT\_SET                     | Feature disabled. Enable  in Hostapp settings.                                 |
| FEATURE\_DISABLED\_IN\_HOSTAPP                 | Feature disabled. Enable  in Hostapp settings.                                 |
| FEATURE\_DISABLED\_IN\_MINIAPP                 | Feature disabled. Enable  in Miniapp settings.                                 |
| FEATURE\_DISABLED\_IN\_INTEGRATION             | Feature disabled. Enable  in Integration settings.                             |
| PARSING\_ERROR\_INVALID\_REQUEST\_BODY         | Failed to parse request body. Ensure it is valid JSON or a stream.             |
| FAILED\_TO\_PARSE\_RESPONSE                    | Failed to parse response. Ensure it is valid JSON.                             |
| DATA\_INTEGRITY\_ERROR                         | Data integrity violation.                                                      |
| SIGNATURE\_VALIDATION\_ERROR                   | Request signature validation failed.                                           |
| HOSTAPP\_USER\_ID\_REQUIRED                    | Hostapp user ID/reference is required for .                                    |
| HOSTAPP\_USER\_NOT\_FOUND                      | Hostapp user with hostapp\_user\_id:  does not exist.                          |
| INVALID\_PAYMENT\_STATUS\_RESPONSE             | Invalid payment status in Hostapp response.                                    |
| ENDPOINT\_URL\_NOT\_SET                        | Endpoint URL is not configured for .                                           |
| PLAN\_LIMIT\_REACHED                           | Plan limit reached. Upgrade your plan to continue.                             |


# Getting Started
Source: https://boxo.mintlify.app/host-apps/GettingStarted



To integrate the miniapp into your mobile application, you need to create a client application within the  [Boxo dashboard](https://dashboard.boxo.io/).

### Create a new host app client within the dashboard

1. To create a client host app go to [My host apps](https://dashboard.boxo.io/host-apps) and click **Add super app**.
2. Enter the name of your host app and click **Add super app**.
3. After successful host app creation you can see your hostapp details where you can find your host app's **client id**.

### Install Boxo SDK

Install one of our Boxo SDKs:

1. [iOS SDK](/host-apps/BoxoSDK#ios-sdk)
2. [Android SDK](/host-apps/BoxoSDK#android-sdk)
3. [Flutter SDK](/host-apps/BoxoSDK#flutter-sdk)
4. [React Native SDK](/host-apps/BoxoSDK#react-native-sdk)

### Launch miniapp

1. To start launching a miniapp inside your newly created host app, a miniapp integration request should be made if the miniapp is not owned by you. You can make the integration request from the miniapps's showroom page. Please provide details about your host app. (If you own the miniapp and want to launch it inside your host app then you are good to go. Simply find the miniapp's **app id** in the miniapp settings page and launch it.)
2. Our team will get in touch with the miniapp owner to complete the integration between your hostapp and their miniapp.
3. Once your integration is approved, you will be provided with a miniapp **app id** that you can use to start launching inside your host app


# Android / iOS Sample Host App
Source: https://boxo.mintlify.app/host-apps/SampleHostApp



Below you can find sample host app projects showcasing a few miniapp initializations, launches and interactions. They have examples of using custom events to trigger native payment systems within a miniapp.

* [Android sample host app](https://github.com/Appboxo/sample-android-hostapp)
* [iOS sample host app](https://github.com/Appboxo/sample-ios-hostapp)
* [ReactNative sample host app](https://github.com/Appboxo/sample-react-native-app)
* [Flutter sample host app](https://github.com/Appboxo/sample-flutter-app)

You can download Boxo Play app

* [iOS](https://testflight.apple.com/join/M8VHctgY)
* [Android](https://play.google.com/store/apps/details?id=io.boxo.go)


# Security measures
Source: https://boxo.mintlify.app/host-apps/SecurityMeasures



## Whitelisting

### For server-to-server calls

Boxo Payments and Boxo Connect functionalities will only work with whitelisted IP addresses. You can provide these in [Dashboard](https://dashboard.boxo.io/) host app overview page.

<img alt="Image" />

### Our IP addresses

We suggest to whitelist our IP addresses for all endpoints opened for Boxo Platform.

**Production environment** 18.136.43.253 - [https://dashboard.boxo.io/](https://dashboard.boxo.io/)

### Network recommendation

SaaS platform is accessed via secure HTTPS
(TLS 1.2+) over the public internet, and for
optimal performance, we recommend a stable
internet connection with minimum bandwidth
of 1 Mbps and latency below 250ms.

## Passing encrypted user data

**Boxo Connect** requires the host app to share sensitive user data with miniapps. To secure the data being passed, we recommend that the host app encrypt the user data before sharing it with miniapps. The decryption keys should be provided directly to miniapp owners through secure, private communication channels, ensuring that the data can only be decrypted by the miniapp's system. This approach minimizes security risks related to user data. For encryption, we suggest using **AES-256**, which is a robust and widely recognized encryption algorithm suitable for this purpose.

<img alt="Image1" />

## Request signaturing

**Boxo Connect** and **Boxo Payments** features enable server-to-server communication, facilitating seamless integration and interaction between applications and the Boxo platform. To ensure the integrity and security of the data exchanged between servers, **request signing** is employed as a critical mechanism. This process verifies that the data has not been tampered with during transmission and ensures secure interactions between systems.

### What is Request Signaturing

**Request signing** is a cryptographic process where a unique signature is attached to an HTTP request before it is transmitted. This signature is generated using a **private key**, known only to the sender, and can be verified by the recipient using the corresponding **public key**. This process ensures the authenticity of the sender and guarantees that the data has not been tampered with during transmission, providing both authentication and data integrity.

### Why Request Signaturing is Essential

1. **Authentication:**

   * Connect Feature: In Boxo Connect, servers interact to share user data and trigger specific actions. Request signaturing ensures that only authenticated servers can initiate requests, preventing unauthorized access and potential security breaches.

   * Payments Feature: For Boxo Payments, where financial transactions are involved, authentication becomes paramount. Request signaturing adds an extra layer of security, guaranteeing that payment requests originate from trusted sources.

2. **Integrity:**

   * Connect Feature: To maintain the integrity of data exchanged between servers in the Boxo Connect feature, request signaturing prevents data tampering during transit. This is vital for ensuring that the received data is exactly as intended by the sender.

   * Payments Feature: In financial transactions, even the slightest alteration of data can have significant consequences. Request signaturing safeguards the integrity of payment requests, ensuring that the transaction details remain unchanged.

3. **Non-Repudiation:**

   * Request signaturing enables non-repudiation, meaning that the sender cannot deny having initiated a particular request. This is crucial for accountability and auditing purposes, especially when dealing with sensitive user data and financial transactions.

4. **Secure Communication:**

   * By implementing request signaturing, Boxo ensures that communication between servers is conducted over a secure channel. This is fundamental for protecting user privacy, maintaining trust, and complying with security best practices.

### How to Implement Request Signaturing

* To implement request signaturing with Boxo Connect and Boxo Payments features, developers need to follow the provided guidelines and use the cryptographic libraries or tools recommended by Boxo.

* Private keys for signaturing should be securely stored and never shared publicly. Public keys are used by Boxo to verify the authenticity of incoming requests.


# Request Signaturing
Source: https://boxo.mintlify.app/host-apps/Signaturing



## Usage in Endpoints

### Validate Requests

* ["Get access\_token"](/host-apps/BoxoConnect#get-access-token) to Hostapp backend
* ["Create Order Payment"](/host-apps/BoxoPayments#1-create-order-payment-endpoint) to Hostapp backend
* ["Get Order Payment Status"](/host-apps/BoxoPayments#2-get-order-payment-status-endpoint) to Hostapp backend

### Signing Requests

["Complete Order Payment"](/host-apps/BoxoPayments#3-webhook-complete-order-payment) Webhook to Boxo Platform

## Settings Options

### Algorithms

Choose from three types of algorithms for signing requests and validating them:

* RSA2
* HMAC
* ECDSA

### Hash Function Used in Signature

Select the hash function used for the signature:

* MD5
* SHA-1
* SHA-224
* SHA-256
* SHA-384
* SHA-512

### Api Client ID

“Api client ID” is an identifier for a Hostapp’s API

### Key Format for RSA or ECDSA

For RSA2 and ECDSA, choose between:

* PEM
* DER

### Boxo public key

“Boxo public key” is used for validating request data on a Hostapp’s side.

### Hostapp public key

“Hostapp public key” is used for validating request data from a Hostapp. This key belongs to the private key on a Hostapp’s side.

### HMAC Secret

“HMAC Secret” is used in HMAC algorithm only.

### Headers Map

“Headers map” is a JSON field used to set up custom headers in case a Hostapp wants to utilize their own request signaturing. These fields should be mapped:

* signature
* timestamp
* nonce
* identity
* client\_id
* merchant\_id

### Default

```json theme={"system"}
{
  "nonce": "X-Nonce",
  "identity": "X-Identity",
  "client_id": "X-Client-Id",
  "signature": "X-Signature",
  "timestamp": "X-Timestamp",
  "merchant_id": "X-Merchant-Id"
}
```

### Signature Payload Template

“Signature payload template” is a string template field used to set up a custom payload format in case a Hostapp wants to utilize their own request signaturing. These fields should be mapped in the template:

* `{timestamp}`
* `{nonce}`
* `{identity}`
* `{client_id}`
* `{merchant_id}`
* `{request_method} - Example: “POST”, "GET"`
* `{url}`
* `{payload} - this is “Request data/body”`

### Signature Template

“Signature template” is a string template field used to set up a custom signature header format in case a Hostapp wants to utilize their own request signaturing. These fields should be mapped in the template:

* `{signature}`

### Timespec

**Timespec** is a field used when generating the current timestamp, defining the level of time precision. Examples include **seconds** or **milliseconds**, depending on the required accuracy for the timestamp in the request signing process.

### Identity

**Identity** is an optional static string that can be included in the signature payload and passed through headers to verify data integrity. If used, make sure to add it to the **Headers map** and include it in the **Signature payload template** as `{identity}` to ensure it's correctly incorporated into the request signing process.

### Nonce

A **Nonce** is an optional random string that can be included in the signature payload and passed through headers to verify data integrity. Its length is defined in the **Nonce length** parameter and can be enabled via the **Use nonce** option. If the nonce is used, make sure to include it in the **Headers map** and the **Signature payload template** as `{nonce}` to ensure it's properly accounted for in the request signing process.

### Encoding

* **Request data encoding for payload**: This field defines how the request data is encoded before it is formatted into the payload. It can either be encoded to **base64** or left as **plain text**.
* **Signature payload encoding**: This field specifies how the payload should be encoded before the signing process. The options are **base64** or **plain text**.
* **Signature encoding**: This field determines how the signature is encoded after the signing process. It can be encoded to **base64** or **hex** format.

### Request Data/Body

* **Use request data with spaces**: This option determines whether spaces are included in the request data when formatting the payload.
  * If **false**, the payload will be formatted without spaces: `{"a":"b"}`.
  * If **true**, the payload will include spaces: `{"a": "b"}`.

* **Sort request data keys**: This option specifies whether the keys in the request data should be sorted alphabetically when formatting the payload.
  * If **true**, the payload will have keys sorted: `{"a": "2", "b": "1"}`.
  * If **false**, the keys will remain in their original order: `{"b": "1", "a": "2"}`.

### Merchant ID

Merchant ID is an optional identifier unique to a Partnership. It is used to identify a miniapp in a Hostapp’s system. Don’t forget to add it in “Headers map” and to “Signature payload template” as  if used. Merchant ID can be also specified in a Partnership settings.

## Hostapp to provide

Please provide the following information to Boxo, after setup Boxo will provide you with a public key to verify the signature:

### Hostapp's settings

Here is a structured breakdown of the parameters used in the request signing process:

* **Algorithm (choice)**: The cryptographic algorithm used for signing:
  * Options: RSA2, HMAC, ECDSA

* **Hash function (choice)**: The hash function applied to the request:
  * Options: MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512

* **Key Format (choice)** (optional): The format for the private/public key pair:
  * Options: PEM, DER (Applicable only for RSA2 and ECDSA)

* **Hostapp public key (string)**: The public key of the host app in PKCS1 format, used by Boxo to verify the signature.

* **HMAC Secret (string)** (optional): A secret key used for HMAC algorithm only.

* **Headers map (JSON)** (optional): A JSON field used to configure custom headers if the host app wants to implement its own request signing.

* **Signature payload template (string)** (optional): A string template for setting up a custom payload format if the host app is using custom request signing.

* **Signature template (string)** (optional): A string template for setting up a custom signature header format if the host app is using custom request signing.

* **Timespec (string)**: Defines the time precision when generating the current timestamp.
  * Example values: seconds, milliseconds

* **Identity (string)** (optional): An identifier for the host app, used for recognition.

* **Nonce length (integer)** (optional): Defines the length of the nonce string.

* **Use nonce (boolean)** (optional): A boolean value indicating whether to use a nonce string.

* **Request data encoding for payload (choice)**: The encoding method for the request payload.
  * Options: base64, plain text

* **Signature payload encoding (choice)**: The encoding for the signature payload.
  * Options: base64, plain text

* **Signature encoding (choice)**: The encoding for the signature.
  * Options: base64, hex

* **Use request data with spaces (boolean)** (optional): Indicates whether spaces should be used in request data.

* **Sort request data keys (boolean)** (optional): Indicates whether the keys in the request data should be sorted.

* **Public Key (string)**: The public key in PKCS1 format for the Boxo Platform to verify the signature.

* **Client ID (string)**: A unique identifier for the host app for verification.

* **Merchant ID (string)** (optional): A unique identifier for the merchant associated with the host app.

This detailed structure ensures that both the host app and the Boxo platform can securely exchange data using request signing.

## Code examples

* Hash function - SHA-256
* Key Format - PEM
* Headers map - `{"signature": "X-Signature", "timestamp": "X-Timestamp", "client_id": "X-Client-Id"}`
* Signature payload template - `{timestamp}{client_id}{request_method}{url}{payload}`
* Signature template - `{signature}`
* Timespec - seconds
* Use nonce - false
* Request data encoding for payload - plain text
* Signature payload encoding - plain text
* Signature encoding - base64
* Use request data with spaces - false
* Sort request data keys - false

### RSA2

```py theme={"system"}
def sign_request(
    url, request_method, request_data, client_id, timestamp, 
):
    import rsa

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    signature = rsa.sign(
        payload.encode("utf-8"),
        rsa.PrivateKey.load_pkcs1(self._private_key),
        hash_method,
    )

    return base64.b64encode(signature).decode()
```

```py theme={"system"}
def verify_signature(
    signature, url, request_method, request_data, client_id, timestamp,
):
    import rsa
    from rsa.pkcs1 import VerificationError

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    signature = base64.b64decode(signature)
    try:
        rsa.verify(
            payload.encode("utf-8"),
            signature,
            rsa.PublicKey.load_pkcs1_openssl_pem(self._public_key),
        )
        return True
    except VerificationError:
        return False
```

### HMAC

```py theme={"system"}
def sign_request(
    url, request_method,  request_data, timestamp
):
    import hmac
    import hashlib

    keyEncoded = secret_key.encode()
    hash_method = hashlib.sha256

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=self._client_id,
        timestamp=timestamp,
        payload=request_data,
    )
    h = hmac.new(keyEncoded, payload.encode(), hash_method)

    generated_signature = base64.b64encode(h.digest()).decode("utf-8")

    return generated_signature
```

```py theme={"system"}
def verify_signature(
    signature, url, request_method, request_data, client_id, secret_key, timestamp
):
    import hmac
    import hashlib
    import base64


    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    keyEncoded = self._secret_key.encode()
    hash_method = hashlib.sha256
    h = hmac.new(keyEncoded, payload.encode(), hash_method)

    generated_signature = base64.b64encode(h.digest()).decode("utf-8")

    return hmac.compare_digest(signature, generated_signature)
```

### ECDSA

```py theme={"system"}
def sign_request(
    url, request_method, request_data, client_id, timestamp, 
):
    import hashlib
    from ecdsa import SigningKey
    from ecdsa.util import sigencode_der

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    sign_key = SigningKey.from_pem(self._private_key)
    signature = sign_key.sign(
        payload.encode(),
        hashfunc=hashlib.sha256,
        sigencode=sigencode_der,
    )

    return base64.b64encode(signature).decode()
```

```py theme={"system"}
def verify_signature(
    signature, url, request_method, request_data, timestamp, client_id
):  
    import hashlib
    from ecdsa import VerifyingKey
    from ecdsa.util import sigdecode_der

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    verifying_key = VerifyingKey.from_pem(self._public_key)
    return verifying_key.verify(
        base64.b64decode(signature),
        payload.encode(),
        hashfunc=hashlib.sha256,
        sigdecode=sigdecode_der,
    )
```


# Testing Host App
Source: https://boxo.mintlify.app/host-apps/Testing



To test **Boxo Connect** and custom events in action, try opening the **Boxo Store** sample miniapp using the **App ID**: `app36902`.

### Boxo Connect

To test Boxo's single sign-on feature, open Boxo Store and click on **Login** in the profile dropdown

### Custom events

To test custom events click on **Buy** button for any of the listed product list. Custom events should be in the form of:

```
{
  type: 'buy_from_miniapp',
  payload: {
    currency: 'USD',
    name: 'Teapot',
    price: 110,
  },
  request_id: 1
}
```


# Whitelisting
Source: https://boxo.mintlify.app/host-apps/Whitelisting



## IP Addresses

Due to the anticipated increase in platform load, we have set up auto-scaling and added another instance in a second Availability Zone for zero-downtime disaster recovery.
Now, we have two new IPs that need to be whitelisted on the client side for those using our app platform:

* 54.254.31.251 (MultiAZ instance)
* 18.136.51.105 (autoscaling instances)


# Introduction
Source: https://boxo.mintlify.app/host-apps/introduction



Boxo is redefining how apps interact with each other. The **Boxo SDK** allows users to instantly launch mini versions of various services within mobile apps, eliminating the need to download them from an app store. We provide developers with component libraries to create dynamic, high-performance, and customized miniapps that cater to specific business needs. Once a miniapp is developed and approved by the Boxo team, it will be featured in the **Showroom** (a platform similar to an app store for miniapps). From here, super apps can browse and select the products and services they wish to integrate into their app.


# Key Principles
Source: https://boxo.mintlify.app/host-apps/keyPrinciples



### Host App (Super App)

The host app is a native mobile application built on platforms such as iOS, Android, or other frameworks like React Native or Flutter. If a host app wants to enhance its functionality, it can leverage Boxo's technologies to accelerate this process. Boxo enables host apps to add value for their users by introducing new functionalities and creating additional revenue streams within the app.

### SDK for iOS and Android platforms

By integrating **Boxo's SDK**, the host app can seamlessly launch dozens of **miniapps** within the app, providing a native-like experience for users.

Current SDK sizes:

[**Android SDK**](/host-apps/BoxoSDK#android-sdk) - 0.7 MB

[**iOS SDK**](/host-apps/BoxoSDK#ios-sdk) - 1.7 MB

The team is continuously working to improve the product by reducing the SDK sizes for each platform.

### Exploring miniapps in Showroom for the host app

Once you register on the **Boxo Platform**, click **Showroom** on the left side of the Dashboard to view the full list of miniapps. Each miniapp has a unique **App ID**, which you'll need during the integration process. Familiarize yourself with the miniapps and ensure that their terms are acceptable before proceeding with the integration.

### Client ID

**client\_id** - is a unique id of your host app on Boxo.


# Start Building
Source: https://boxo.mintlify.app/main/homepage



<CardGroup>
  <Card title="HostApps" href="/host-apps/introduction" />

  <Card title="Miniapps" href="/miniapp/Intro" />

  <Card title="White-label miniapps" href="/mini-apps/esim/integration" />

  <Card title="API Reference" href="/MiniApp API Reference/EventsAPI" />
</CardGroup>

**Useful Links**

<CardGroup>
  <Card title="UI Best Practice" icon="square-check" href="/main/uibest" />

  <Card title="Changelog" icon="wrench" href="/changelog/flutter" />
</CardGroup>


# eSIM Integration
Source: https://boxo.mintlify.app/mini-apps/esim/integration



## Boxo Platform and Boxo SDK

In this section we will look at some additional integration details (such as user's locale) when working with Boxo Platform and Boxo SDK.

### Payment Payload

Here is the payload that Boxo will send via platform to host app backend.

```json theme={"system"}
{
  "currency": "CAD",
  "amount": "20.00",
  "subtotal_amount": "20.00",
  "shipping_amount": "0.00",
  "discount_amount": "0.00",
  "tax_title": "",
  "tax_amount": "5.00",
  "taxes_included": false,
  "note": "",
  "miniapp_order_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
  "hostapp_user_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
  "custom_attributes": {
    "plan_title": "5GB for 30 Days",
    "location": {
      "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
      "code": "ES",
      "title": "Spain",
      "type": "COUNTRY",
      "is_global": false
    },
    "provider_net_price": {
      "amount": "10.00",
      "currency": "CAD"
    },
    "data": 1024,
    "duration": 7,
    "order_type": "ACTIVATION"
  }
}
```

### Locale

Host app can provide language during initial launch and miniapp will be able to retrieve latest language settings.

```kotlin theme={"system"}
Appboxo.setConfig(Config.Builder().setClientId().setLanguage("en").build()))
```

### Closing miniapp and landing on Home page on next launch

In order to land on Home page each time miniapp is closed and reopened, a `saveState=false` can be passed. This behavior is available in versions starting from `v0.1.4`.

For example:

```kotlin theme={"system"}
Appboxo.openMiniapp({ appId: appId, saveState: false });
```

### Deeplinks

The deeplink URL should include miniapp id and the relevant URL route, if needed to land user on a specific page.

User will first deeplink to host app, then in host app it parses the deeplink and obtains the miniapp ID and the path to the page.

**Open the homepage of the miniapp**

```kotlin theme={"system"}
const appId = "<app_id>"  // Get miniapp appId from deeplink
Appboxo.closeMiniapp({ appId: appId });
Appboxo.openMiniapp({ appId: appId, saveState: false });
```

**Open a specific page within the miniapp**

```kotlin theme={"system"}
const appId = "<app_id>"  // Get miniapp appId from deeplink
Appboxo.closeMiniapp({ appId: appId });
Appboxo.openMiniapp({ appId: appId, data: {'deeplink': '/help'}, saveState: false });
// Deeplink contains root slash, path and query params. Example: '/path?id=123'
```

### Hide About from Menu

Available from SDK version `v0.1.6` (Capacitor v5) and `v0.2.4` (Capacitor v6).

```kotlin theme={"system"}
Appboxo.setConfig({ clientId: clientId, showAboutPage: false }); // By default showAboutPage is true
```

### Returning user who has NOT purchased an eSIM will launch into Explore page. Otherwise, will launch Homepage

```kotlin theme={"system"}
Appboxo.openMiniapp({ appId: appId, saveState: false, data: {havePurchasedSims: false } });
```

### Caching

Miniapp config is cached for 60 seconds. Logo and other related miniapp configuration changes should be reflected on next launch after 60 seconds have passed.

### Android compatibility check enhancement

Available from SDK version `v0.3.0` for Capacitor v6.

Instead of performing model check against a compatible device list, Android SDK will perform eSIM compatibility check using native method and pass on the result to eSIM miniapp.

The feature is supported inside the SDK, no code change needed on host app side.

## iOS direct installation

Here is an example of implementation of eSIM direct installation, sample code is also available [here](https://github.com/Appboxo/esim-direct-install).

```swift theme={"system"}
// JS SDK call AppBoxoEsimDirectInstall with direct install URL parameter
// SDK will check iOS version and open given URL
if #available(iOS 17.4, *) {
    guard let url = URL(string: url) else { return }

    if UIApplication.shared.canOpenURL(url) {
      UIApplication.shared.open(url)
    }
}
```

## Capacitor plugin

Capacitor plugin can be downloaded [here](https://www.npmjs.com/package/@appboxo/capacitor-boxo-sdk). Example code reference can be viewed [here](https://github.com/Appboxo/capacitor-appboxo-sdk/tree/main/example). Latest version: `v0.1.1` (includes changes to support play instruction video on Install Now page).

## Webhooks

Here are examples payloads for various webhooks that eSIM Miniapp BE will send, if you have provided use with the webhook URL.

eSIM backend will use `hostapp_client_id` and `hostapp_client_secret` configured in Boxo Platform and they will be passed as basic auth in `Authorization` header along with all requests. You can use this implement authentication for your webhook endpoint.

The `plan` object in webhook payloads includes a `location` object (the country or region the plan covers) and `title_translations`. Translated titles (`title_translations` on both the plan and its location) are included for the languages configured for your miniapp's webhooks; if no languages are configured, these objects are empty.

### eSIM order success

This event is fired when user successfully purchases a new eSIM or tops up existing eSIM.

```json theme={"system"}
{
  "event_type": "order.completed",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "6168918c-befc-46c4-9f2c-ca84c898bcf7",
    "external_source_payment_id": "261ba7b4-a578-451a-a05a-7ee26ba36e65",
    "order_type": "TOP_UP",
    "user_id": "eb275a7f-3b4c-4c35-881c-f5535d509202",
    "plan": {
      "id": "1bcc2d27-1863-4ef1-8a82-4f292511f5a2",
      "title": "2 GB - 15 days",
      "title_translations": {
        "en": "2 GB - 15 days",
        "es": "2 GB - 15 días"
      },
      "location": {
        "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
        "code": "AE",
        "title": "United Arab Emirates",
        "title_translations": {
          "en": "United Arab Emirates",
          "es": "Emiratos Árabes Unidos"
        },
        "type": "COUNTRY",
        "is_global": false
      }
    },
    "sim": {
      "id": "26a275d1-356d-4f59-92f7-640aded2c5ae",
      "iccid": "8900000261135167972"
    },
    "provider_net_local_price": {
      "amount": "10.00",
      "currency": "USD"
    },
    "subtotal": {
      "amount": "10.00",
      "currency": "USD"
    },
    "tax": {
      "amount": "0.00",
      "currency": "KZT"
    },
    "total": {
      "amount": "10.00",
      "currency": "USD"
    }
  }
}
```

### eSIM order failed

This event is fired when we were unable to fulfill given eSIM order. Hostapp can use it to initiate refund if this event is received. Can happen if eSIM is currently unavailable or eSIM provider is not available at given moment.

```json theme={"system"}
{
  "event_type": "order.failed",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "6168918c-befc-46c4-9f2c-ca84c898bcf7",
    "external_source_payment_id": "261ba7b4-a578-451a-a05a-7ee26ba36e65",
    "order_type": "TOP_UP",
    "user_id": "eb275a7f-3b4c-4c35-881c-f5535d509202",
    "plan": {
      "id": "1bcc2d27-1863-4ef1-8a82-4f292511f5a2",
      "title": "2 GB - 15 days",
      "title_translations": {
        "en": "2 GB - 15 days",
        "es": "2 GB - 15 días"
      },
      "location": {
        "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
        "code": "AE",
        "title": "United Arab Emirates",
        "title_translations": {
          "en": "United Arab Emirates",
          "es": "Emiratos Árabes Unidos"
        },
        "type": "COUNTRY",
        "is_global": false
      }
    },
    "sim": null,
    "provider_net_local_price": {
      "amount": "10.00",
      "currency": "USD"
    },
    "subtotal": {
      "amount": "10.00",
      "currency": "USD"
    },
    "tax": {
      "amount": "0.00",
      "currency": "KZT"
    },
    "total": {
      "amount": "10.00",
      "currency": "USD"
    }
  }
}
```

### eSIM order expired

This event is fired when if order hasn't been marked as completed / failed by the hostapp within 15 minutes of order creation. All orders in pending status get automatically cancelled after 15 minutes if no final status (paid or failed) received from the hostapp.

```json theme={"system"}
{
  "event_type": "order.expired",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "6168918c-befc-46c4-9f2c-ca84c898bcf7",
    "external_source_payment_id": "261ba7b4-a578-451a-a05a-7ee26ba36e65",
    "order_type": "TOP_UP",
    "user_id": "eb275a7f-3b4c-4c35-881c-f5535d509202",
    "plan": {
      "id": "1bcc2d27-1863-4ef1-8a82-4f292511f5a2",
      "title": "2 GB - 15 days",
      "title_translations": {
        "en": "2 GB - 15 days",
        "es": "2 GB - 15 días"
      },
      "location": {
        "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
        "code": "AE",
        "title": "United Arab Emirates",
        "title_translations": {
          "en": "United Arab Emirates",
          "es": "Emiratos Árabes Unidos"
        },
        "type": "COUNTRY",
        "is_global": false
      }
    },
    "sim": null,
    "provider_net_local_price": {
      "amount": "10.00",
      "currency": "USD"
    },
    "subtotal": {
      "amount": "10.00",
      "currency": "USD"
    },
    "tax": {
      "amount": "0.00",
      "currency": "KZT"
    },
    "total": {
      "amount": "10.00",
      "currency": "USD"
    }
  }
}
```

### eSIM activated

This event is fired when eSIM activates for the first time.

```json theme={"system"}
{
  "event_type": "sim.activated",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "26a275d1-356d-4f59-92f7-640aded2c5ae",
    "iccid": "8900000261135167972",
    "expired": "2026-06-12T11:33:43Z",
    "user_id": "eb275a7f-3b4c-4c35-881c-f5535d509202",
    "activated": "2026-06-12T11:33:43Z",
    "data_total": 0,
    "subscriptions": [
      {
        "id": "77ada95e-ca4c-4b47-b772-42b61e105172",
        "plan": {
          "id": "73def29d-99b0-4370-9100-4321ee6faabd",
          "title": "Unlimited - 3 days",
          "title_translations": {
            "en": "Unlimited - 3 days",
            "es": "Ilimitado - 3 días"
          },
          "location": {
            "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
            "code": "AE",
            "title": "United Arab Emirates",
            "title_translations": {
              "en": "United Arab Emirates",
              "es": "Emiratos Árabes Unidos"
            },
            "type": "COUNTRY",
            "is_global": false
          }
        },
        "status": "ACTIVE",
        "data_remaining": 924
      }
    ],
    "data_remaining": 924
  }
}
```

### eSIM expired

This event is fired when eSIM has expired (data run out or it reached expiry date).

```json theme={"system"}
{
  "event_type": "sim.expired",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "51a9e5f8-4962-4a40-8c3c-a8e2f641bfaf",
    "data": {
      "id": "95a20b92-12cf-434d-8998-23ee65944fb0",
      "iccid": "89424242426606109842",
      "expired": "2025-08-23T07:37:10Z",
      "user_id": "c671550c-88e9-4386-b072-70c9c378e40b",
      "activated": "2025-07-24T07:37:12Z",
      "data_total": 1024,
      "subscriptions": [
        {
          "id": "d11e8d86-9f46-4893-9d8c-eb9601b4d233",
          "plan": {
            "id": "8070b80e-61f9-419f-8711-543827e72b23",
            "title": "1 GB - 7 days",
            "title_translations": {
              "en": "1 GB - 7 days",
              "es": "1 GB - 7 días"
            },
            "location": {
              "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
              "code": "AE",
              "title": "United Arab Emirates",
              "title_translations": {
                "en": "United Arab Emirates",
                "es": "Emiratos Árabes Unidos"
              },
              "type": "COUNTRY",
              "is_global": false
            }
          },
          "status": "EXPIRED",
          "data_remaining": 1024
        }
      ],
      "data_remaining": 1024
    },
    "type": "sim.expired",
    "created": "2025-08-23T07:50:09.387684Z"
  }
}
```

### eSIM data zero

This event is fired when eSIM data remaining reaches 0.

```json theme={"system"}
{
  "event_type": "sim.data_zero",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "2699a0fa-d99b-443f-aa43-04e2dfc27856",
    "iccid": "8900000371411193282",
    "expired": "2026-06-05T08:30:46.581991Z",
    "user_id": "e0093bf4-6de7-4653-96c7-e6e10e77b3a6",
    "activated": "2026-06-09T14:23:16Z",
    "data_total": 0,
    "subscriptions": [
      {
        "id": "6c321664-cef9-4074-9331-8ec41cc6993d",
        "plan": {
          "id": "46cee6d0-7788-44ae-bd69-8a8e932b7ab9",
          "title": "1 GB - 7 days",
          "title_translations": {
            "en": "1 GB - 7 days",
            "es": "1 GB - 7 días"
          },
          "location": {
            "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
            "code": "AE",
            "title": "United Arab Emirates",
            "title_translations": {
              "en": "United Arab Emirates",
              "es": "Emiratos Árabes Unidos"
            },
            "type": "COUNTRY",
            "is_global": false
          }
        },
        "status": "EXPIRED",
        "data_remaining": 0
      }
    ],
    "data_remaining": 0
  }
}
```

### eSIM data running low

This event is fired when eSIM data has been used 75% or 90%.

```json theme={"system"}
{
  "event_type": "sim.data_low",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "2699a0fa-d99b-443f-aa43-04e2dfc27856",
    "iccid": "8900000371411193282",
    "expired": "2026-06-05T08:30:46.581991Z",
    "user_id": "e0093bf4-6de7-4653-96c7-e6e10e77b3a6",
    "activated": "2026-06-09T14:23:16Z",
    "data_total": 1024,
    "subscriptions": [
      {
        "id": "6c321664-cef9-4074-9331-8ec41cc6993d",
        "plan": {
          "id": "46cee6d0-7788-44ae-bd69-8a8e932b7ab9",
          "title": "1 GB - 7 days",
          "title_translations": {
            "en": "1 GB - 7 days",
            "es": "1 GB - 7 días"
          },
          "location": {
            "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
            "code": "AE",
            "title": "United Arab Emirates",
            "title_translations": {
              "en": "United Arab Emirates",
              "es": "Emiratos Árabes Unidos"
            },
            "type": "COUNTRY",
            "is_global": false
          }
        },
        "status": "ACTIVE",
        "data_remaining": 100
      }
    ],
    "data_remaining": 100
  }
}
```

### Webhook Simulator

This endpoint allows to simulate various webbhooks sent by eSIM backend. Webhook simulator is available at `<esim-backend-url>/api/v1/sources/<hostapp_name>/webhook/simulator/`.

Here as an example request to webhook simulator and it's payload:

```bash theme={"system"}
curl --location 'https://esim-staging.shopboxo.io/api/v1/sources/<hostapp_name>/webhook/simulator/' \
--header 'Content-Type: application/json' \
--data '{
    "app_id": "app_XXXXX",
    "event_type": "order.succeeded",
    "iccid": "893000000000057339",
    "reference": "06b66222-4ff4-4056-803b-dc81c74fcbdc"
}'
```

```json theme={"system"}
{
    "event_type": "order.succeeded",
    "iccid": "893000000000057339",
    "reference": "06b66222-4ff4-4056-803b-dc81c74fcbdc"
}
```


# Miniapp Analytics
Source: https://boxo.mintlify.app/miniapp/Analytics



**Boxo Analytics** enables tracking of key metrics such as views, session length, conversions, and other important data within miniapps. Our native SDK automatically tracks miniapp launches and session length, along with general usage data like IP address, session duration, and basic system information, including platform, OS version, and device model. This allows for comprehensive insights into user interactions and performance within miniapps.

## Analytics in Dashboard

To view analytics details in the dashboard, go to either **My miniapps** or **My host apps** and select the app whose analytics you want to view. The analytics data will be displayed under the **Analytics** tab.

## Sending postback transaction data

We require miniapp owners to send postback transaction data upon conversion

Example:

```js theme={"system"}
await appboxo.track({
  action: 'transaction',
  payload: {
    shipping: 0,
    tax: 0.57,
    discount: 2.25,
    currency_code: 'USD',
    customer: { // optional
      first_name: 'John',
      last_name: 'Doe',
      email: 'jdoe@domain.com',
      ip_address: '234.192.4.75'
    },
    items: [
      {
        name: 'Product name',
        description: 'Product description',
        price: 8.80,
        amount: 1,
        total: 8.80
      }
    ]
  }
})
```


# Custom Events
Source: https://boxo.mintlify.app/miniapp/CES



<Accordion title="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:

  ```js theme={"system"}
  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:

  ```js theme={"system"}

  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:

  ```js theme={"system"}
  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
    }
  });
  ```

  <br />

  # Boxo Event Bridge

  ***
</Accordion>

# Boxo Event Bridge

***

<Accordion title="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.

  <Steps>
    <Step title="Create event">
      An app (either hostapp or miniapp) creates an event with a specific event type and payload
    </Step>

    <Step title="Send to Boxo Platform">
      The app sends the event to the Boxo Platform via the Event Bridge API
    </Step>

    <Step title="Validate and authenticate">
      The Boxo Platform validates the event and authenticates the sender
    </Step>

    <Step title="Forward to recipient">
      The Boxo Platform forwards the event to the recipient's event receiver URL
    </Step>

    <Step title="Process event">
      The recipient processes the event and returns a response
    </Step>

    <Step title="Capture response">
      The Boxo Platform captures the response and forwards it to the original sender
    </Step>

    <Step title="Receive response">
      The original sender receives the response and can take appropriate actions
    </Step>
  </Steps>
</Accordion>

<Accordion title="Setting up the backend">
  \*Note: Feature must be enabled in [Dashboard](https://dashboard.boxo.io/host-apps/)

  **Data format**

  JSON is used for data exchange. Event payloads can contain any valid JSON structure that both the sender and receiver agree upon.

  <Accordion title="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](https://dashboard.boxo.io/host-apps/)

    **Headers:**

    | Key             | Value                                                             |
    | --------------- | ----------------------------------------------------------------- |
    | `Authorization` | `<prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)>` |
    | `Content-type`  | `application/json`                                                |

    * Default `<prefix>`: `Token`. Access token prefix can be set in [Boxo Connect](https://dashboard.boxo.io/host-apps/).
    * `hostapp_client_id` and `hostapp_secret_key` must be provided in [Dashboard](https://dashboard.boxo.io/host-apps/)

    **Body**

    | Field        | Data type | Description                                             |
    | ------------ | --------- | ------------------------------------------------------- |
    | `app_id`     | String    | Miniapp identifier                                      |
    | `client_id`  | String    | Hostapp identifier                                      |
    | `event_type` | String    | Event type identifying the purpose of the event         |
    | `payload`    | Object    | Event 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"
        }
    }'
    ```
  </Accordion>

  <Accordion title="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/events/hostapp/` endpoint

    **Headers**

    | Key             | Value                                                             |
    | --------------- | ----------------------------------------------------------------- |
    | `Authorization` | `<prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)>` |
    | `Content-type`  | `application/json`                                                |

    * Default `<prefix>`: `Token`. Access token prefix can be set in [Boxo Connect](https://dashboard.boxo.io/host-apps/).
    * `hostapp_client_id` and `hostapp_secret_key` must be provided in [Dashboard](https://dashboard.boxo.io/host-apps/)

    **Body**

    | Field               | Data type        | Description                                             |
    | ------------------- | ---------------- | ------------------------------------------------------- |
    | `app_id`            | String           | Miniapp identifier (recipient)                          |
    | `client_id`         | String           | Hostapp identifier (sender)                             |
    | `event_type`        | String           | Event type identifying the purpose of the event         |
    | `external_event_id` | String(Optional) | Event ID from Miniapp                                   |
    | `payload`           | Object           | Event 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/events/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"
        }
    }'
    ```
  </Accordion>
</Accordion>

<Accordion title="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 Type             | Description                               | Example Payload                                             |
  | ---------------------- | ----------------------------------------- | ----------------------------------------------------------- |
  | `user_profile_updated` | User profile information has been updated | `{"user_reference": "123", "email": "example@example.com"}` |

  ### Miniapp to Host App Events

  | Event Type            | Description                      | Example Payload                                                         |
  | --------------------- | -------------------------------- | ----------------------------------------------------------------------- |
  | `order_status_update` | Miniapp order fulfillment status | `{"order_payment_id": "order_123", "fulfillment_status": "delivering"}` |
</Accordion>

<Accordion title="Error Handling">
  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 recipient |
  | `INVALID_EVENT_DATA`      | The event data format is invalid                |
  | `EVENT_DELIVERY_FAILED`   | Failed to deliver the event to the recipient    |
  | `UNAUTHORIZED`            | Sender is not authorized to send events         |
</Accordion>

<Accordion title="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.
</Accordion>


# Boxo Connect
Source: https://boxo.mintlify.app/miniapp/Connect



**Boxo Connect** is a single sign-on functionality that allows the host app user to be authorized within the miniapp. In essence, the Boxo Platform facilitates the transfer of user data from the host app backend to the miniapp backend for user authorization, after which a session token is returned to the miniapp for continued access.

<Warning> **Notice**
Our backend will make a request for creating a user and for getting an authorization token. </Warning>

When creating a user, you need to generate a random password and send it to us via email. This password can be used by the user to log in to your service outside of the Boxo SDK.

### Prerequisites

* User authorization system

<Accordion title="Boxo Connect flow">
  Here is diagram showcasing the hostapp user authorization inside miniapp

  <img alt="Boxo Connect" />

  Here is the revised flow for better clarity:

  <Steps>
    <Step title="User launches miniapp">
      **User opens host app and launches miniapp**: The user opens the host app and starts the miniapp.
    </Step>

    <Step title="User identification required">
      **User should be identified to proceed with the flow**: This could involve product purchase, user registration, etc.
    </Step>

    <Step title="Miniapp calls login">
      **`appboxo.login()` is called from inside the miniapp**: The miniapp requests a login action via Boxo's SDK.
    </Step>

    <Step title="User consent requested">
      **User is asked for confirmation to give access to personal data**: The user is prompted to confirm sharing personal data necessary for the miniapp's authorization process.
    </Step>

    <Step title="SDK retrieves auth code">
      **Boxo's native SDK gets the auth code generated by the host app**: Boxo SDK receives the authorization code and sends an HTTPS request to the Boxo platform with the auth code.
    </Step>

    <Step title="Platform requests validation">
      **Boxo's platform sends an HTTPS request to the host app backend**: The Boxo platform sends the auth code to the host app's backend for validation.
    </Step>

    <Step title="Host app validates and returns token">
      **Host app backend validates the auth code and returns an access token**: The backend checks the auth code and sends back an access token.
    </Step>

    <Step title="Platform requests user data">
      **Boxo's platform sends an HTTPS request to the host app backend to get user data**: The Boxo platform requests the user data from the host app backend using the access token.
    </Step>

    <Step title="Host app returns user data">
      **Host app backend validates the access token and returns user data**: The host app backend confirms the validity of the access token and sends the user data back.
    </Step>

    <Step title="Platform forwards to miniapp">
      **Boxo's platform sends an HTTPS request with the user data to the miniapp backend**: Boxo platform forwards the user data to the miniapp backend for processing.
    </Step>

    <Step title="Miniapp processes user">
      **Miniapp backend either registers a new user or identifies an existing one**: The miniapp backend registers the user or identifies the existing user, then sends an authorization token back to Boxo platform.
    </Step>

    <Step title="Platform returns auth token">
      **Boxo platform sends back the authorization token to the Boxo native SDK**: The authorization token is sent back to the Boxo SDK that initiated the request.
    </Step>

    <Step title="Token passed to miniapp">
      **Authorization token is passed to the miniapp**: The token is provided to the miniapp.
    </Step>

    <Step title="Miniapp requests user data">
      **Miniapp makes a request with the token to get user data from the miniapp backend**: The miniapp sends the token to its backend for user data.
    </Step>

    <Step title="Backend returns user data">
      **Miniapp backend recognizes the token and sends back user data**: The miniapp backend verifies the token and returns the user data.
    </Step>

    <Step title="User authorized successfully">
      **User is authorized and continues with the miniapp flow**: The user is successfully authorized and can proceed with using the miniapp.
    </Step>
  </Steps>

  This process ensures a secure and seamless flow for user authorization between the host app, Boxo platform, and miniapp.
</Accordion>

<Accordion title="Setting up the backend">
  Note: Feature must be enabled in [Dashboard Partnership](https://dashboard.boxo.io/partnerships/)

  <img alt="Connect Enabled" />

  <Accordion title="Generate Auth Token">
    This endpoint is for the Boxo platform to send user data along with miniapp credentials and receive an authorization token in return.

    **URL and METHOD:**

    * This endpoint must handle a HTTPS POST request
    * URL to endpoint must be provided in [Dashboard](https://dashboard.boxo.io/miniapps)

      <img alt="Boxo Connect" />

    **Headers**

    |         Key         |                     Value                    |   |   |   |
    | :-----------------: | :------------------------------------------: | - | - | - |
    |    Authorization    | Basic `<base64 encoded(app_id:secret_key)> ` |   |   |   |
    | X-Hostapp-Client-ID |      `<client_id - Hostapp identifier>`      |   |   |   |
    |   X-Miniapp-App-ID  |        `<app_id - Miniapp identifier>`       |   |   |   |

    **Body:**

    |        Field       |  Data type  |                 Description                |   |   |
    | :----------------: | :---------: | :----------------------------------------: | - | - |
    |      reference     | String(100) |     Reference to user in Hostapp Server    |   |   |
    |        email       |    String   |         Verified user email address        |   |   |
    |        phone       |    String   | Verified user phone number in E.164 format |   |   |
    |     first\_name    |    String   |              User's first name             |   |   |
    |     last\_name     |    String   |              User's last name              |   |   |
    | custom\_attributes |     JSON    |              Custom attributes             |   |   |

    Response:

    * Response status must be `200` in all cases
    * Response body:

    |                 | Data type    | Optional                         | Description                                                                                                                                                |   |   |   |
    | :-------------- | ------------ | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | - | - | - |
    | `auth_token`    | String(1000) | No, except `error_code` provided | Authorization token for authenticating user in miniapp                                                                                                     |   |   |   |
    | `refresh_token` | String(1000) | Yes                              | Refresh token for `auth_token` miniapp                                                                                                                     |   |   |   |
    | `error_code`    | String       | Yes                              | If some error is occured error code should be provided. Example: `{"error_code": "INVALID_USER_DATA"}` All error codes can be found [here](/miniapp/Error) |   |   |   |

    **In the backend, follow these steps:**

    1. **For new users:**
       * Create a new user account with the received inputs for new users. Use `reference` field as identifier.
       * Ensure that the new user account is identical to the regular user accounts within your authorization system.

    2. **For existing users:**
       * If the user already exists in your database, generate an authorization token for the user and return it.

    3. **Return the access token:**
       * At the end of the login process, generate an authorization token.
       * The authorization token will serve as proof that the API calls made are from a specific user.
       * You can also specify the session expiry time according to your preferences.
       * You can also provide `refresh_token` for the session renewal without triggering connect flow again.

    Example:

    ```
    curl --location --request POST '[YOUR_SERVER_URL]/get_auth_token/' \
    --header 'Authorization: Basic {{BASE64_ENCODED_APP_ID_AND_SECRET_KEY}}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    	"reference": "{{HOSTAPP_USER_REFERENCE}}",
    	"email": "{{USER_EMAIL}}",
    	"phone": "{{USER_PHONE}}",
    	"first_name": "{{USER_FIRST_NAME}}"
    	"last_name": "{{USER_LAST_NAME}}"
    }'
    ```

    Add **Get Token URL** and **Required Fields** to miniapp settings

    On the **My miniapps** page, choose the miniapp, and go to settings. Enter **Get Auth Token URL** and **Required field** in the appropriate input fields.
  </Accordion>
</Accordion>

<Accordion title="Authorizing users at different phases of miniapp experience">
  You can authorize users at different stages based on your miniapp's user experience. This can occur either when the miniapp is launched or during the checkout process.

  When authorization is triggered, the Boxo SDK will prompt the user for permission to transfer their data from the host app to the miniapp. Once the **User** approves the request, the miniapp receives the access token, indicating that the user is successfully authorized.

  ```js theme={"system"}
  const handleLogin = async () => {
    try {
      const {
        // token string
        token
      } = await appboxo.login()
    } catch (error) {
      console.error(error)
      // Prompt authorization failure
    }
  }
  ```

  <Warning> **Notice**
  During successful authorization, Boxo JS SDK automatically saves a token with `ab_token` key to cookies. </Warning>
</Accordion>

<Accordion title="Logging out">
  Whenever you need to logout the user, you can call the `logout()` function, which will clear cookies and log out the user from the miniapp.

  ```js theme={"system"}
  const handleLogout = async () => {
    try {
      await appboxo.logout()
    } catch (error) {
      console.error(error)
      // Prompt logout failure
    }
  }
  ```
</Accordion>

<Accordion title="Security">
  You can secure the connection with the following methods.

  **IP Filter**

  You can set up an IP filter to secure the connection between Boxo and your miniapp. For security purposes, you should only accept requests from [Boxo's verified IP address](/miniapp/Security#our-ip-addresses). This ensures that the requests are coming from Boxo's trusted servers, adding an extra layer of protection to the communication.

  **Authorization Header**

  Boxo will send requests with a **Basic Authorization** header containing the **app\_id** and **secret\_key** provided in the Dashboard. These credentials ensure that the requests are authenticated and that only authorized applications can access the resources within the miniapp.
</Accordion>


# Design - UI/UX of Miniapps
Source: https://boxo.mintlify.app/miniapp/Design



Boxo Miniapps are native-like web apps that can be seamlessly integrated and launched within third-party native apps (Host Apps). To deliver the best user experience, they should be fast, simple, and efficient. These guidelines aim to help you create quick-loading, high-performance, and consistent user experiences across both Boxo miniapps and host apps. By following these principles, you can ensure smooth functionality, usability, and seamless interaction between the miniapp and host app environments.

**Miniapp should work equally well on all supported platforms**

Boxo iOS SDK is compatible with mobile clients running iOS 11.0 or higher. Similarly, Boxo Android SDK is designed to work with mobile clients running Android 5.0 (Lollipop) or higher. These versions ensure compatibility and allow users to leverage Boxo's features across a wide range of devices.

If service functionality is restricted due to factors such as geographical location, operating system version, or mobile app version, display a dedicated screen that clearly communicates the reason for the limitation. This will help users understand why the application is unavailable or why they cannot proceed further.

When testing the service, ensure thorough testing across all planned platforms. Additionally, we will soon release Boxo UI guidelines, which will include Boxo UI components for both Android and iOS apps, to help standardize and streamline development.

## Mini header

The upper right corner is occupied by native Boxo menu buttons. Do not place your navigation elements in this area. Developers cannot customize their content. When you need to add interactive elements around this menu, test and check the functionality and interactions of the elements with the native Boxo elements.

<img alt="Utilies only greens space in your UI/UX" />

*Utilise only green space in your UI/UX*

For the same reason, the title should be short or placed under the buttons so it doesn’t come too close to the native menu buttons. Be extra careful with the ios platform as as the headers are located in the center, leaving even less space for creativity. Header image Title should be short and meaningful.

The title of each page should be meaningful. There is no need to place the name of the miniapp on each page, rather ensure it reflects the essence of the specific page.

## Hostapp emulator

To test your miniapp, you can install our [Hostapp emulator](https://chrome.google.com/webstore/detail/appboxohostappemulator/aacgglamlcapoldmjiindjbpflkjpbpp) chrome extension that emulates the native app's behavior. You can see which API events are received from the miniapp and try sending different API events to test the miniapp's behavior.

<Warning> **WARNING**
The Host app emulator is under active development and not all API events are supported. Please stay tuned for more updates. </Warning>

## Take care of navigation

You can add navigation operations within the page based on your design requirements. There should be consistency in the navigation operations across all pages to facilitate forward and backward movements. This means using the same back button or logical tab navigation bar when moving between screens.

<img alt="NavigationBar" />

*Use native icons for navigation. Make it look native.*

Use the hardware back key on Android devices. On Android devices, clicking the Back button returns the user to previous screen action in the WebView. By pressing this button, the host app will return the user to the previous page of the host app or close the miniapp if it is impossible to return. To prevent the user from exiting your miniapp, make use of java scripts available routing libraries.

Make sure that input fields are saved when moving between screens. For example, if the user fills in the information for booking tickets on three different screens and suddenly realizes that the input on the first page was incorrect. Do not force the user to re-enter all the details.

If for some reason the transition between screens takes a considerable amount of time (for example, the miniapp uses a complex search query), use loaders or spinners to show the user that the miniapp is active and working and there is no need to leave.

## Use convenient buttons and readable fonts.

When developing a miniapp, it is important to remember that the Boxo iOS and Android SDK are used by many users with a variety of devices: the application should be equally convenient on screens of any size.

Fonts should be medium sized adaptive to the screen size of the device.

<img alt="Fonts" />

**Use system fonts whenever in doubt.**

The upper right corner of the miniapp is always occupied by the native menu buttons, so avoid using this area to place any of your buttons (like closing photo screen).

Navigation icons, buttons, and everything that can be tapped should be located in such a way so that the user does not accidentally touch the native buttons in the upper right corner and open a menu or close the miniapp.

It is worth making sure that the native buttons do not overlap with the design/navigation elements in the application.

Do not place long texts of multiple lines within buttons.

The layout of the miniapp should work equally well on all platforms from the standard iPhone 5s with a small screen as well as the Galaxy Note with a large diagonal.


# Error Codes
Source: https://boxo.mintlify.app/miniapp/Error



| Error code                                     | Error message                                                                  |
| ---------------------------------------------- | ------------------------------------------------------------------------------ |
| NO\_INTEGRATION                                | No accepted integration exist. Do not retry.                                   |
| NOT\_IMPLEMENTED                               | Feature is not implemented. Do not retry.                                      |
| PROCESS\_FAIL                                  | General business failure occurred. Do not retry.                               |
| UNKNOWN\_ERROR                                 | Unknown error. Please try again later.                                         |
| UNEXPECTED\_RESPONSE\_ERROR                    | Unexpected response from the upstream service. See Dashboard Logs for details. |
| EXPIRED\_AUTH\_CODE                            | Auth code expired. Please try again.                                           |
| INVALID\_AUTH\_CODE                            | Invalid auth code. Please try again.                                           |
| EXPIRED\_ACCESS\_TOKEN                         | Access token expired. Please try again.                                        |
| INVALID\_ACCESS\_TOKEN                         | Invalid access token. Please try again.                                        |
| INVALID\_USER\_DATA                            | Invalid user data. Please try again.                                           |
| ACCESS\_DENIED                                 | Access denied.                                                                 |
| HOSTAPP\_NOT\_FOUND                            | No Hostapp client matches the given query.                                     |
| MINIAPP\_NOT\_FOUND                            | No Miniapp matches the given query.                                            |
| ORDER\_NOT\_FOUND                              | No Order matches the given query.                                              |
| INVALID\_PAYMENT\_STATUS                       | Cannot set this status to order payment.                                       |
| NOT\_A\_WHITELISTED\_IP                        | Not a whitelisted IP address. Please provide IP address in Dashboard.          |
| INVALID\_ORDER\_DATA                           | Invalid request body.                                                          |
| RESPONSE\_ATTRIBUTE\_MISSING                   | Missing response attribute: .                                                  |
| INVALID\_SIGNATURE                             | Invalid request signature.                                                     |
| MISSING\_HEADER                                | Missing required header: .                                                     |
| NOT\_IMPLEMENTED\_FOR\_THIS\_MINIAPP\_CATEGORY | Feature not implemented for this Miniapp category.                             |
| INVALID\_RESPONSE\_CONTENT\_TYPE               | Invalid response content type.                                                 |
| MISSING\_REQUEST\_SIGNATURE\_SETTINGS          | Request signature settings are not configured.                                 |
| HOSTAPP\_INTEGRATION\_NOT\_SET                 | Feature not integrated. Enable  in Hostapp settings.                           |
| MINIAPP\_INTEGRATION\_NOT\_SET                 | Feature not integrated. Enable  in Miniapp settings.                           |
| INTEGRATION\_ENABLED\_NOT\_SET                 | Feature disabled. Enable  in Integration settings.                             |
| HOSTAPP\_ENABLED\_NOT\_SET                     | Feature disabled. Enable  in Hostapp settings.                                 |
| FEATURE\_DISABLED\_IN\_HOSTAPP                 | Feature disabled. Enable  in Hostapp settings.                                 |
| FEATURE\_DISABLED\_IN\_MINIAPP                 | Feature disabled. Enable  in Miniapp settings.                                 |
| FEATURE\_DISABLED\_IN\_INTEGRATION             | Feature disabled. Enable  in Integration settings.                             |
| PARSING\_ERROR\_INVALID\_REQUEST\_BODY         | Failed to parse request body. Ensure it is valid JSON or a stream.             |
| FAILED\_TO\_PARSE\_RESPONSE                    | Failed to parse response. Ensure it is valid JSON.                             |
| DATA\_INTEGRITY\_ERROR                         | Data integrity violation.                                                      |
| SIGNATURE\_VALIDATION\_ERROR                   | Request signature validation failed.                                           |
| HOSTAPP\_USER\_ID\_REQUIRED                    | Hostapp user ID/reference is required for .                                    |
| HOSTAPP\_USER\_NOT\_FOUND                      | Hostapp user with hostapp\_user\_id:  does not exist.                          |
| INVALID\_PAYMENT\_STATUS\_RESPONSE             | Invalid payment status in Hostapp response.                                    |
| ENDPOINT\_URL\_NOT\_SET                        | Endpoint URL is not configured for .                                           |
| PLAN\_LIMIT\_REACHED                           | Plan limit reached. Upgrade your plan to continue.                             |


# Getting Started
Source: https://boxo.mintlify.app/miniapp/GettingStarted



Getting started with Boxo as a miniapp is simple and can be broken down into three key steps:

1. **Optimize your web application for mobile**\
   Ensure that your web application is responsive and provides a seamless experience on mobile devices.

2. **Install the JS SDK**\
   Integrate the Boxo JS SDK into your miniapp to enable smooth interaction with the Boxo platform.

3. **Register your miniapp for approval**\
   Submit your miniapp for review and approval to ensure it meets Boxo's guidelines before being made available to users.

## JS SDK

Install the Boxo JS SDK package with:

```sh theme={"system"}
npm install @appboxo/js-sdk --save
# or
yarn add @appboxo/js-sdk
```

### Usage

<Tip> **TIP** If you would like to develop a miniapp from scratch, we recommend building it using a modern JavaScript frameworks such as React.js, Angular, Vue etc. as they provide the best optimization tools to make web applications perform faster. </Tip>

```js theme={"system"}
import appboxo from '@appboxo/js-sdk';

// Sends init event to host client
appboxo.send('AppBoxoWebAppInit');

// Subscribes to event, sent by host client
appboxo.subscribe(e => console.log(e));
```

<Tip> **TIP**
If you already have a lightweight mobile adaptive web app, you can easily install the Boxo JS SDK and start using its features. </Tip>

For use in a browser, include the file `/dist/index.umd.js` and use it as follows:

```html theme={"system"}
<script src="dist/index.umd.js"></script>

<script>
  // Sends init event to host client
  appboxo.send('AppBoxoWebAppInit');
</script>
```

<Tip> **TIP** See \[Boxo JS SDK API]\(/MiniApp API Reference/EventsAPI#sendpromise-method-params) for the full list of API </Tip>

or use [unpkg.com](https://unpkg.com/) if your want it from CDN:

```html theme={"system"}
<script src="https://unpkg.com/@appboxo/js-sdk"></script>
```

## Adding a miniapp to Boxo

### Add a miniapp

1. Sign in to the [Boxo Dashboard](https://dashboard.boxo.io/).

2. Click on the “Add miniapp” button located at the bottom of the screen. Alternatively, navigate to the “My miniapps” page and find the “Add miniapp” button at the footer.

### Miniapp name

1. Enter your miniapp name.

2. If you have an existing website or mobile app, use the existing name so that users can identify the existing products and services.

### Category

1. Select the appropriate category from the dropdown menu. (Please ensure you choose the correct category!)

2. If you cannot find a suitable category for your business, please reach out via email to [support@boxo.io](mailto:support@boxo.io).

### Description

Make sure your description is informative and detailed. Remember to include all your financial terms for potential partners. The description is an important aspect as it is a good way for new potential partners to learn about your business before deciding to integrate.

### Add app to Boxo Showroom

If you are not ready to make your published miniapp public on the showroom, simply turn off the toggle for *Add app* to *Boxo showroom*.

### URL

Enter the URL of your miniapp. All the miniapps should be hosted by the miniapp owner.

### Miniapp icon

A miniapp icon is a small logo that represents your business and appears during the launch of your miniapp. Ensure that the icon is in PNG format for optimal display.


# Introduction
Source: https://boxo.mintlify.app/miniapp/Intro



Boxo miniapps are native-like web applications designed to be integrated and launched within third-party native apps (host apps). By offering a native-like user experience, Boxo enables users to quickly access services within the apps they already use, providing a frictionless alternative to full native API integrations, deep-linking, or web linking via in-app or phone browsers. Existing solutions often fall short when it comes to driving traffic to third-party services, and Boxo aims to change that.

Boxo’s vision is to offer a superior user experience with minimal development effort. Built from the ground up, the platform ensures seamless mobile experiences that prioritize user engagement, facilitating transactions, and increasing customer retention.

For miniapp developers, Boxo provides easy-to-use tools for integrating and deploying miniapps within native apps. This creates a unique opportunity for developers to rapidly engage new users. Boxo offers a one-tap experience to launch miniapps, handle logins, and access APIs for communication with the native host app.

The platform’s simple API set makes it easy for miniapp developers to integrate their services into any host app they choose to partner with.


# Key Principles
Source: https://boxo.mintlify.app/miniapp/KeyP



As a miniapp developer, you must adhere to our guidelines to successfully launch your miniapp within the Boxo platform. Here are the key terms to familiarize yourself with:

* **Miniapp**: A mobile-adaptive web application developed with JavaScript, designed to seamlessly integrate within native mobile apps. It serves as an extension of native app functionality. If you already have a responsive web service, you can easily launch it as a miniapp on the Boxo platform using our guidelines.

* **App ID**: A unique identifier automatically assigned to each miniapp by Boxo. This ID helps differentiate miniapps within the platform.

* **Client ID**: A unique identifier for each host app. Boxo automatically assigns a Client ID on the dashboard, which is used for identifying and managing interactions with the host app.

* **Boxo JS SDK**: An npm library that acts as a bridge between a Boxo miniapp and the Boxo host app. It provides APIs to manage user authorization, facilitate data flow between the miniapp and host app, and track user activity.

* **Showroom**: A curated list of publicly available miniapps on the [Boxo Dashboard](https://dashboard.boxo.io/), where developers can submit their miniapps for review and integration into host apps.


# Native Components
Source: https://boxo.mintlify.app/miniapp/Native



Native components are UI components that are natively developed on the iOS and Android that can be used in combination with web UI components with the help of events from the JS SDK.

List of native components and native features that are available to your miniapp:

* [Navigation bar](/miniapp/Native#navigation-bar)
* [TabBar](/miniapp/Native#tab-bar)
* [QR code reader](/miniapp/Native#qr-code-reader)
* [Action sheet](/miniapp/Native#action-sheet)
* [Action buttons](/miniapp/Native#action-buttons)
* [Alert](/miniapp/Native#alert)
* [Geolocation](/miniapp/Native#geolocation)
* [Map](/miniapp/Native#map)
* [Image Gallery](/miniapp/Native#image-gallery)
* [Loading indicator](/miniapp/Native#loading-indicator)
* [Haptic feedback](/miniapp/Native#haptic-feedback)
* [Storage](/miniapp/Native#storage)
* [Clipboard](/miniapp/Native#clipboard)
* [Accelerometer](/miniapp/Native#accelerometer)
* [Gyroscope](/miniapp/Native#gyroscope)
* [Compass](/miniapp/Native#compass)

<br />

## Navigation bar

### `AppBoxoWebAppSetNavigationBar`

Activates native navigation bar.

<img alt="Navbar" />

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetNavigationBar', {
  title: 'Light nav bar',     // Navigation bar title
  backButton: true,           // Controls back button visibility
  background: '#ffffff',      // Navigation bar background color
  frontColor: '#000000',      // Navigation bar and status bar accent color
  show: true                  // Controls navigation bar visibility,
  isBackgroundTransparent: true,        // When set to true, will make background transparent
  frontColorWhenTransparent: '#ffffff', // Navigation bar and status bar accent color when navigation has transparent background
  changeBackgroundOnScroll: true        // Will smoothly change backgroound from transparent to `background` color on scroll
})
```

Sending event with only required changes will preserve initial options:

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetNavigationBar', {
  title: 'Changed some time later'
})
```

<br />

## Tab bar

### `AppBoxoWebAppSetTabBar`

Initialized native tab bar component

<img alt="tabbar" />

**Parameters**

* `show` **required** `boolean`
  Defines TabBar visibility

* `activeTab` **required** `number`
  Active TabBar item id

* `list` **required** `Array<{ tabId: number, tabName: string, tabIcon: string }>`
  Define tabs

* `options`  **required**  `{ color: string, background: string, selectedColor: string, hasBorder: boolean, borderColor: string }`
  Tab bar options

* `badges` **optional** `Array<{ tabId: number, background: string, color: string, value?: string }>`
  Define tab item badges.

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetTabBar', {
  show: true,
  activeTab: 1,
  list: [
    {
      tabId: 1,
      tabName: 'Home',
      tabIcon: ICON_URL
    },
    {
      tabId: 2,
      tabName: 'About',
      tabIcon: ICON_URL
    },
    {
      tabId: 3,
      tabName: 'Services',
      tabIcon: ICON_URL
    }
  ],
  badges: [
    {
      tabId: 1,
      background: '#ff0000',
      color: '#ffffff',
      value: '4'
    },
    {
      tabId: 3,
      background: '#ff0000',
      color: '#ffffff',
      value: '1'
    }
  ],
  options: {
    color: '#aaaaaa',
    background: '#ffffff',
    selectedColor: '#2eb8da',
    hasBorder: true,
    borderColor: '#dddddd'
  }
})
```

Sending event with only required changes will preserve initial options:

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetTabBar', {
  activeTab: 2
})
```

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetTabBar', {
  options: {
    color: '#ffffff',
    background: '#000000',
    selectedColor: '#2eb8da',
    hasBorder: false
  }
})
```

### `AppBoxoWebAppTabBarItemClick`

Event that should be subscribed to in order to get active tab item click

Example:

```js theme={"system"}
appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type, data } = event.detail

  if (type === 'AppBoxoWebAppTabBarItemClick') {
    if (data.tabId) {
      // Active tab id received
    }
  }
})
```

<br />

## QR code reader

### `AppBoxoWebAppOpenQRCodeReader`

Opens native QR code reader.

<img alt="QR Reader" />

*This method will prompt a permission request for camera.*

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppOpenQRCodeReader');
```

Results from QR code reader are received by events: `AppBoxoWebAppOpenQRCodeReaderResult` or `AppBoxoWebAppOpenQRCodeReaderFailed`

Example:

```js theme={"system"}
// Subscribe to events to receive data
appboxo.subscribe(event => {
  if (!event.detail) {
    return;
  }

  const { type, data } = event.detail;

  if (type === 'AppBoxoWebAppOpenQRCodeReaderResult') {
    // Reading result of the QR Code Reader
    console.log(data.code_data);
  }

  if (type === 'AppBoxoWebAppOpenQRCodeReaderFailed') {
    // Catching the error
    console.log(data.error_type, data.error_data);
  }
});
```

<br />

## Action sheet

### `AppBoxoWebAppShowActionSheet`

Shows native action sheet

<img alt="Action Sheet" />

**Parameters**

* `header` **optional** `string`
  Action sheet header text

* `list` **required** `Array<{ id: number, text: string, role?: 'cancel' | 'destructive' | 'selected' }>`
  Define action sheet items

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppShowActionSheet', {
  header: 'Albums',
  list: [
    {
      id: 1,
      text: 'Delete',
      role:'destructive'
    },
    {
      id: 2,
      text: 'Selected',
      role:'selected'
    },
    {
      id: 3,
      text: 'Share',
    },
    {
      id: 4,
      text: 'Play',
    },
    {
      id: 5,
      text: 'Cancel',
      role: 'cancel'
    }
  ]
})
```

### `AppBoxoWebAppActionSheetItemClick`

Event that should be subscribed to in order to get action sheet item click

Example:

```js theme={"system"}
appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type, data } = event.detail

  if (type === 'AppBoxoWebAppActionSheetItemClick') {
    if (data.id) {
      // Action sheet item id received
    }
  }
})
```

<br />

## Action buttons

### `AppBoxoWebAppSetActionButton`

Changes the params of action button

<img alt="Action Buttons" />

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppSetActionButton', {
  isLight: true, //optional - By default is value from MiniappSettings
  visible: true  //optional
})
```

<br />

## Alert

### `AppBoxoWebAppShowAlert`

Show native alert box

<img alt="Alert Box" />

**Parameters**

* `header` **optional** `string`
  Alert header text

* `message` **optional** `string`
  Alert message

* `buttons` **required**  `Array<{ id: number, text: string, role?: 'cancel' | 'destructive' }>`

  Define buttons

Example:

```js theme={"system"}
const showAlert = async () => {
  const data = await appboxo.sendPromise('AppBoxoWebAppShowAlert', {
    header: 'Native alert',
    message: 'This is a native alert box.',
    buttons: [
      {
        id: 1,
        text: 'Cancel',
        role:'destructive'
      },
      {
        id: 2,
        text: 'Ok'
      }
    ]
  });

  // Selected button
  const selectedButton = data.id
};
```

<br />

## Geolocation

### `AppBoxoWebAppGetGeodata`

Requests user geodata. This method will prompt a permission request to access geolocation.

<img alt="Geolocation" />

Example:

```js theme={"system"}
const getGeodata = async () => {
  const data = await appboxo.sendPromise('AppBoxoWebAppGetGeodata');

  return {
    isAvailable: !!data.available,
    lat: parseFloat(data.lat),
    long: parseFloat(data.long)
  };
};
```

<br />

## Map

### `AppBoxoWebAppChooseLocation`

Open full screen map to choose location

*This method will prompt a permission request to access geolocation.*

<img alt="Map" />

Example:

```js theme={"system"}
const chooseLocation = async () => {
  const data = await appboxo.sendPromise('AppBoxoWebAppChooseLocation');

  return {
    latitude: parseFloat(data.latitude),
    longitude: parseFloat(data.longitude)
  };
};
```

### `AppBoxoWebAppOpenLocation`

Open full screen map to that shows markered location

*This method will prompt a permission request to access geolocation.*

Example:

```js theme={"system"}
const openLocation = async () => {
  const data = await appboxo.sendPromise('AppBoxoWebAppOpenLocation', {
    latitude: 42.5264986,
    longitude: 74.5788997,
    scale: 13
  });

  console.log(data)

  // Returns:
  // {
  //   result: true
  // }
};
```

<br />

## Image gallery

### `AppBoxoWebAppShowImages`

Open full screen native image gallery

<img alt="Image Gallery" />

**Parameters**

`start_index` *optional* `number` Index to start showing from
`images` *required* `Array<string>` Image urls

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppShowImages', {
  images: [
    // image urls
  ]
});
```

After image gallery is closed, the same event will be dispatched back to the miniapp with result data.

Example:

```js theme={"system"}
appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type, data } = event.detail

  if (type === 'AppBoxoWebAppShowImages') {
    if (data.result) {
      // Image gallery has been shown successfully
    } else {
      // There were problems loading provided images
    }
  }
})
```

<br />

## Loading indicator

### `AppBoxoWebAppLoadingIndicator`

Shows native loading indicator.

<img alt="Loading Indicator" />

**Important:** Loading indicator will timeout after 30 seconds with prompt to hide it if no event is dispatched to change it.

Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppLoadingIndicator', {
  show: true
})
```

<br />

## Haptic feedback

### `AppBoxoWebAppVibrate`

Triggers haptic engine on the device, if available.

<img alt="Haptic Engine" />

Parameters

`style` *optional* `'light' | 'medium' | 'heavy'` Controls strength of vibration, defaults to 'light'.
Example:

```js theme={"system"}
appboxo.send('AppBoxoWebAppVibrate', {
  style: 'medium'
})
```

<br />

## Storage

### `AppBoxoWebAppStorageGet`

Requests a value from the storage

**Parameters**

`keys` *required* `Array<string>` Keys for getting (\[a-zA-Z\_-0-9])

Example:

```js theme={"system"}
const getUserData = async () => {
  const userData = await appboxo.sendPromise('AppBoxoWebAppStorageGet', {
    keys: ['username', 'email']
  });

  console.log(userData)

  // Returns:
  // {
  //   keys: [
  //     {
  //       key: 'username',
  //       value: 'John'
  //     },
  //     {
  //       key: 'email',
  //       value: 'john@doe.com'
  //     }
  //   ]
  // }
};
```

### `AppBoxoWebAppStorageGetKeys`

Request list of keys of some stored values

**Parameters**

`count` *required* `number` Count of keys to get. Max value is 1000
`offset` *optional* `number` The offset required to fetch a specific subset of keys. Default: 0

Example:

```js theme={"system"}
const getStorageKeys = async () => {
  const storageKeys = await appboxo.sendPromise('AppBoxoWebAppStorageGetKeys', {
    count: 10
  });

  console.log(storageKeys);

  // Returns:
  // {
  //   keys: ['username', 'email']
  // }
};
```

### `AppBoxoWebAppStorageSet`

Stores value in storage

**Parameters**

`key` *required* `string` The key of value (\[a-zA-Z\_-0-9])
`value` *optional* `string` value

Example:

```js theme={"system"}
const saveData = async ({ key, value }) => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStorageSet', {
    key,
    value
  });

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppStorageRemove`

Removes value in storage

**Parameters**

`key` *required* `string` The key of value (\[a-zA-Z\_-0-9])

Example:

```js theme={"system"}
const removeData = async ({ key }) => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStorageRemove', { key });

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppStorageClear`

Clears all data in storage

Example:

```js theme={"system"}
const clearStorage = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStorageClear');

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

<br />

## Clipboard

### `AppBoxoWebAppGetClipboard`

Gets the content on the system clipboard.

Example:

```js theme={"system"}
const getClipboard = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppGetClipboard');

  console.log(response);

  // Returns:
  // {
  //   data: 'from clipboard or null'
  // }
};
```

### `AppBoxoWebAppSetClipboard`

Sets the content on the system clipboard.

**Parameters**

`data` *required* `string` Content to be copied to clipboard

Example:

```js theme={"system"}
const setClipboard = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppSetClipboard', {
    data: 'copied to clipboard'
  });

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

<br />

## Accelerometer

### `AppBoxoWebAppStartAccelerometer`

Starts listening on acceleration data.

Example:

```js theme={"system"}
const startAccelerometer = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStartAccelerometer', {
    interval: 200 // Update interval in ms
  });

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppStopAccelerometer`

Stops listening on acceleration data.

Example:

```js theme={"system"}
const stopAccelerometer = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStopAccelerometer');

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppOnAccelerometerChange`

Listens on the acceleration data event. You can send `AppBoxoWebAppStopAccelerometer` event to stop listening.

Example:

```js theme={"system"}
appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type, data } = event.detail

  if (type === 'AppBoxoWebAppOnAccelerometerChange') {
    console.log(data.x)
    console.log(data.y)
    console.log(data.z)
  }
})
```

<br />

## Gyroscope

### `AppBoxoWebAppStartGyroscope`

Starts listening on gyroscope data.

Example:

```js theme={"system"}
const startAccelerometer = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStartGyroscope', {
    interval: 200 // Update interval in ms
  })

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

`AppBoxoWebAppStopGyroscope`

Stops listening on gyroscope data.

Example:

```js theme={"system"}
const stopAccelerometer = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStopGyroscope');

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppOnGyroscopeChange`

Listens on the gyroscope data event. You can send `AppBoxoWebAppStopGyroscope` event to stop listening.

Example:

```js theme={"system"}
appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type, data } = event.detail

  if (type === 'AppBoxoWebAppOnGyroscopeChange') {
    console.log(data.x)
    console.log(data.y)
    console.log(data.z)
  }
})
```

<br />

## Compass

### `AppBoxoWebAppStartCompass`

Starts listening on compass data.

Example:

```js theme={"system"}
const startCompass = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStartCompass')

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppStopCompass`

Stops listening on compass data.

Example:

```js theme={"system"}
const stopCompass = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStopCompass');

  console.log(response);

  // Returns:
  // {
  //   result: true
  // }
};
```

### `AppBoxoWebAppOnCompassChange`

Listens on the compass data event. You can send `AppBoxoWebAppStopCompass` event to stop listening.

Example:

```js theme={"system"}
appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type, data } = event.detail

  if (type === 'AppBoxoWebAppOnCompassChange') {
    console.log(data.direction)
  }
})
```


# Boxo Payments
Source: https://boxo.mintlify.app/miniapp/Payment



## Introduction

Boxo Payments is an integrated in-app payment solution that enables users of host apps to securely make payments for orders directly within a miniapp. By leveraging the Boxo platform, it simplifies the payment process, allowing users to complete transactions seamlessly without leaving the host app environment. This functionality ensures a smooth and secure payment experience for users, while providing miniapp developers with an easy-to-integrate solution for handling payments within their services.

<Accordion title="Boxo Payments flow">
  Here is diagram showcasing the payment of miniapp's order with the host app's payment system

  <img alt="Payments" />

  Here is the streamlined process for handling payment in a Boxo Miniapp:

  <Steps>
    <Step title="User reaches payment page">
      **User reaches the payment page** in the Miniapp and proceeds to create an order.
    </Step>

    <Step title="Miniapp creates order request">
      **Miniapp server** creates the order and sends a `createOrderPayment` request to the Boxo Platform.
    </Step>

    <Step title="Platform initiates payment">
      **Boxo Platform** initiates the payment request on the **Host app server**.
    </Step>

    <Step title="Host app returns payment ID">
      **Host app server** returns the `orderPaymentID` to the **Boxo Platform**.
    </Step>

    <Step title="Platform forwards payment ID">
      **Boxo Platform** returns the `orderPaymentID` to the **Miniapp server**.
    </Step>

    <Step title="Miniapp receives payment ID">
      **Miniapp server** sends the `orderPaymentID` to the **Miniapp**.
    </Step>

    <Step title="SDK processes payment">
      The **Miniapp** passes the `orderPaymentID` to the Boxo JS SDK `pay` method.
    </Step>

    <Step title="Native SDK displays confirmation">
      The **Boxo Native SDK** listens for the `pay` event triggered by the Boxo JS SDK and displays the payment confirmation page to the user.
    </Step>

    <Step title="User confirms payment">
      **User confirms the payment** on the payment confirmation page.
    </Step>

    <Step title="Host app processes payment">
      The **Host app** handles the payment and sends the payment status back to the Boxo JS SDK `pay` event.

      * During payment processing, the **Host app server** sends a callback to the **Boxo Platform** to update the order in the **Miniapp backend**.
    </Step>

    <Step title="Miniapp handles payment status">
      The **Miniapp** handles the payment status event from the Boxo JS SDK and updates the order payment status in the **Miniapp server**.
    </Step>

    <Step title="Payment status confirmation">
      **Miniapp** confirms the order payment status.

      * If the order is still processing, the **Miniapp** will request the payment status from the **Boxo Platform**, which in turn will request the payment status from the **Host app server**.
    </Step>

    <Step title="Display payment result">
      Finally, the **Miniapp** shows the **order payment status** page to the user.
    </Step>
  </Steps>
</Accordion>

<Accordion title="Setting up the backend">
  Note: Feature must be enabled in [Dashboard Partnership](https://dashboard.boxo.io/partnerships/)

  <img alt="PaymentEnabled" />

  **Data format**
  Currently, the Boxo platform uses JSON format for data exchange. When working with decimals, they are represented as either float, number, or string, with a maximum of 20 digits and 2 digits after the decimal point. Additionally, the data type definitions include limits on the size of strings, ensuring consistent and manageable data structures across systems.

  <Accordion title="1. Create Order Payment Request">
    This endpoint is on Boxo platform. Send request to create order payment (see step 2 in diagram).

    **URL and METHOD:**

    This is HTTPS POST `/api/v1/orders/create-order-payment/` endpoint
    IP address of requesting services must be provided in [Dashboard](https://dashboard.boxo.io/miniapps/) for whitelisting or [Request Signaturing](/miniapp/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           |
    |    order   | OrderDetails |    No    | Order info (amount, currency and etc.) |

    Here is the data for **OrderDetails**, **OrderItem**, and **OrderShippingAddress** in a clean, well-structured format:

    **OrderDetails**

    | Field                      | Data Type            | Optional | Description                                                                                                                                                                                                                                                                                  |
    | -------------------------- | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `currency`                 | String(20)           | No       | Order amount currency                                                                                                                                                                                                                                                                        |
    | `amount`                   | Decimal              | No       | Order amount                                                                                                                                                                                                                                                                                 |
    | `subtotal_amount`          | Decimal              | Yes      | Subtotal amount of the order                                                                                                                                                                                                                                                                 |
    | `shipping_amount`          | Decimal              | Yes      | Shipping cost                                                                                                                                                                                                                                                                                |
    | `discount_amount`          | Decimal              | Yes      | Discount applied on the order                                                                                                                                                                                                                                                                |
    | `tax_title`                | String(250)          | Yes      | Title of the tax applied                                                                                                                                                                                                                                                                     |
    | `tax_amount`               | Decimal              | Yes      | Tax amount                                                                                                                                                                                                                                                                                   |
    | `taxes_included`           | Bool                 | Yes      | Indicates whether taxes are included                                                                                                                                                                                                                                                         |
    | `wholesale_total`          | Decimal              | Yes\*    | Wholesale/settlement amount of the order. Deducted from the partner team balance when the order is paid. Forwarded to the host app create order payment request when provided. \***Required when the partner team has the [pre-paid model](/host-apps/BoxoPayments#pre-paid-model) enabled** |
    | `wholesale_total_currency` | String(20)           | Yes      | Currency of `wholesale_total`. Defaults to the team balance currency when omitted. Forwarded to the host app create order payment request when provided                                                                                                                                      |
    | `note`                     | String               | Yes      | Additional notes for the order                                                                                                                                                                                                                                                               |
    | `miniapp_order_id`         | String(250)          | Yes      | Order reference in the miniapp                                                                                                                                                                                                                                                               |
    | `hostapp_user_id`          | String(250)          | Yes      | User reference in the host app                                                                                                                                                                                                                                                               |
    | `items`                    | OrderItem\[]         | Yes      | List of items purchased in the order                                                                                                                                                                                                                                                         |
    | `shipping_address`         | OrderShippingAddress | Yes      | Shipping address information                                                                                                                                                                                                                                                                 |
    | `custom_attributes`        | JSON                 | Yes      | Custom attributes for the order                                                                                                                                                                                                                                                              |

    ***

    **OrderItem**

    | Field                  | Data Type   | Optional | Description                          |
    | ---------------------- | ----------- | -------- | ------------------------------------ |
    | `product_name`         | String(250) | Yes      | Name of the product                  |
    | `product_variant_name` | String(250) | Yes      | Name of the product variant          |
    | `product_sku`          | String(250) | Yes      | Product SKU                          |
    | `product_image_url`    | String(250) | Yes      | URL of the product image             |
    | `quantity`             | Integer     | Yes      | Quantity of the product in the order |
    | `price`                | Decimal     | Yes      | Price of the product                 |
    | `discount`             | Decimal     | Yes      | Discount applied to the product      |

    ***

    **OrderShippingAddress**

    | Field           | Data Type    | Optional | Description                                                           |
    | --------------- | ------------ | -------- | --------------------------------------------------------------------- |
    | `address1`      | String(1000) | Yes      | Address line 1                                                        |
    | `address2`      | String(1000) | Yes      | Address line 2                                                        |
    | `first_name`    | String(250)  | Yes      | First name of the recipient                                           |
    | `last_name`     | String(250)  | Yes      | Last name of the recipient                                            |
    | `phone`         | String(250)  | Yes      | Phone number of the recipient                                         |
    | `region_name`   | String(100)  | Yes      | Name of the region or state                                           |
    | `region_code`   | String(100)  | Yes      | Code of the region or state                                           |
    | `province_name` | String(250)  | Yes      | Name of the province                                                  |
    | `province_code` | String(250)  | Yes      | Code of the province                                                  |
    | `city`          | String(250)  | Yes      | City of the recipient                                                 |
    | `country`       | String(250)  | Yes      | Country of the recipient                                              |
    | `postal_code`   | String(250)  | Yes      | Postal code of the recipient                                          |
    | `latitude`      | Decimal      | Yes      | Latitude of the shipping address (up to 15 digits after the decimal)  |
    | `longitude`     | Decimal      | Yes      | Longitude of the shipping address (up to 15 digits after the decimal) |

    ***

    **Decimal Limits for Coordinates:**

    * **Latitude**: Max value: 90, Min value: -90, max 17 digits with 15 digits after the decimal point.
    * **Longitude**: Max value: 180, Min value: -180, max 18 digits with 15 digits after the decimal point.

    **Response:**

    * Response status will be `400` in case there is error\_code

    * **Response body:**

    |        Field       |  Data type  | Optional |                                                                         Description                                                                         |
    | :----------------: | :---------: | :------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------: |
    | order\_payment\_id | String(250) |    Yes   |                                                                   Order payment identifier                                                                  |
    |     error\_code    |    String   |    Yes   | If some error is occured error code should be provided. Example: `{"error_code": "INVALID_ORDER_DATA"}` All error codes can be found [here](/miniapp/Error) |

    **Request Example:**

    ```
        curl --location --request POST '[BOXO_PLATFORM_SERVER_URL]/api/v1/orders/create-order-payment/'\
        --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}}",
            "order": {
                "amount": "100.00",
                "currency": "USD",
                "miniapp_order_id": "{{ MINIAPP_ORDER_ID }}",
                "hostapp_user_id": "{{ HOSTAPP_USER_ID }}"
            }
        }'
    ```

    **Response Example:**

    ```
        {
            "order_payment_id": "8X566iHGnpUxHXPX3FH0iDsXUVn9ku16xJGQ"
        }
    ```

    ```
        {
            "error_code": "UNKNOWN_ERROR",
            "error_message": "Unknown error. Please try again later."
        }
    ```
  </Accordion>

  <Accordion title="2. Get Order Payment Status Request">
    This endpoint is on Boxo platform. Send request to get order payment status (see "Check order status" step in diagram).

    **URL and METHOD:**
    This is HTTPS POST `/api/v1/orders/get-payment-status/` endpoint
    IP address of requesting services must be provided in [Dashboard](https://dashboard.boxo.io/miniapps/) for whitelisting or [Request Signaturing](/miniapp/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    |
    | order\_payment\_id | String(250) |    No    | Order payment identifier |

    **Response:**

    * Response status will be

      `400`

      in case there is error\_code

    * Response body:

    |         Field         | Data type |                                                  Description                                                 |
    | :-------------------: | :-------: | :----------------------------------------------------------------------------------------------------------: |
    |   order\_payment\_id  |   String  |                                           Order payment identifier                                           |
    |        app\_id        |   String  |                                              Miniapp identifier                                              |
    |       client\_id      |   String  |                                              Hostapp identifier                                              |
    |    payment\_status    |   String  |                        Order payment status: `in_process\| paid\| cancelled \|failed `                       |
    | payment\_fail\_reason |   String  |                                           Order payment fail reason                                          |
    |      error\_code      |   String  | Error code. Example: `{"error_code": "ORDER_NOT_FOUND"}` All error codes can be found [here](/miniapp/Error) |

    **Request Example**

    ```
        curl --location --request POST '[BOXO_PLATFORM_SERVER_URL]/api/v1/orders/get-payment-status/'\
        --header 'Content-Type: application/json' \
        --data-raw '{
            "app_id": "{{MINIAPP_ID}}",
            "client_id": "{{CLIENT_ID}}",
            "order_payment_id": "{{ORDER_PAYMENT_ID}}"
        }'
    ```

    ```
        {
            "order_payment_id": "{{ORDER_PAYMENT_ID}}",
            "app_id": "{{MINIAPP_ID}}",
            "client_id": "{{CLIENT_ID}}",
            "payment_status": "failed",
            "payment_fail_reason": "Payment amount exceeds user's amount limit."
        }
    ```

    ```
        {
            "error_code": "ORDER_NOT_FOUND",
            "error_message": "No Order matches the given query."
        }
    ```
  </Accordion>

  <Accordion title="3. Webhook Complete Order Payment Endpoint">
    Setup this endpoint for Boxo platform to complete order payment(see step after 10 in diagram).

    **URL and METHOD:**
    This endpoint must handle a HTTPS POST request
    URL to endpoint must be provided in [Dashboard](https://dashboard.boxo.io/miniapps/)

    <img alt="Payments_miniApp" />

    * We suggest to whitelist our IP addresses for this endpoint.

    **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](https://dashboard.boxo.io/miniapps/)

    **Body:**

    |            Field            |  Data type  |                           Description                          |
    | :-------------------------: | :---------: | :------------------------------------------------------------: |
    |      miniapp\_order\_id     | String(250) |                    Miniapp order indentifier                   |
    | hostapp\_order\_payment\_id | String(250) |                    Order payment identifier                    |
    |     hostapp\_client\_id     | String(250) |                       Hostapp identifier                       |
    |       payment\_status       |    String   | Order payment status: `in_process\| paid\| cancelled\| failed` |
    |    payment\_fail\_reason    |    String   |                    Order payment fail reason                   |
    |      custom\_attributes     |     JSON    |                     Order custom attributes                    |

    **Response:**

    * Response status must be

      `200`

      in all cases

    * Response body:

    |    Field    | Data type |               Description              |
    | :---------: | :-------: | :------------------------------------: |
    |     code    |   String  | Request result code example: `SUCCESS` |
    | error\_code |   String  |               Error code               |

    **Request Example:**

    ```
        curl --location --request POST '[YOUR_SERVER_URL]/api/complete-order/' \
        --header 'Authorization: Basic {{BASE64_ENCODED_APP_ID_AND_SECRET_KEY}}' \
        --header 'Content-Type: application/json' \
        --data-raw '{
            "miniapp_order_id": "{{MINIAPP_ORDER_ID}}",
            "hostapp_client_id": "{{CLIENT_ID}}",
            "hostapp_order_payment_id": "{{ORDER_PAYMENT_ID}}",
            "payment_status": "paid"
        }'
    ```

    **Response Example:**

    ```
        {
            "code": "SUCCESS"
        }
    ```

    ```
        {
            "error_code": "ORDER_NOT_FOUND"
        }
    ```
  </Accordion>
</Accordion>

<Accordion title="Setting up the SDK">
  When the order is created payment should be handled on host app's side. Use `appboxoSdk.pay` method as in example to open payment pages on host app.

  ```
  const payResponse = await appboxoSdk.pay({
      amount,
      currency,
      miniappOrderId, // order reference
      orderPaymentId, // pass order_payment_id 
      extraParams: {},
  })
  const { status } = payResponse
  ```
</Accordion>


# Miniapp Performance
Source: https://boxo.mintlify.app/miniapp/Perf



Web app performance is a critical aspect of the success of Boxo miniapps. Given that users expect fast and seamless interactions, optimizing performance should be a top priority to ensure that the miniapp provides an engaging and efficient experience. Here's why performance matters and how it impacts both user experience and business growth:

### **Why Web App Performance Matters for Boxo Miniapps:**

1. **User Expectations:**
   * Users expect near-instantaneous load times, especially for mobile experiences. Slow load times or lags in miniapp performance can lead to high abandonment rates.

2. **Engagement & Retention:**
   * Fast performance directly correlates with better engagement. The faster users can complete tasks (such as browsing products, completing transactions, etc.), the more likely they are to return and use the app again.

3. **Conversion Rates:**
   * A slow miniapp can hurt conversion rates, especially during critical interactions like checkout or order placement. Minimizing delays and streamlining interactions can lead to higher sales and user satisfaction.

4. **Competitive Edge:**
   * In the competitive landscape of mobile services, users are more likely to stick with fast, efficient, and well-performing apps over slow or lagging ones.

### **How to Optimize Boxo Miniapp Performance:**

1. **Optimize JavaScript:**
   * Minimize and bundle your JavaScript files to reduce loading times.
   * Use efficient coding practices, avoid blocking resources, and leverage code-splitting for better load management.

2. **Efficient Asset Loading:**
   * Compress images and media files to reduce their size without compromising quality.
   * Use lazy loading for images and other resources to improve the app's initial load time.

3. **Mobile-First Design:**
   * Ensure the miniapp is optimized for mobile users. Responsive layouts that adapt to various screen sizes will enhance the user experience.

4. **Reduce HTTP Requests:**
   * Minimize the number of HTTP requests by bundling resources and utilizing efficient caching strategies.

5. **Server-Side Performance:**
   * Optimize backend services that support the miniapp to ensure quick data retrieval and seamless communication between the host app and miniapp.

6. **Monitoring and Optimization:**
   * Use performance monitoring tools to regularly analyze and track performance metrics. This can help you identify areas of improvement and maintain optimal speed and reliability.

### **Key Benefits of Optimized Performance:**

* **Higher User Satisfaction**: Faster apps lead to better user experiences and higher satisfaction.
* **Increased Conversion Rates**: Quick interactions encourage users to complete tasks, such as purchases or form submissions.
* **Improved Retention**: A fast, smooth app experience helps build trust and encourage repeat use.
* **Business Growth**: Optimized miniapps can lead to more positive reviews, higher user acquisition, and greater revenue.

By ensuring that your Boxo miniapp is fast and optimized, you can provide users with the seamless experience they expect, ultimately contributing to the success of your app and the satisfaction of your users.
Here we have collected some tools and guides that can help reach the best performance optimizations:

* [Why Performance Matters](https://developers.google.com/web/fundamentals/performance/why-performance-matters)
* [Web performance resources](https://developer.mozilla.org/en-US/docs/Learn/Performance/Web_Performance_Basics)
* [https://developers.google.com/speed](https://developers.google.com/speed)
* [https://www.webpagetest.org/](https://www.webpagetest.org/)
* [HTTP caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching)
* [12 Steps to a Faster Web App](https://auth0.com/blog/12-steps-to-a-faster-web-app/)


# Security Measures
Source: https://boxo.mintlify.app/miniapp/Security



## Whitelisting

### For server-to-server calls

Boxo Payments and Boxo Connect functionalities will only work with whitelisted IP addresses. You can provide these in [Dashboard](https://dashboard.boxo.io/) miniapp settings.

<img alt="Whitelist IP" />

### Our IP addresses

We suggest to whitelist our IP addresses for all endpoints opened for Boxo Platform.

**Production environment**

18.136.43.253 - [https://dashboard.boxo.io/](https://dashboard.boxo.io/)

## Passing encrypted user data

Boxo Connect requires the host app to share sensitive user data with miniapps. To ensure the security of this data during transfer, we recommend the following best practices:

1. **Data Encryption by Host App**: Host apps should encrypt sensitive user data before sharing it with miniapps.

2. **Decryption Keys**: The decryption keys should be securely shared with miniapp owners through private communication channels. This ensures that the data can only be decrypted by the miniapp system.

3. **Recommended Encryption Algorithm**: For securing user data, we recommend using **AES-256**, one of the most secure and widely accepted encryption algorithms.

4. **Security Risk Mitigation**: This approach reduces the risks associated with the transfer and decryption of sensitive user data.

For more information on data encryption, please contact the host app owners directly.

## Request signaturing

Boxo Connect and Boxo Payments are powerful features that enable smooth server-to-server communication, facilitating integration and interaction between your applications and the Boxo platform. To maintain the integrity and security of the data exchanged between servers, **request signing** is used as a critical security mechanism.

* **Request Signing**: This mechanism ensures that requests sent to the Boxo platform are authentic and secure, safeguarding against tampering or unauthorized access during data transmission.

### What is Request Signaturing

Request signaturing is a cryptographic process that involves attaching a unique signature to an HTTP request before it is transmitted. This signature is generated using a private key, known only to the sender, and can be verified by the recipient using the corresponding public key. This process ensures that the sender of the request is authenticated, and the data has not been tampered with during transmission.

### Why Request Signaturing is Essential

1. **Authentication:**

   * **Connect Feature:**

     In Boxo Connect, servers interact to share user data and trigger specific actions. Request signaturing ensures that only authenticated servers can initiate requests, preventing unauthorized access and potential security breaches.

   * **Payments Feature:**

     For Boxo Payments, where financial transactions are involved, authentication becomes paramount. Request signaturing adds an extra layer of security, guaranteeing that payment requests originate from trusted sources.

2. **Integrity:**

   * **Connect Feature:**

     To maintain the integrity of data exchanged between servers in the Boxo Connect feature, request signaturing prevents data tampering during transit. This is vital for ensuring that the received data is exactly as intended by the sender.

   * **Payments Feature:**

     In financial transactions, even the slightest alteration of data can have significant consequences. Request signaturing safeguards the integrity of payment requests, ensuring that the transaction details remain unchanged.

3. **Non-Repudiation:**

   * Request signaturing enables non-repudiation, meaning that the sender cannot deny having initiated a particular request. This is crucial for accountability and auditing purposes, especially when dealing with sensitive user data and financial transactions.

4. **Secure Communication:**

   * By implementing request signaturing, Boxo ensures that communication between servers is conducted over a secure channel. This is fundamental for protecting user privacy, maintaining trust, and complying with security best practices.

## How to Implement Request Signaturing

* To implement request signaturing with Boxo Connect and Boxo Payments features, developers need to follow the provided guidelines and use the cryptographic libraries or tools recommended by Boxo.

* Private keys for signaturing should be securely stored and never shared publicly. Public keys are used by Boxo to verify the authenticity of incoming requests.


# Miniapp Settings
Source: https://boxo.mintlify.app/miniapp/Settings



## Main Settings

### Token URL

This URL handles the user's session token and facilitates the creation of an active user session. It serves as the endpoint where the miniapp backend receives user data from the host app for account creation, returning the session token in the process.

### Required Fields

These are the essential input fields required for user registration within the miniapp. Ensure that all necessary fields are included to successfully register a user.

Each miniapp requires a set of minimum fields to create a user within its system and generate a session for the newly created user. The specific required fields for each miniapp can be customized on the Hostapp settings page.

<img alt="AuthDiagram" />

Following are examples of potential fields, though the list is not exhaustive

* email
* phone
* first\_name
* last\_name
* etc.

Where required fields will be returned in the following format:

```js theme={"system"}
{
  "requiredFields": [
    "first_name",
    "last_name",
    "email",
    "phone",
    "custom_attributes.address",
    "custom_attributes.city",
    "custom_attributes.identification_type",
    "custom_attributes.identification_number",
    "custom_attributes.date_of_birth"
  ]
}
```

### Whitelisted URLs

If your miniapp includes multiple URLs with different domains, you can ensure that they open seamlessly within the miniapp view by listing them in the **Whitelisted URLs** field. Boxo’s native SDK automatically filters URLs based on their domain. If a URL does not match any of the whitelisted domains, it will open in the phone’s default in-app browser.

***

## Display Properties

### Consent Screen

Consent screen will display required fields setup for user login upon preview, while scaling the consent screen based on the number of required fields created. In the following screen scalability of the consent screen is displayed. In certain cases, consent screen can be omitted, in cases where no sensitive information is being shared. You can contact us for more details on cases where consent screen display can be omitted.

<img alt="AuthDiagram" />

In cases where no required fields are populated, default consent screen will be displayed.

### Orientation

Define the orientation of your miniapp by selecting either **Portrait** or **Landscape** mode. By default, **Portrait** is selected.

### Action Buttons

Action buttons are built-in components provided by the SDK, enabling users to close or manage the miniapp. Choose between **Light** or **Dark** styles to define the appearance of the action buttons.

### Webview Size

Select the preferred size for the miniapp’s webview:

* **Full Screen**: Includes the status bar.
* **Safe Area**: Excludes the status bar. When selecting **Safe Area**, ensure you define a default status bar color.

***

## White-Labeling

When the **Inherit Host App Colors** option is enabled, the miniapp will inherit the color scheme from the host app. If the host app does not provide theming colors, be sure to define default color values to maintain consistency in the user interface.


# Request Signaturing
Source: https://boxo.mintlify.app/miniapp/Signaturing



## Usage in Endpoints

### Validate Requests

* ["Get authToken"](/miniapp/Connect#generate-auth-token) to Miniapp backend
* ["Complete Order Payment"](/miniapp/Payment#3-webhook-complete-order-payment-endpoint) Webhook to Miniapp backend

### Signing Requests

["Create Order Payment"](/miniapp/Payment#1-create-order-payment-request) to Boxo Platform
["Get Order Payment Status"](/miniapp/Payment#2-get-order-payment-status-request) to Boxo Platform

## Settings Options

### Algorithms

Choose from three types of algorithms for signing requests and validating them:

* RSA2
* HMAC
* ECDSA

### Hash Function Used in Signature

Select the hash function used for the signature:

* MD5
* SHA-1
* SHA-224
* SHA-256
* SHA-384
* SHA-512

### Api Client ID

“Api client ID” is an identifier for a Miniapp’s API

### Key Format for RSA or ECDSA

For RSA2 and ECDSA, choose between:

* PEM
* DER

### Boxo public key

“Boxo public key” is used for validating request data on a Hostapp’s side.

### Hostapp public key

“Hostapp public key” is used for validating request data from a Hostapp. This key belongs to the private key on a Hostapp’s side.

### HMAC Secret

“HMAC Secret” is used in HMAC algorithm only.

### Headers Map

“Headers map” is a JSON field used to set up custom headers in case a Hostapp wants to utilize their own request signaturing. These fields should be mapped:

* signature
* timestamp
* nonce
* identity
* client\_id
* merchant\_id

### Default

```json theme={"system"}
{
  "nonce": "X-Nonce",
  "identity": "X-Identity",
  "client_id": "X-Client-Id",
  "signature": "X-Signature",
  "timestamp": "X-Timestamp",
  "merchant_id": "X-Merchant-Id"
}
```

### Signature Payload Template

“Signature payload template” is a string template field used to set up a custom payload format in case a Hostapp wants to utilize their own request signaturing. These fields should be mapped in the template:

* `{timestamp}`
* `{nonce}`
* `{identity}`
* `{client_id}`
* `{merchant_id}`
* `{request_method} - Example: “POST”, "GET"`
* `{url}`
* `{payload} - this is “Request data/body”`

### Signature Template

“Signature template” is a string template field used to set up a custom signature header format in case a Hostapp wants to utilize their own request signaturing. These fields should be mapped in the template:

* `{signature}`

### Timespec

“Timespec” is a field used while generating the current timestamp, defining time precision. Example: seconds, milliseconds

### Identity

“Identity” is an optional static string that can be used in the signature payload and passed with headers to verify data integrity. Don’t forget to add it in “Headers map” and to “Signature payload template” as  if used.

### Nonce

“Nonce” is an optional random string that can be used in the signature payload and passed with headers to verify data integrity. Length is set in “Nonce length”. Enabled via “Use nonce”. Don’t forget to add it in “Headers map” and to “Signature payload template” as  if used.

### Encoding

“Request data encoding for payload” is a field that encodes Request data to “base64” or leaves it as plain text before formatting payload.

“Signature payload encoding” is a field that encodes the payload to “base64” or leaves it as plain text before signing it.

“Signature encoding” is a field that encodes the signature from bytes to “base64” or “hex” after signing payload.

### Request Data/Body

“Use request data with spaces”

Example: If false `{"a": "b"}` will become `{"a":"b"}` in payload, if true `{"a":"b"}` will become `{"a": "b"}` in payload

“Sort request data keys”

Example: If true `{"b": "1", "a": "2"}` will become `{"a": "2", "b": "1"}` in payload

### Merchant ID

Merchant ID is an optional identifier unique to a Partnership. It is used to identify a miniapp in a Hostapp’s system. Don’t forget to add it in “Headers map” and to “Signature payload template” as  if used. Merchant ID can be also specified in a Partnership settings.

## Miniapp to provide

Please provide the following information to Boxo, after setup Boxo will provide you with a public key to verify the signature:

### **Miniapp's settings**

* Algorithm (choice) - RSA2, HMAC, ECDSA
* Hash function (choice) - MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512
* Key Format (choice) optional - PEM, DER (For RSA2 and ECDSA only)
* Miniapp public key (string) - Public Key (string) PKCS1 - Private key for a Miniapp to verify the signature
* HMAC Secret (string) optional - Secret for a HMAC algorithm only
* Headers map (JSON) optional - JSON field used to set up custom headers in case a Miniapp wants to utilize their own request signaturing
* Signature payload template (string) optional - String template field used to set up a custom payload format in case a Miniapp wants to utilize their own request signaturing
* Signature template (string) optional - String template field used to set up a custom signature header format in case a Miniapp wants to utilize their own request signaturing
* Timespec (string) - Field used while generating the current timestamp, defining time precision. Example: seconds, milliseconds
* Identity (string) optional - Any identifier for a Miniapp's identification
* Nonce length (integer) optional - Length of a Nonce string
* Use nonce (boolean) optional - Use Nonce string
* Request data encoding for payload (choice) - base64, plain text
* Signature payload encoding (choice) - base64, plain text
* Signature encoding (choice) - base64, hex
* Use request data with spaces (boolean) optional - Use spaces in request data
* Sort request data keys (boolean) optional - Sort request data keys
* Public Key (string) PKCS1 - Private key for a Boxo Platform to verify the signature
* Client ID (string) - Client ID for a Miniapp's identification
* Merchant ID (string) optional - Merchant ID for a Miniapp's identification

## Code examples

* Hash function - SHA-256
* Key Format - PEM
* Headers map - `{"signature": "X-Signature", "timestamp": "X-Timestamp", "client_id": "X-Client-Id"}`
* Signature payload template - `{timestamp}{client_id}{request_method}{url}{payload}`
* Signature template - `{signature}`
* Timespec - seconds
* Use nonce - false
* Request data encoding for payload - plain text
* Signature payload encoding - plain text
* Signature encoding - base64
* Use request data with spaces - false
* Sort request data keys - false

### RSA2

```py theme={"system"}
def sign_request(
    url, request_method, request_data, client_id, timestamp, 
):
    import rsa

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    signature = rsa.sign(
        payload.encode("utf-8"),
        rsa.PrivateKey.load_pkcs1(self._private_key),
        hash_method,
    )

    return base64.b64encode(signature).decode()
```

```py theme={"system"}
def verify_signature(
    signature, url, request_method, request_data, client_id, timestamp,
):
    import rsa
    from rsa.pkcs1 import VerificationError

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    signature = base64.b64decode(signature)
    try:
        rsa.verify(
            payload.encode("utf-8"),
            signature,
            rsa.PublicKey.load_pkcs1_openssl_pem(self._public_key),
        )
        return True
    except VerificationError:
        return False
```

### HMAC

```py theme={"system"}
def sign_request(
    url, request_method,  request_data, timestamp
):
    import hmac
    import hashlib

    keyEncoded = secret_key.encode()
    hash_method = hashlib.sha256

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=self._client_id,
        timestamp=timestamp,
        payload=request_data,
    )
    h = hmac.new(keyEncoded, payload.encode(), hash_method)

    generated_signature = base64.b64encode(h.digest()).decode("utf-8")

    return generated_signature
```

```py theme={"system"}
def verify_signature(
    signature, url, request_method, request_data, client_id, secret_key, timestamp
):
    import hmac
    import hashlib
    import base64


    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    keyEncoded = self._secret_key.encode()
    hash_method = hashlib.sha256
    h = hmac.new(keyEncoded, payload.encode(), hash_method)

    generated_signature = base64.b64encode(h.digest()).decode("utf-8")

    return hmac.compare_digest(signature, generated_signature)
```

### ECDSA

```py theme={"system"}
def sign_request(
    url, request_method, request_data, client_id, timestamp, 
):
    import hashlib
    from ecdsa import SigningKey
    from ecdsa.util import sigencode_der

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    sign_key = SigningKey.from_pem(self._private_key)
    signature = sign_key.sign(
        payload.encode(),
        hashfunc=hashlib.sha256,
        sigencode=sigencode_der,
    )

    return base64.b64encode(signature).decode()
```

```py theme={"system"}
def verify_signature(
    signature, url, request_method, request_data, timestamp, client_id
):  
    import hashlib
    from ecdsa import VerifyingKey
    from ecdsa.util import sigdecode_der

    payload = self._payload_template.format(
        request_method=request_method,
        url=url,
        client_id=client_id,
        timestamp=timestamp,
        payload=request_data,
    )

    verifying_key = VerifyingKey.from_pem(self._public_key)
    return verifying_key.verify(
        base64.b64decode(signature),
        payload.encode(),
        hashfunc=hashlib.sha256,
        sigdecode=sigdecode_der,
    )
```


# Testing
Source: https://boxo.mintlify.app/miniapp/Testing



## Host App Emulator

For debugging purposes, you can use the Host App Emulator Chrome extension. This tool simulates the native app’s behavior, allowing you to monitor API events received from the miniapp. You can also send different API events to test how the miniapp responds.

<Check>**The Host App Emulator** is actively being developed, and not all API events are currently supported. Stay tuned for updates.</Check>


# Miniapp White-labeling
Source: https://boxo.mintlify.app/miniapp/WhiteLabel



Boxo miniapps can be customized to match the appearance of the host app. This means that the same miniapp can have different visual styles depending on the host app it’s launched in.

### White-Labeling Process:

To enable white-labeling, host app theming colors and details, such as the host app’s name and logo, are provided to the miniapp within its settings.

### Steps to Get Started:

<Steps>
  <Step title="Enable Inheritance of Host App Colors">
    Turn on **Inherit host app colors** within the miniapp settings. Additionally, provide default colors for scenarios where the host app doesn't share its theming colors.
  </Step>

  <Step title="Retrieve Miniapp Settings">
    Call the `AppBoxoWebAppGetMiniappSettings` event to retrieve the miniapp's settings.
  </Step>

  <Step title="Apply UI Customizations">
    Update the UI accordingly, using the data provided in the settings.
  </Step>
</Steps>

Here is an example of overriding CSS custom properties (variables):

```js theme={"system"}
appboxo.sendPromise('AppBoxoWebAppGetMiniappSettings').then(({ miniapp_settings }) => {
  // Data inside:
  // miniapp_settings = {
  //   colors: {
  //     primary_color: '#2EB8DA',
  //     secondary_color: '#E84060',
  //     tertiary_color: '#001529'
  //   },
  //   hostapp: {
  //     name: 'Boxo',
  //     logo: 'https://appboxo.com/img/Logo.svg'
  //   }
  // }

  document.head.insertAdjacentHTML('beforeend', `<style>
    :root {
      --primary-color: ${miniapp_settings.colors.primary_color};
      --secondary-color: ${miniapp_settings.colors.secondary_color};
      --tertiary-color: ${miniapp_settings.colors.tertiary_color};
    }
  </style>`)
}).catch(err => console.log(err));
```