Vite Javascript Bridge

A javascript bridge between native & web, can be used in web page in Vite App.

v2.0.x require Vite App version 3.2.0 and above.

Quick start

``js
import Bridge from '@vite/bridge'

const bridge = new Bridge()

bridge['wallet.currentAddress']().then(address => {
console.log(current address is ${address})
})
`




Installation

With bundler, like: webpack, rollup.
`sh


use npm

npm install @vite/bridge --save

use yarn

yarn add @vite/bridge
`

Or you can include dist/bridge.js in HTML.
`html

`

Usage


`js
import Bridge from '@vite/bridge'

const bridge = new Bridge()

bridge['bridge.version']().then(data => {
console.log(data)
})
`

If you include bridge.js in your HTML, Usage refer following code:
`html

`

$3

Bridge constructor can receive options, which is very different between version 2.0.x and version 1.x

#### 2.0.x

You can pass in a function, will be invoked after bridge inited.
`js
const bridge = new Bridge(bridge => {
// will be invoked after bridge inited
})
`

#### 1.x

You can pass in an options object.

- options.readyCallback

A function will be invoked after bridge inited

- options.selfDefinedMethods

A string array, each string is a method name which has been supported by Vite App, but not in ViteBridge internal methods list. So you can extend ViteBridge these methods.

Mostly you don't need this property.

`js
const bridge = new Bridge({
readyCallback: bridge => {},
selfDefinedMethods: [
// strings
]
})
`




$3

You can use static properties like Bridge.enabled

| Name | Type | Description | Comment |
| --- | --- | --- | --- |
| enabled | boolean | is in vite app | added in version 2.0.0 |
| _support | Boolean | is supported | deprecated in version 2.0.0 |
| _inIosContainer | Boolean | is in iOS system ｜ deprecated in version 2.0.0 |
| _inAndroidContainer | Boolean | is in Android system ｜ deprecated in version 2.0.0 |




$3

There are some methods on Bridge instance. Each method return a promise, so you can invoke like:
`js
bridgemethodName.then(res => {
console.log(get result from native Vite App: ${JSON.stringify(res)})
}, err => {
console.error(failed to invoke ${methodName}: ${JSON.stringify(err)})
})
`

Available Methods list in following table.

Input param is passed in method, and Output param is return from native Vite App.

| Method name | Input param | Output param | Description | Comment |
| -- | -- | -- | -- | -- |
| bridge.version | void | types.BridgeVersion | get js bridge version | output like: `{ "versionName": "1.1.0", "versionCode": 2}` |
| app.info | void | types.AppInfo | get Vite App version | output like: `{"platform":"ios", "versionName":"1.0.0", "versionCode":1024}` platform is ios or android |
| app.language | void | "zh" or "en" | get Operation System language | |
| app.setWebTitle | types.SetWebTitleInput | void | set webview title | input like: `{ "title": "Vite Cool" }` |
| app.share | types.ShareLinkInput | void | share a link | input like: `{ url: "https://vite.org" }` |
| app.setRRButton | types.SetRRButtonInput | void | show an icon (size: 56px * 56px, base64 Data URL) or customized text, no more than 4 chars, in right nav button | input like `{"img": "data:image/png;base64, xxxx"}` or `{"text": "Vite"}` |
| wallet.currentAddress | void | string | get current used vite address | |
| wallet.sendTxByURI | types.SendTxInput | types.SendTxOutput | send a tx | see following example |
| app.scan | void | types.ScanOutput | scan a QR code by camera | new in version 2.0.0
output like: `{"text": "Vite Cool"}` |
| call | string, ...any | any | invoke a native method | new in version 2.0.0 |

Use call if bridge missing some native method. for example: Vite App add new methods, but bridge haven't update, call is helpful.

#### example

Set webview title.
`js
bridge}" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">'app.setWebTitle'.then(() => {
console.log(success)
}, ({ code, msg, data }) => {
console.error(failed to set webview title: [${code}] ${msg}, native response: ${data})
})
`
Error detail will be described in following section, just ignore for now.


Send a transaction by Vite Bridge.

The uri should be a Vite URI, can be generated by @vite/vitejs
`js
import * as utils from "@vite/vitejs-utils";
import * as abi from "@vite/vitejs-abi";

// regular transfer
const sendTx = await bridge"wallet.sendTxByURI"
})

// call contract method
const hexFunctionCall = abi.encodeFunctionCall(contractMethodABI, contractMethodParams);
const base64FunctionCall = utils._Buffer.from(hexFunctionCall, 'hex').toString('base64');
const sendTx = await bridge"wallet.sendTxByURI"
})
`

Call a method
`js
bridge.call('app.setWebTitle', {
"title": "Vite Cool"
})
`

$3

Vite Bridge can subscribe following events trigged by user.

| Event name | Description |
| -- | -- |
| nav.RRBtnClick | the right button in navbar been clicked |
| page.onShow | page is show in the screen, or Vite App is switch to the frontground |
| shakeGesture | phone shaked |


#### subscribe

Subscribe an event
`js
bridge.subscribe(event_name, event_handler, once)
`
When the event trigged, the event handlers will be invoked in the order of subscribe.

The third param once is optional, default is false. If true, the event_handler will be invoked only once.

Example:
`js
bridge.subscribe('nav.RRBtnClick', () => {
console.log(navbar right button clicked)
})

bridge.subscribe('page.onShow', () => {
console.log(resume animation)
})

// you can subscribe an event multiple times, but not recommended.
bridge.subscribe('page.onShow', () => {
console.log(Welcome back)
})
`

#### unsubscribe

Unsubscribe an event
`js
bridge.unsubscribe(event_name, event_handler)
`

The second param event_handler is optional, if omited, bridge will unsubscribe all event_handlers on the specific event.

caveat: the event_handler should equal with the one passed in subscribe

Example
`js
const fn = () => {
console.log(Welcome back)
}

bridge.subscribe('page.onShow', fn)

bridge.unsubscribe('page.onShow', fn)

// unsubscribe all event_handler on event page.onShow
bridge.unsubscribe('page.onShow')
`

Anonymous event_handler can't be unsubscribed
`js
bridge.subscribe('page.onShow', () => {
console.log(resume animation)
})

// unsubscribe failed, because this anonymous event_handler is not the former one passed in subscribe
bridge.unsubscribe('page.onShow', () => {
console.log(resume animation)
})
`

$3

#### common error code
| Code | Description |
| --- | --- |
| 1 | unknown error |
| 2 | invalidate params |
| 3 | network error |
| 4 | login error |
| 5 | address in params not identical to current address |

#### wallet.sendTxByURI

wallet.sendTxByURI` could throw following codes.

| Code | Description | Comment |
| --- | --- | --- |
| 4001 | duplicate transaction before last transaction finished | only can send next transaction after the previous one be handled |
| 4002 | cannot find related tokenId | |
| 4003 | amount format error (should be translate to min unit) | |
| 4004 | user suspend | |