ejsc-mna-api

v1.0.3

Published

11 days ago

Native Hardware Bridge API for 365 Mini App environment. Facilitates real-time, asynchronous communication with system-level APIs including Media, UI, and Location services.

0High
0Medium
0Low

tranvansi6302

ejsc-mna-api 🚀

The Official Universal Native Hardware & Bridge API Suite for 365 Mini App Communication.

ejsc-mna-api là thư viện cầu nối phần cứng (Native Bridge API) chính thức dành cho hệ sinh thái 365 Mini App. Thư viện cho phép các ứng dụng Web Mini App tương tác trực tiếp với tầng phần cứng và dịch vụ hệ thống của ứng dụng Host/Super App (như Camera, GPS, Biometrics, Payment, Local & KeyChain Storage, System UI, WebSocket, iBeacon).

Thư viện cung cấp đầy đủ TypeScript Types, kiểm soát an toàn kiểu dữ liệu và hỗ trợ đồng thời cả hai mô hình lập trình:

apisAsync: Bọc toàn bộ Native APIs dưới dạng Promise (async/await) hiện đại.
apisSync: Truy cập trực tiếp qua JS Proxy Callbacks (success, fail, complete).

📑 Mục Lục

1. Tính Năng Nổi Bật

⚡ Zero-Dependency Core: Thư viện siêu nhẹ, không phụ thuộc vào gói mã nguồn bên ngoài.
🔒 Type-Safe Autocomplete: Định nghĩa TypeScript chặt chẽ cho 100% các API và tham số trả về.
📱 Cross-Platform Bridge: Tương thích hoàn toàn trên cả Android WebView và iOS WKWebView.
🔑 Secure KeyChain Storage: Hỗ trợ lưu trữ thông tin nhạy cảm qua iOS KeyChain & Android KeyStore.
👆 Biometric Enclave Integration: Tạo khóa và xác thực chữ ký số bằng sinh trắc học trực tiếp trên Secure Enclave.
🛡️ CORS Bypass HTTP: Thực hiện API HTTP requests thông qua Native Thread giúp bỏ qua rào cản CORS trên Web.

2. Yêu Cầu Hệ Thống & Cài Đặt

Yêu cầu:

Node.js: Phiên bản >= 22.0.0
TypeScript: Phiên bản >= 5.0.0

Cài đặt:

# Sử dụng pnpm (khuyên dùng)
pnpm add [email protected]

# Sử dụng npm
npm install [email protected]

# Sử dụng yarn
yarn add [email protected]

3. Hướng Dẫn Sử Dụng Nhanh

3.1 Mô hình Async / Promise (Khuyên Dùng)

Sử dụng apisAsync để áp dụng cú pháp async/await sạch sẽ và dễ xử lý lỗi:

import { apisAsync } from 'ejsc-mna-api';

async function handleGetLocation() {
  try {
    const info = await apisAsync.getSystemInfo();
    console.log('Hệ điều hành:', info.platform, info.system);

    const location = await apisAsync.getLocation();
    console.log('Tọa độ hiện tại:', location.latitude, location.longitude);
  } catch (error) {
    console.error('Lỗi khi lấy dữ liệu Native:', error);
  }
}

3.2 Mô hình Callback (Proxy `window.ejsc`)

Sử dụng apisSync đối với các dự án ưu tiên mô hình callback truyền thống:

import { apisSync } from 'ejsc-mna-api';

apisSync.getLocation({
  success: (res) => {
    console.log('Tọa độ:', res.latitude, res.longitude);
  },
  fail: (err) => {
    console.error('Lỗi lấy tọa độ:', err);
  },
  complete: () => {
    console.log('Hoàn thành tiến trình getLocation');
  }
});

4. Danh Sách API Chi Tiết

4.1 System & Thiết Bị (Device APIs)

| API Method | Mô Tả | Tham Số chính | | :--- | :--- | :--- | | getSystemInfo() | Đọc toàn bộ thông số phần cứng, màn hình và pin | { keys?: string[] } | | getAppLanguage() | Lấy ngôn ngữ hiển thị hiện tại | N/A | | setAppLanguage() | Thiết lập ngôn ngữ hiển thị hệ thống (vi | en) | { language: string } | | getClipboard() | Đọc văn bản từ khay nhớ tạm | N/A | | setClipboard() | Ghi văn bản vào khay nhớ tạm | { data: string } | | triggerHapticFeedback() | Tạo phản hồi rung vật lý | { style: 'light' \| 'medium' \| 'heavy' \| 'success' \| 'error' } | | authorize() | Yêu cầu cấp quyền truy cập tính năng hệ thống | { scope: string } | | getSetting() / openSetting() | Đọc và mở trang quản lý quyền Mini App | N/A |

4.2 Xác Thực & Người Dùng (Auth APIs)

| API Method | Mô Tả | Kết Quả Trả Về | | :--- | :--- | :--- | | getAuthCode() | Lấy mã xác thực OAuth Code từ Super App | { authCode: string } | | getUserInfo() | Đọc thông tin Profile người dùng (tên, avatar, email) | { name: string, avatar: string, ... } | | logout() | Đăng xuất tài khoản khỏi hệ thống Super App | { success: boolean } |

4.3 Giao Diện & Thông Báo (UI APIs)

// Hiển thị Toast
await apisAsync.showToast({
  type: 'success',
  content: 'Thao tác thành công!',
  duration: 2000
});

// Hiển thị Confirm Modal
const res = await apisAsync.confirm({
  title: 'Xác Nhận',
  content: 'Bạn có chắc chắn muốn xóa không?',
  confirmButtonText: 'Đồng ý',
  cancelButtonText: 'Hủy'
});

4.4 Media & Quét Mã (Media & Scan APIs)

// Quét mã QR / Barcode
const scanResult = await apisAsync.scan();
console.log('Nội dung mã QR:', scanResult.result);

// Chọn ảnh từ thư viện hoặc chụp camera
const media = await apisAsync.chooseImage({ count: 3 });
console.log('Các đường dẫn ảnh tạm:', media.tempFilePaths);

4.5 Định Vị GPS & Bản Đồ (Location APIs)

4.6 Bộ Nhớ Storage & KeyChain Bảo Mật

4.7 Mạng & Tiện Ích (Network & System APIs)

// Gửi HTTP Request qua Native (Bypass CORS)
const response = await apisAsync.request({
  url: 'https://api.example.com/v1/orders',
  method: 'POST',
  data: { orderId: '12345' },
  headers: { 'Content-Type': 'application/json' }
});

// Thoát Mini App về ứng dụng Host
await apisAsync.exitMiniApp();

4.8 Sinh Trắc Học (FaceID / TouchID / Biometrics)

Tích hợp xác thực sinh trắc học cao cấp thông qua apisAsync.bioMetrics:

// Kiểm tra phần cứng có hỗ trợ FaceID / TouchID không
const check = await apisAsync.bioMetrics.isSupported();

if (check.isSupported) {
  // Xác thực dấu vân tay / khuôn mặt
  const auth = await apisAsync.bioMetrics.localAuth({
    reason: 'Xác thực để phê duyệt giao dịch'
  });
  
  if (auth.success) {
    console.log('Xác thực sinh trắc học thành công!');
  }
}