API Reference - Boxo Documentation

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

TIP There is a shortcut .getInitData() that handles saving details above in cookies or localStorage and returns a Promise.

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:

appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type } = event.detail

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

Authentication

`AppBoxoWebAppLogin`

Example:

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

TIP There is a shortcut that you can use:

appboxo.login(data).then(response => {
   console.log(response)
 }).catch(error => {
   console.log(error)
 })

`AppBoxoWebAppLogout`

Logout and clear session token

Example:

const logout = async (data) => {
  await appboxo.sendPromise('AppBoxoWebAppLogout')
}

TIP There is a shortcut that you can use:

 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 This event is available from version 1.3.13 and above

`AppBoxoWebAppPay`

Send payment event to host app

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

Parameters

transactionToken required string Transaction token
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:

appboxoSdk.send('AppBoxoWebAppPay', {
  transactionToken: "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

transactionToken : string Transaction token
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:

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:

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:

appboxo.send('AppBoxoWebAppSetTabBar', {
  activeTab: 2
})

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:

appboxo.subscribe((event) => {
  if (!event.detail) {
    return
  }

  const { type, data } = event.detail

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

`AppBoxoWebAppSetNavigationBar`

Activates native navigation bar.

Example:

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:

appboxo.send('AppBoxoWebAppSetNavigationBar', {
  title: 'Changed some time later'
})

Action buttons

`AppBoxoWebAppSetActionButton`

Changes actions button theme. By default it is dark.

Example:

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:

appboxo.send('AppBoxoWebAppLoadingIndicator', {
  show: true
})

QR code reader

`AppBoxoWebAppOpenQRCodeReader`

Opens native QR code reader.

This method will prompt a permission request for camera.

Example:

appboxo.send('AppBoxoWebAppOpenQRCodeReader');

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

Example:

// 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:

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:

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:

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:

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:

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:

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:

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:

appboxo.send('AppBoxoWebAppShowImages', {
  images: [
    // image urls
  ]
});

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

Example:

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:

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:

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:

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:

const removeData = async ({ key }) => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStorageRemove', { key });

  console.log(response);

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

`AppBoxoWebAppStorageClear`

Clears all data in storage

Example:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

const startCompass = async () => {
  const response = await appboxo.sendPromise('AppBoxoWebAppStartCompass')

  console.log(response);

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

`AppBoxoWebAppStopCompass`

Stops listening on compass data.

Example:

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:

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.

appboxo.send('AppBoxoWebAppSetBackgroundColor', {
  color: '#ff0000'
});

Status bar color

`AppBoxoWebAppSetStatusBarColor`

Dynamically sets the status bar color

appboxo.send('AppBoxoWebAppSetStatusBarColor', {
  color: '#ffffff'
})

Tracking

`AppBoxoWebAppTrack`

Send postback tracking data about transaction

Example:

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

TIP There is a shortcut that you can use to send tracking data:

appboxo.track(data).then(response => {
  console.log(response)
}).catch(error => {
  console.log(error)
})

Custom events

`AppBoxoWebAppCustomEvent`

Send custom event to host app.

Example:

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:

appboxo.send('AppBoxoWebAppDownloadFile', {
  url: 'url',  
  file_name: 'filename.png'
})

`AppBoxoWebAppShare`

Send event to open native share modal

Example:

appboxo.send('AppBoxoWebAppShare', {
  text: 'text',   
  url: 'url',  
  file_name: 'filename.png'
})

​Miniapp initialization

​AppBoxoWebAppInit

​AppBoxoWebAppGetInitData

​Miniapp manipulation

​AppBoxoWebAppOpenMiniApp

​AppBoxoWebAppCloseMiniApp

​AppBoxoWebAppOnRestore

​Authentication

​AppBoxoWebAppLogin

​AppBoxoWebAppLogout

​AppBoxoWebAppClearToken

​AppBoxoWebAppSaveToken

​Appboxo Pay

​AppBoxoWebAppPay

​Tab bar

​AppBoxoWebAppSetTabBar

​AppBoxoWebAppTabBarItemClick

​Navigation bar

​AppBoxoWebAppSetNavigationBar

​Action buttons

​AppBoxoWebAppSetActionButton

​Loading indicator

​AppBoxoWebAppLoadingIndicator

​QR code reader

​AppBoxoWebAppOpenQRCodeReader

​Haptic feedback

​AppBoxoWebAppVibrate

​Action sheet

​AppBoxoWebAppShowActionSheet

​AppBoxoWebAppActionSheetItemClick

​Geolocation

​AppBoxoWebAppGetGeodata

​Map

​AppBoxoWebAppChooseLocation

​AppBoxoWebAppOpenLocation

​Alert

​AppBoxoWebAppShowAlert

​Image gallery

​AppBoxoWebAppShowImages

​Storage

​AppBoxoWebAppStorageGet

​AppBoxoWebAppStorageGetKeys

​AppBoxoWebAppStorageSet

​AppBoxoWebAppStorageRemove

​AppBoxoWebAppStorageClear

​Clipboard

​AppBoxoWebAppGetClipboard

​AppBoxoWebAppSetClipboard

​System information

​AppBoxoWebAppGetSystemInfo

​Accelerometer

​AppBoxoWebAppStartAccelerometer

​AppBoxoWebAppStopAccelerometer

​AppBoxoWebAppOnAccelerometerChange

​Gyroscope

​AppBoxoWebAppStartGyroscope

​AppBoxoWebAppStopGyroscope

​AppBoxoWebAppOnGyroscopeChange

​Compass

​AppBoxoWebAppStartCompass

​AppBoxoWebAppStopCompass

​AppBoxoWebAppOnCompassChange

​Background color

​AppBoxoWebAppSetBackgroundColor

​Status bar color

​AppBoxoWebAppSetStatusBarColor

​Tracking

​AppBoxoWebAppTrack

​Custom events

​AppBoxoWebAppCustomEvent

​Download file

​AppBoxoWebAppDownloadFile

​Share text and file

​AppBoxoWebAppShare

Miniapp initialization

`AppBoxoWebAppInit`

`AppBoxoWebAppGetInitData`

Miniapp manipulation

`AppBoxoWebAppOpenMiniApp`

`AppBoxoWebAppCloseMiniApp`

`AppBoxoWebAppOnRestore`

Authentication

`AppBoxoWebAppLogin`

`AppBoxoWebAppLogout`

`AppBoxoWebAppClearToken`

`AppBoxoWebAppSaveToken`

Appboxo Pay

`AppBoxoWebAppPay`

Tab bar

`AppBoxoWebAppSetTabBar`

`AppBoxoWebAppTabBarItemClick`

Navigation bar

`AppBoxoWebAppSetNavigationBar`

Action buttons

`AppBoxoWebAppSetActionButton`

Loading indicator

`AppBoxoWebAppLoadingIndicator`

QR code reader

`AppBoxoWebAppOpenQRCodeReader`

Haptic feedback

`AppBoxoWebAppVibrate`

Action sheet

`AppBoxoWebAppShowActionSheet`

`AppBoxoWebAppActionSheetItemClick`

Geolocation

`AppBoxoWebAppGetGeodata`

Map

`AppBoxoWebAppChooseLocation`

`AppBoxoWebAppOpenLocation`

Alert

`AppBoxoWebAppShowAlert`

Image gallery

`AppBoxoWebAppShowImages`

Storage

`AppBoxoWebAppStorageGet`

`AppBoxoWebAppStorageGetKeys`

`AppBoxoWebAppStorageSet`

`AppBoxoWebAppStorageRemove`

`AppBoxoWebAppStorageClear`

Clipboard

`AppBoxoWebAppGetClipboard`

`AppBoxoWebAppSetClipboard`

System information

`AppBoxoWebAppGetSystemInfo`

Accelerometer

`AppBoxoWebAppStartAccelerometer`

`AppBoxoWebAppStopAccelerometer`

`AppBoxoWebAppOnAccelerometerChange`

Gyroscope

`AppBoxoWebAppStartGyroscope`

`AppBoxoWebAppStopGyroscope`

`AppBoxoWebAppOnGyroscopeChange`

Compass

`AppBoxoWebAppStartCompass`

`AppBoxoWebAppStopCompass`

`AppBoxoWebAppOnCompassChange`

Background color

`AppBoxoWebAppSetBackgroundColor`

Status bar color

`AppBoxoWebAppSetStatusBarColor`

Tracking

`AppBoxoWebAppTrack`

Custom events

`AppBoxoWebAppCustomEvent`

Download file

`AppBoxoWebAppDownloadFile`

Share text and file

`AppBoxoWebAppShare`