MiniApp SDK Documentation

Overview

The MiniApp SDK is a JavaScript library designed to facilitate communication between a web-based MiniApp and its host application (specifically tailored for Flutter In-App WebView environments). It provides a unified interface for accessing native device capabilities, managing user authentication, handling payments, and controlling UI navigation.

Developed by Dexel Tech teams.

Installation & Initialization

To use the SDK, include the script in your MiniApp project. Before calling any API methods, you must initialize the SDK with a manifest configuration.

Initialization

Call MiniApp.init(manifest) to start the session. This sets up the App ID, declares permissions, and establishes the instance ID with the host.

const manifest = {
  appId: "your-app-id",
  permissions: [
    "auth.profile",
    "auth.token",
    "storage.kv",
    "device.location"
  ]
};

MiniApp.init(manifest)
  .then(result => {
    console.log("SDK Initialized", result);
    // result contains instanceId and capabilities
  })
  .catch(err => {
    console.error("Initialization failed", err);
  });

Permissions

The SDK enforces a permission model. Certain APIs require specific permissions to be declared in the manifest during initialization.

• Declared Permissions: Passed in manifest.permissions during init().
• Runtime Checks: Methods internally call MiniApp.hasPermission(permission). If a permission was not declared, an ERR_PERMISSION_REQUIRED error is thrown.
• Requesting Permissions: You can request additional scopes at runtime using the Permissions API.

Permissions API

| Method | Description | | :--- | :--- | | MiniApp.permissions.query(scope) | Query the status of a specific permission scope. | | MiniApp.permissions.request(scopes) | Request a list of permission scopes from the user/host. |

API Reference

1. Authentication (MiniApp.auth)

Handles user login, profile retrieval, and session management.

| Method | Parameters | Description | | :--- | :--- | :--- | | login() | None | Requests auth.profile and auth.token. Returns user info and access token. | | getProfile() | None | Retrieves the user's profile information. Requires auth.profile. | | getToken(options) | options (Object) | Retrieves the access token. Requires auth.token. | | logout() | None | Logs out the user. Requires auth.logout. |

Example:

MiniApp.auth.login()
  .then(({ id, name, token }) => {
    console.log(`Welcome ${name}`);
  });

2. Storage (MiniApp.storage)

Key-Value storage interface backed by the host application. Values are automatically stringified if they are objects.

| Method | Parameters | Description | | :--- | :--- | :--- | | setItem(key, value) | key (String), value (Any) | Stores a value. Requires storage.kv. | | getItem(key) | key (String) | Retrieves a value. Requires storage.kv. | | removeItem(key) | key (String) | Removes a specific key. Requires storage.kv. | | clear() | None | Clears all storage. Requires storage.kv. | | getQuota() | None | Returns storage quota information. Requires storage.kv. |

3. User Interface (MiniApp.ui)

Display native UI elements like modals, loaders, and toasts.

| Method | Parameters | Description | | :--- | :--- | :--- | | showModal(options) | title, content/message | Shortcut for displaying a modal. | | modal(options) | title, message, etc. | Displays a native modal dialog. | | loading.show(options) | None | Shows a loading indicator. | | loading.hide() | None | Hides the loading indicator. | | toast(options) | message, duration, etc. | Displays a temporary toast notification. |

4. Navigation (MiniApp.navigation)

Control the MiniApp's navigation stack within the host.

| Method | Parameters | Description | | :--- | :--- | :--- | | open(options) | url, params | Opens a new page or MiniApp. | | back(options) | None | Navigates back in the history stack. | | setTitle(title) | title (String) | Updates the header title of the current view. |

5. Payments (MiniApp.payments & MiniApp.pay)

Process payments through the host's payment gateway.

| Method | Parameters | Description | | :--- | :--- | :--- | | pay(options) | amount, currency, description | High-level wrapper. Converts amount to minor units (cents). | | payments.requestPayment(req) | idempotencyKey, amountMinor, currency | Low-level payment request. Requires payments.request. |

Example:

MiniApp.pay({
  amount: 10.00, // Will be converted to 1000 minor units
  currency: "USD",
  description: "Order #123"
});

6. Device Capabilities (MiniApp.device)

Access native hardware features. All methods require specific permissions declared in the manifest.

Clipboard

• clipboard.writeText(text): Requires device.clipboard.
• clipboard.readText(): Requires device.clipboard.

Location

• location.getCurrentPosition(options): Requires device.location.
• location.watchPosition(options): Requires device.location.
• location.clearWatch(watchId): Requires device.location.

Scanner & File

• scanner.scan(options): Opens QR/Barcode scanner. Requires device.scanner.
• file.pick(options): Opens file picker. Requires device.file.

Camera

• camera.open(options): Captures image/video. Maps to device.camera.capture.

7. Messaging (MiniApp.notify)

Send notifications or messages to the host system.

MiniApp.notify({
  title: "Alert",
  body: "Something happened"
});

Lifecycle Management

The SDK supports listening to the MiniApp's lifecycle events triggered by the host application.

| Event | Handler Method | Description | | :--- | :--- | :--- | | launch | MiniApp.onLaunch(callback) | Called when the MiniApp is first started. | | show | MiniApp.onShow(callback) | Called when the MiniApp comes to the foreground. | | hide | MiniApp.onHide(callback) | Called when the MiniApp goes to the background. | | close | MiniApp.onClose(callback) | Called when the MiniApp is about to be closed. |

Example:

MiniApp.onShow(() => {
  console.log("MiniApp is visible");
  // Refresh data here
});

Event System

You can define and trigger custom events within the SDK context.

| Method | Description | | :--- | :--- | | MiniApp.on(name, callback) | Register a listener for a custom event. | | MiniApp.emit(name, data) | Trigger a custom event with data. |

Example:

MiniApp.on("user-updated", (data) => {
  console.log("User data changed", data);
});

// Elsewhere
MiniApp.emit("user-updated", { id: 123 });

Error Handling

Methods may reject Promises or throw errors based on permission states or bridge availability.

Common Error Codes

| Code | Message | Description | | :--- | :--- | :--- | | ERR_PERMISSION_REQUIRED | Permission required: {scope} | The method was called without the permission declared in the manifest. | | ERR_PERMISSION_DENIED | Permission denied | The user or host denied the requested permission scope. | | Bridge not available | Error: Flutter Bridge missing | The host environment (Flutter WebView) is not ready or connected. |

Handling Bridge Availability

The SDK automatically waits for the flutter_inappwebview bridge to become ready. If the bridge is missing after multiple attempts, requests will reject with an error.

Environment Requirements

• Host: Flutter Application using flutter_inappwebview.
• Bridge: Expects window.flutter_inappwebview.callHandler to be available.
• Crypto: Uses crypto.randomUUID() if available, otherwise falls back to Date.now() for request IDs.

Version

• SDK Version: 1.0.0 (Defined in MiniApp.meta.sdkVersion)