> ## Documentation Index
> Fetch the complete documentation index at: https://boxo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

## 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'
})
```