capacitor-boxo-sdk

A Capacitor wrapper over Appboxo SDK for IOS and Android.

Install

``bash
npm install @appboxo/capacitor-boxo-sdk
npx cap sync
`

API

* setConfig(...)
* openMiniapp(...)
* setAuthCode(...)
* setAuthTokens(...)
* closeMiniapp(...)
* sendCustomEvent(...)
* sendPaymentEvent(...)
* getMiniapps()
* hideMiniapps()
* addListener('custom_event', ...)
* addListener('payment_event', ...)
* addListener('miniapp_lifecycle', ...)
* logout()
* Interfaces

$3

`typescript
setConfig(options: ConfigOptions) => Promise
`

Set global configs

| Param | Type |
| ------------- | ------------------------------------------------------- |
| options | ConfigOptions |

--------------------

$3

`typescript
openMiniapp(options: OpenMiniappOptions) => Promise
`

Open miniapp with options

| Param | Type |
| ------------- | ----------------------------------------------------------------- |
| options | OpenMiniappOptions |

--------------------

$3

`typescript
setAuthCode(options: { appId: string; authCode: string; }) => Promise
`

get AuthCode from hostapp backend and send it to miniapp

| Param | Type |
| ------------- | ------------------------------------------------- |
| options | { appId: string; authCode: string; } |

--------------------

$3

`typescript
setAuthTokens(options: { appId: string; tokens: { [key: string]: string; }; }) => Promise
`

get AuthTokens from hostapp backend and send it to miniapp

| Param | Type |
| ------------- | ------------------------------------------------------------------- |
| options | { appId: string; tokens: { [key: string]: string; }; } |

--------------------

$3

`typescript
closeMiniapp(options: { appId: string; }) => Promise
`

close miniapp by appId

| Param | Type |
| ------------- | ------------------------------- |
| options | { appId: string; } |

--------------------

$3

`typescript
sendCustomEvent(customEvent: CustomEvent) => Promise
`

send custom event to miniapp

| Param | Type |
| ----------------- | --------------------------------------------------- |
| customEvent | CustomEvent |

--------------------

$3

`typescript
sendPaymentEvent(paymentEvent: PaymentEvent) => Promise
`

send payment event to miniapp

| Param | Type |
| ------------------ | ----------------------------------------------------- |
| paymentEvent | PaymentEvent |

--------------------

$3

`typescript
getMiniapps() => Promise
`

Get list of miniapps

Returns: Promise<MiniappListResult>

--------------------

$3

`typescript
hideMiniapps() => Promise
`

Miniapp opens on a native screen. To show payment processing page need to hide miniapp screen.
To use this function need to enable 'enableMultitaskMode: true' in Boxo.setConfig()

--------------------

$3

`typescript
addListener(eventName: 'custom_event', listenerFunc: (customEvent: CustomEvent) => void) => Promise
`

When host app user logs out, it is highly important to clear all miniapp storage data.

| Param | Type |
| ------------------ | ----------------------------------------------------------------------------- |
| eventName | 'custom_event' |
| listenerFunc | (customEvent: CustomEvent) => void |

Returns: Promise<PluginListenerHandle>

--------------------

$3

`typescript
addListener(eventName: 'payment_event', listenerFunc: (paymentEvent: PaymentEvent) => void) => Promise
`

| Param | Type |
| ------------------ | -------------------------------------------------------------------------------- |
| eventName | 'payment_event' |
| listenerFunc | (paymentEvent: PaymentEvent) => void |

Returns: Promise<PluginListenerHandle>

--------------------

$3

`typescript
addListener(eventName: 'miniapp_lifecycle', listenerFunc: (lifecycle: LifecycleEvent) => void) => Promise
`

| Param | Type |
| ------------------ | --------------------------------------------------------------------------------- |
| eventName | 'miniapp_lifecycle' |
| listenerFunc | (lifecycle: LifecycleEvent) => void |

Returns: Promise<PluginListenerHandle>

--------------------

$3

`typescript
logout() => Promise
`

--------------------

$3


#### ConfigOptions

| Prop | Type | Description |
| ----------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------- |
| clientId | string | your client id from dashboard |
| userId | string | hostapp userId, will be used for the Consent Management |
| language | string | language value will be passed to the miniapp |
| sandboxMode | boolean | switch to sandbox mode |
| enableMultitaskMode | boolean | Each miniapp appears as a task in the Recents screen. !It works only on android devices. |
| theme | 'light' \| 'dark' \| 'system' | theme for splash screen and other native components used inside miniapp. |
| isDebug | boolean | enables webview debugging |
| showPermissionsPage | boolean | use it to hide "Settings" from Miniapp menu |
| showClearCache | boolean | use it to hide "Clear cache" from Miniapp menu |
| showAboutPage | boolean | use it to hide "About Page" from Miniapp menu |
| miniappSettingsExpirationTime | number | use it to change miniapp settings cache time in sec. By default is 60 sec |


#### OpenMiniappOptions

| Prop | Type | Description |
| -------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| appId | string | miniapp id |
| data | object | (optional) data as Map that is sent to miniapp |
| theme | 'light' \| 'dark' \| 'system' | (optional) miniapp theme "dark" \| "light" (by default is system theme) |
| extraUrlParams | object | (optional) extra query params to append to miniapp URL (like: http://miniapp-url.com/?param=test) |
| urlSuffix | string | (optional) suffix to append to miniapp URL (like: http://miniapp-url.com/?param=test) |
| colors | ColorOptions | (optional) provide colors to miniapp if miniapp supports |
| enableSplash | boolean | (optional) use to skip miniapp splash screen |
| saveState | boolean | (optional) use to save state on close miniapp |
| pageAnimation | 'BOTTOM_TO_TOP' \| 'TOP_TO_BOTTOM' \| 'LEFT_TO_RIGHT' \| 'RIGHT_TO_LEFT' \| 'FADE_IN' | (optional) use to change launch animation for miniapp. |


#### ColorOptions

| Prop | Type |
| -------------------- | ------------------- |
| primaryColor | string |
| secondaryColor | string |
| tertiaryColor | string |


#### CustomEvent

| Prop | Type |
| --------------- | ------------------- |
| appId | string |
| requestId | number |
| type | string |
| errorType | string |
| payload | object |


#### PaymentEvent

| Prop | Type |
| ---------------------- | ------------------- |
| appId | string |
| transactionToken | string |
| miniappOrderId | string |
| amount | number |
| currency | string |
| status | string |
| hostappOrderId | string |
| extraParams | object |


#### MiniappListResult

| Prop | Type |
| -------------- | -------------------------- |
| miniapps | [MiniappData] |
| error | string |


#### MiniappData

| Prop | Type |
| ----------------- | ------------------- |
| appId | string |
| name | string |
| category | string |
| description | string |
| logo | string |


#### PluginListenerHandle

| Prop | Type |
| ------------ | ----------------------------------------- |
| remove | () => Promise<void> |


#### LifecycleEvent

| Prop | Type | Description |
| --------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| appId | string | |
| lifecycle | string | 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 touch event is dispatched to the miniapp page. onAuth - Called when the miniapp starts login and user allows it |
| error` | string | |