@vite/bridge
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    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

    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.

    # use npm
    npm install @vite/bridge --save
    
    # use yarn
    yarn add @vite/bridge

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

    <script src="/path/to/bridge.js"></script>

    Usage

    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:

    <script>
        const bridge = new ViteBridge();
    </script>

    Constructor options

    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.

    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.

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

    Static properties

    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

    Instance Methods

    There are some methods on Bridge instance. Each method return a promise, so you can invoke like:

    bridge[methodName](params).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.

    bridge['app.setWebTitle']({
        "title": "Vite Cool"
    }).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

    import * as utils from "@vite/vitejs-utils";
    import * as abi from "@vite/vitejs-abi";
    
    // regular transfer
    const sendTx = await bridge["wallet.sendTxByURI"]({
        address: currentWalletAddress,
        uri: utils.uriStringify({
            target_address: receiverAddress,    // receiver address
            params: {
                tti: 'tti_5649544520544f4b454e6e40',    // tokenId, usually is VITE
                amount: amount, // in VITE unit
            }
        })
    })
    
    // call contract method
    const hexFunctionCall = abi.encodeFunctionCall(contractMethodABI, contractMethodParams);
    const base64FunctionCall = utils._Buffer.from(hexFunctionCall, 'hex').toString('base64');
    const sendTx = await bridge["wallet.sendTxByURI"]({
        address: currentWalletAddress,
        uri: utils.uriStringify({
            target_address: contractAddress,    // contract address
            function_name: contractMethodName,  // contract method name
            params: {
                tti: 'tti_5649544520544f4b454e6e40',    // tokenId
                amount: amount, // in VITE unit
                data: base64FunctionCall,
            }
        })
    })

    Call a method

    bridge.call('app.setWebTitle', {
        "title": "Vite Cool"
    })

    subscribe events

    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

    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:

    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

    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

    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

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

    Error

    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

    Keywords

    none

    Install

    npm i @vite/bridge

    DownloadsWeekly Downloads

    31

    Version

    2.0.0

    License

    ISC

    Unpacked Size

    35.9 kB

    Total Files

    9

    Last publish

    Collaborators

    • charles_liu
    • allenliuxt