Overview

Overview

The Super Qi framework provides developers with comprehensive JSAPI capabilities to build diversified and convenient services for users. JSAPIs are client-side JavaScript functions that Mini Programs call directly within the application to access device features, user data, and platform services.

JS Bridge Architecture

Mini Programs launched to different native apps run on different containers, which may support varying JSAPI implementations. To resolve this, Super Qi provides a JavaScript Bridge (JS Bridge) that standardizes JSAPI calls across different platforms.

How JS Bridge Works

JS Bridge acts as a two-way communication channel between JavaScript code in your Mini Program and native code in the host application. This allows:

• Unified API calls across different native apps
• Platform abstraction - developers write once, run everywhere
• Native feature access - camera, location, payments, etc.
• Consistent behavior regardless of the host application

SDK Integration

To use Mini Program JSAPIs, you need to integrate the JSBridge SDK.

Import the SDK

Add the following script tag to your Mini Program's HTML file:

<script src="https://cdn.marmot-cloud.com/npm/hylid-bridge/2.10.0/index.js"></script>

API Conventions

Super Qi JSAPIs follow consistent naming and usage patterns to make integration straightforward.

API Naming Patterns

JSAPIs use different prefixes based on their purpose:

Standard APIs

All other JSAPI interfaces accept an object as a parameter with the following common properties:

Additional API-specific properties vary depending on the functionality.

Callback Results

• Callback functions receive a result object as their parameter
• If the result contains error or errorMessage fields, the call failed
• Success callbacks receive API-specific data

Promise Support

All standard APIs return a Promise object, allowing you to use modern async/await syntax or promise chaining.

Callback Example:

my.httpRequest({
  url: '/api/data',
  success(res) {
    console.log('Success:', res.data);
  },
  fail(res) {
    console.log('Error:', res.error, res.errorMessage);
  },
  complete(res) {
    console.log('Request completed');
  }
});

Promise Example:

my.httpRequest({
  url: '/api/data',
  success(res1) {
    console.log('Callback result:', res1);
  }
}).then((res2) => {
  // res1 === res2
  console.log('Promise result:', res2.data);
}).catch((res) => {
  console.log('Error:', res.error, res.errorMessage);
});

Async/Await Example:

async function fetchData() {
  try {
    const res = await my.httpRequest({ url: '/api/data' });
    console.log('Data:', res.data);
  } catch (res) {
    console.log('Error:', res.error, res.errorMessage);
  }
}

API Interface Definition

Each JSAPI has a TypeScript-style interface definition that describes its parameters and callbacks.

Example - my.alert

The my.alert API displays a simple alert dialog. Here's how its interface is defined:

interface IAlertOptions {
  title?: string;          // Alert dialog title
  content?: string;        // Alert dialog content
  buttonText?: string;     // Button label text
  success?: () => void;    // Success callback
  fail?: () => void;       // Failure callback
  complete?: () => void;   // Completion callback
}

Usage:

my.alert({
  title: 'Payment Successful',
  content: 'Your order has been confirmed',
  buttonText: 'OK',
  success() {
    console.log('User closed the alert');
  }
});

Common Interface Pattern

Most JSAPIs follow this pattern:

interface IApiOptions {
  // API-specific required parameters
  requiredParam: string;

  // API-specific optional parameters
  optionalParam?: number;

  // Common callback functions
  success?: (res: SuccessResult) => void;
  fail?: (res: ErrorResult) => void;
  complete?: (res: Result) => void;
}

Properties marked with ? are optional.

Related Documentation

• my.getAuthCode - Authorization API
• my.tradePay - Payment API