JS bridge guide for cross-app launch

This document guides you through the steps to use JavaScript (JS) bridge when calling JSAPIs for mini programs in the cross-app launch scenario.

Overview

For mini programs that are launched to different native apps, they run on different containers. The JSAPIs that these mini programs can call may vary. To resolve this problem, we recommend that mini program developers use JavaScript (JS) bridge for mini programs to call the standard JSAPIs provided by Mini Program Platform.

JS bridge works as a bridge that builds a two-way channel for communication between JavaScript and native code. By using JS bridge, mini program developers can call JSAPIs for the mini programs launched to different native apps.

image

Note: JS bridge is optional for mini programs without cross-app launch needs.

Audience

This document is targeted at developers who call JSAPIs when debugging mini programs for cross-app launch.

Procedures

To use JS bridge, refer to the following steps:

Step 1: Install JS bridge

Run the following code in the root directory of the mini program project:

copy
npm install hylid-bridge --save

For more information about NPM, refer to NPM Package Management.

Step 2: Use JS bridge

Native mini programs

To use JS bridge in native mini programs, you need to import the hylid-bridge package on the mini program page. Then you can call the JSAPIs exported by the package. To learn more, check the sample code below.

Sample code

copy
import { alert } from 'hylid-bridge'

Page({
  onLoad() {
     alert({
        content: 'app onload'
     })
  }
})

HTML5 mini programs

To use JS bridge in HTML5 mini programs, refer to Mini Program JSAPIs in HTML5.

Note: To learn more about native mini programs and HTML5 mini programs, refer to Mini program types.

Step 3: Check native app (optional)

For some JSAPIs that are not supported by the native app where the mini program is released, JS bridge will throw an error. Check the error message and import appEnv from hylid-bridge to check which native app a mini program runs on. Then resolve the error accordingly. To learn more, check the sample code below.

Sample code

copy
import { appEnv, getAppIdSync } from 'hylid-bridge'

Page({
  onLoad() {
    const { appId } = appEnv.isLazada ? getAppIdSync() : { appId: 'taobao-appid' }
  }
})

Note: If you use the hylid-bridge package, we recommend that you use appEnv to check the native app before calling the unique JSAPIs of the native app via my[apiName] format.

For example, to call a unique JSAPI in Taobao, check the sample code below:

copy
import { appEnv } from 'hylid-bridge'

Page({
  onLoad() {
    if(appEnv.isTaobao) {
       my.tb.navigateToTaobaoPage()
    }
  }
})

API list

The following table lists the latest JSAPIs that are supported in JS bridge:

Interface Name

Description

Basic

getAppIdSync

Obtain the Mini Program App ID synchronously.

NavigationBar

hideBackHome

Hide back to home button.

hideNavigationBarLoading

Hide navigation bar loading.

setNavigationBar

Set the navigation bar text and style.

showNavigationBarLoading

Show navigation bar loading.

TabBar

hideTabBar

Hide the tabBar.

setTabBarStyle

Set the style of tabBar.

Route

switchTab

Jump to the specified tabBar page and close all other pages that are not tabBar.

navigateTo

Maintain the current page and jump to the specified page within the application. Use navigateBackto return to the original page.

reLaunch

Close all current pages and jump to the specified page within the application.

navigateBack

Close the current page and return to the previous one or more pages.

redirectTo

Close the current page and jump to the specified page within the application.

FeedBack

alert

Alert box.

confirm

Confirm box.

prompt

Prompt box.

showToast

Show a weak hint, which disappears in the specified seconds.

hideToast

Hide the weak hint.

showLoading

Show the loading hint.

hideLoading

Hide the loading hint.

showActionSheet

Display an operation menu.

Pulldown

onPullDownRefresh

On the Page, customize the onPullDownRefresh function to listen to the pull-to-refresh event of user.

stopPullDownRefresh

Stop the pull-to-refresh for the current page.

startPullDownRefresh

Start the pull-to-refresh function.

Animation

createAnimation

Create an instance of animation.

Keyboard

hideKeyboard

Hide keyboard.

Scroll

pageScrollTo

Scroll to the destination location of the page.

SetBackground

setBackgroundColor

Set background color.

Set Page Pulldown

setCanPullDown

Set whether the page can support pulldown.

Storage

setStorage

Store the data in the specified key in the local cache, which overlaps the original data corresponding to the key.

setStorageSync

Store synchronously the data in the specified key in the local cache.

getStorage

Get cached data.

getStorageSync

Get cached data synchronously.

removeStorage

Remove cached data.

removeStorageSync

Remove cached data synchronously.

clearStorage

Clear local data cache.

clearStorageSync

Clear local data cache synchronously.

Location

getLocation

Get the current geographical location of the user.

Network

request

Network request.

getNetworkType

Get the current network status.

System Information

getSystemInfo

Get system information.

Clipboard

getClipboard

Get the clipboard data.

setClipboard

Set the clipboard data.

Permission Guide

showAuthGuide

Guide users to grant the authorization when permission is needed.

Scan

scan

Call the scanning QR code function.

Memory Warning

onMemoryWarning

Listen to the insufficient memory alarm event.

offMemoryWarning

Unlisten to the insufficient memory alarm event.

WebView

createWebViewContext

By creating webViewContext, Mini Program can send message to web-view. This API will create a webViewContext instance.

Open Capabilities

getAuthCode

Get auth code.

getOpenUserInfo

Get basic information about the user.

tradePay

Start to pay.

Note: The API list will be constantly updated.

FAQs

How to apply for JSAPI calling permission?

Some native apps have restrictions on calling JSAPIs. You need to apply for permissions from the native app so that your mini program can call specific JSAPIs.

For example, if you launch the mini program to Taobao, you need to send requests to Taobao to call the JSAPIs provided by Taobao. Otherwise, the JSAPI calling might fail.

For mini programs that are launched to other native apps, refer to the native apps to get documentation.

How to whitelist domains?

When calling JSAPIs provided by the native apps, you may encounter domain name control. To resolve this problem, add certain domains to the whitelist.

For example, if you launch the mini program to Taobao, Taobao implements domain name control. See here to learn how to whitelist your domains on Taobao.

For mini programs that are launched to other native apps, refer to the native apps to get documentation.

How to set navigation bar on Lazada?

To enable the navigation bar of your mini program on Lazada, you need to set navigationBarForceEnable to true in the window field of the app.json file under the root directory of the mini program project.

More information

NPM Package Management

Mini program types

How to transform an HTML 5 mobile app to an HTML 5 mini program