> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rebellapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JS Bridge Guide

> Use hylid-bridge to call JSAPIs in Native Mini Programs launched via cross-app mechanisms.

`hylid-bridge` is an npm package for **Native Mini Programs** that are launched from a foreign native app container (cross-app launch). It provides a normalized `my.*` API layer that works consistently regardless of which host app is running the Mini Program.

<Info>
  This package is **only needed for cross-app launch scenarios** — when your Native Mini Program is opened from a different native app. Standard Mini Apps running inside the Rebell SuperApp do not require `hylid-bridge`: the `my` object is injected automatically by the SuperApp runtime.
</Info>

## When to Use hylid-bridge

| Scenario                                                | Use hylid-bridge?                             |
| ------------------------------------------------------- | --------------------------------------------- |
| Native Mini App in Rebell SuperApp                      | No — `my.*` available natively                |
| H5 Mini App in Rebell SuperApp                          | Via CDN `<script>` tag (not this npm package) |
| Native Mini App launched cross-app (from a partner app) | **Yes — install via npm**                     |

## Installation

```bash theme={null}
npm install hylid-bridge --save
```

## Usage

Import the specific APIs you need directly from the package:

```javascript theme={null}
import { alert, appEnv, getAppIdSync } from 'hylid-bridge'

Page({
  onLoad() {
    alert({ content: 'Hello from Mini Program!' })
  }
})
```

## Handling Platform Differences

When running cross-app, not all JSAPIs are available on every host platform. Use `appEnv` to detect the runtime and branch accordingly:

```javascript theme={null}
import { appEnv, getAppIdSync, alert } from 'hylid-bridge'

Page({
  onLoad() {
    if (appEnv.platform === 'alipay') {
      const { appId } = getAppIdSync();
      console.log('Running on Alipay, App ID:', appId);
    } else {
      alert({ content: 'Some features may not be available on this platform' });
    }
  }
})
```

## Supported APIs

<AccordionGroup>
  <Accordion title="Navigation">
    * `navigateTo` - Navigate to a new page
    * `navigateBack` - Navigate back
    * `redirectTo` - Redirect to a page
    * `reLaunch` - Relaunch the app
    * `switchTab` - Switch to a tab page
  </Accordion>

  <Accordion title="UI Elements">
    * `alert` - Show alert dialog
    * `confirm` - Show confirmation dialog
    * `showToast` - Show toast message
    * `showLoading` - Show loading indicator
    * `hideLoading` - Hide loading indicator
    * `showActionSheet` - Show action sheet
  </Accordion>

  <Accordion title="Storage">
    * `setStorage` - Store data
    * `getStorage` - Retrieve data
    * `removeStorage` - Remove data
    * `clearStorage` - Clear all data
  </Accordion>

  <Accordion title="Location">
    * `getLocation` - Get current location
    * `openLocation` - Open location in map
    * `chooseLocation` - Choose a location
  </Accordion>

  <Accordion title="Network">
    * `request` - Make HTTP requests
    * `uploadFile` - Upload files
    * `downloadFile` - Download files
  </Accordion>

  <Accordion title="System">
    * `getSystemInfo` - Get system information
    * `getNetworkType` - Get network type
    * `scan` - Scan QR codes
  </Accordion>

  <Accordion title="Payment">
    * `tradePay` - Process payments
    * `signContract` - Sign contracts
  </Accordion>
</AccordionGroup>

## Requirements

<Warning>
  Applications using the JS bridge in cross-app scenarios may need to:

  * Request specific permissions from host platforms
  * Whitelist domains for API calls
  * Handle cases where certain APIs are not available on the host platform
</Warning>

### Domain Whitelisting

```json theme={null}
{
  "networkTimeout": {
    "request": 30000,
    "downloadFile": 30000
  },
  "request": {
    "whitelist": [
      "https://api.yourdomain.com"
    ]
  }
}
```

## Error Handling

Always implement error handling — cross-app environments may not support every API:

```javascript theme={null}
import { request } from 'hylid-bridge'

async function fetchData() {
  try {
    const res = await request({
      url: 'https://api.example.com/data',
      method: 'GET'
    });
    return res.data;
  } catch (error) {
    console.error('Bridge API error:', error);
    if (error.code === 'NOT_SUPPORTED') {
      // API not available on this host platform
    }
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="JSAPI Overview" icon="book" href="/jsapi/overview">
    Learn about all available JSAPIs
  </Card>

  <Card title="JSAPI Reference" icon="list" href="/jsapi/reference">
    Complete API reference
  </Card>
</CardGroup>