@laoone/miniapp-sdk
v0.0.6
Published
Miniapp SDK
Readme
@laoone/miniapp-sdk
LaoOne Miniapp SDK plugin cung cấp các API native cho miniapp chạy bên trong Super App.
Install
npm install @laoone/miniapp-sdkKhai báo & Sử dụng
import { LaoOneSDK } from '@laoone/miniapp-sdk';
// Ví dụ: Lấy Access token
try {
const res = await LaoOneSDK.getAccessToken();
console.log("Access Token Result: ", res);
} catch (e) {
console.log("Access Token Error: ", e.message);
}
// Ví dụ: Lấy thông tin thiết bị
try {
const info = await LaoOneSDK.getSystemInfo();
console.log(info.model, info.osName);
} catch (err) {
console.error("Failed to get system info:", err);
}
// Ví dụ: Lấy thông tin người dùng
try {
const user = await LaoOneSDK.getUserInfo();
console.log(user.name, user.phone);
} catch (err) {
console.error("Failed to get user info:", err);
}
// Ví dụ: Quét mã QR
try {
const qr = await LaoOneSDK.scanQr();
console.log(qr.content);
} catch (err) {
console.error("Failed to scan QR:", err);
}API
echo(...)getSystemInfo()getUserInfo()getAppInfo()getCurrentLocation()openWebview(...)openMiniapp(...)getNetworkInfo()getAccessToken()scanQr()getPhoto(...)pickImages(...)getBatteryInfo()vibrate(...)setNavigationBarColor(...)setStatusBarColor(...)closeApp()getContacts()saveImageToGallery(...)configAppView(...)requestCameraPermission()isBiometricAvailable()verifyIdentity(...)getCredentials(...)setCredentials(...)deleteCredentials(...)getPermissions()requestPermissions(...)getDeviceLanguage()isPedometerAvailable()getStepsCountTodayOnce()getStepsCountTodayUpdate()stopStepsCountUpdates()showToast(...)showMiniappMenu()pickVideo()saveVideoToGallery(...)saveFile(...)pickFile()getSuperAppSettings()copyToClipboard(...)setData(...)getData(...)removeData(...)setSecretData(...)getSecretData(...)removeSecretData(...)getCustomDataFromSuperApp()- Interfaces
- Type Aliases
echo(...)
echo(options: { value: string; }) => Promise<{ value: string; }>Echo a string value
| Param | Type |
| ------------- | ------------------------------- |
| options | { value: string; } |
Returns: Promise<{ value: string; }>
getSystemInfo()
getSystemInfo() => Promise<{ model: string; osName: string; osVersion: string; platform: string; manufacturer?: string; }>Get system information
Returns: Promise<{ model: string; osName: string; osVersion: string; platform: string; manufacturer?: string; }>
getUserInfo()
getUserInfo() => Promise<{ userId: string; userName: string; phoneNumber?: string; email?: string; avatar?: string; }>Get user information
Returns: Promise<{ userId: string; userName: string; phoneNumber?: string; email?: string; avatar?: string; }>
getAppInfo()
getAppInfo() => Promise<{ id: string; name: string; description?: string; owner?: string; version?: string; iconUrl?: string; isFavorite?: boolean; publishDate?: string; }>Get app information
Returns: Promise<{ id: string; name: string; description?: string; owner?: string; version?: string; iconUrl?: string; isFavorite?: boolean; publishDate?: string; }>
getCurrentLocation()
getCurrentLocation() => Promise<{ latitude: number; longitude: number; }>Get current location
Returns: Promise<{ latitude: number; longitude: number; }>
openWebview(...)
openWebview(options: { url: string; }) => Promise<void>Open a webview with the given URL
| Param | Type |
| ------------- | ----------------------------- |
| options | { url: string; } |
openMiniapp(...)
openMiniapp(options: { url: string; }) => Promise<void>Open a miniapp with the given URL
| Param | Type |
| ------------- | ----------------------------- |
| options | { url: string; } |
getNetworkInfo()
getNetworkInfo() => Promise<{ conneted: boolean; type: string; }>Get network information
Returns: Promise<{ conneted: boolean; type: string; }>
getAccessToken()
getAccessToken() => Promise<{ clientId: string; accessToken: string; }>Get access token
Returns: Promise<{ clientId: string; accessToken: string; }>
scanQr()
scanQr() => Promise<{ content: string; }>Scan a QR code
Returns: Promise<{ content: string; }>
getPhoto(...)
getPhoto(options: CameraOptions) => Promise<Photo>Get a photo from the camera or photo library
| Param | Type |
| ------------- | ------------------------------------------------------- |
| options | CameraOptions |
Returns: Promise<Photo>
pickImages(...)
pickImages(options: GalleryPhotosOptions) => Promise<Photo[]>Pick an image from the camera or photo library
| Param | Type |
| ------------- | --------------------------------------------------------------------- |
| options | GalleryPhotosOptions |
Returns: Promise<Photo[]>
getBatteryInfo()
getBatteryInfo() => Promise<{ level: number; charging: boolean; }>Get battery information
Returns: Promise<{ level: number; charging: boolean; }>
vibrate(...)
vibrate(options: { duration: number; }) => Promise<void>Vibrate the device
| Param | Type |
| ------------- | ---------------------------------- |
| options | { duration: number; } |
setNavigationBarColor(...)
setNavigationBarColor(options: { color: string; }) => Promise<void>Set the navigation bar color
| Param | Type |
| ------------- | ------------------------------- |
| options | { color: string; } |
setStatusBarColor(...)
setStatusBarColor(options: { color: string; }) => Promise<void>Set the status bar color
| Param | Type |
| ------------- | ------------------------------- |
| options | { color: string; } |
closeApp()
closeApp() => Promise<void>Close the app
getContacts()
getContacts() => Promise<{ contacts: { name: string; phone?: string; }[]; }>Get the user's contacts
Returns: Promise<{ contacts: { name: string; phone?: string; }[]; }>
saveImageToGallery(...)
saveImageToGallery(options: { imageBase64Data?: string; imageUrl?: string; }) => Promise<void>Save an image to the gallery
| Param | Type |
| ------------- | ------------------------------------------------------------- |
| options | { imageBase64Data?: string; imageUrl?: string; } |
configAppView(...)
configAppView(options: ConfigAppViewOptions) => Promise<void>Configure the app view
| Param | Type |
| ------------- | --------------------------------------------------------------------- |
| options | ConfigAppViewOptions |
requestCameraPermission()
requestCameraPermission() => Promise<{ granted: boolean; }>Returns: Promise<{ granted: boolean; }>
isBiometricAvailable()
isBiometricAvailable() => Promise<{ isAvailable: boolean; biometryType: number; }>Check if biometric auth is available
Returns: Promise<{ isAvailable: boolean; biometryType: number; }>
verifyIdentity(...)
verifyIdentity(options: { useFallback?: boolean; fallbackTitle?: string; }) => Promise<void>| Param | Type |
| ------------- | --------------------------------------------------------------- |
| options | { useFallback?: boolean; fallbackTitle?: string; } |
getCredentials(...)
getCredentials(options: { server: string; }) => Promise<{ username?: string; password?: string; }>| Param | Type |
| ------------- | -------------------------------- |
| options | { server: string; } |
Returns: Promise<{ username?: string; password?: string; }>
setCredentials(...)
setCredentials(options: { server: string; username: string; password: string; }) => Promise<void>| Param | Type |
| ------------- | -------------------------------------------------------------------- |
| options | { server: string; username: string; password: string; } |
deleteCredentials(...)
deleteCredentials(options: { server: string; }) => Promise<void>| Param | Type |
| ------------- | -------------------------------- |
| options | { server: string; } |
getPermissions()
getPermissions() => Promise<{ permissions: Record<string, boolean>; }>Returns: Promise<{ permissions: Record<string, boolean>; }>
requestPermissions(...)
requestPermissions(options: { permissions: string[]; }) => Promise<{ permissions: Record<string, boolean>; }>| Param | Type |
| ------------- | --------------------------------------- |
| options | { permissions: string[]; } |
Returns: Promise<{ permissions: Record<string, boolean>; }>
getDeviceLanguage()
getDeviceLanguage() => Promise<{ language: string; country: string; displayName: string; }>Returns: Promise<{ language: string; country: string; displayName: string; }>
isPedometerAvailable()
isPedometerAvailable() => Promise<{ isPedometerAvailable: boolean; }>Checks if the step counting sensor is available on the device. Returns: { isPedometerAvailable: boolean }
Returns: Promise<{ isPedometerAvailable: boolean; }>
getStepsCountTodayOnce()
getStepsCountTodayOnce() => Promise<{ steps: number; }>Retrieves the total number of steps taken today (since 00:00:00). Used for a one-time fetch, it does not start real-time tracking updates. Returns: { steps: number }
Returns: Promise<{ steps: number; }>
getStepsCountTodayUpdate()
getStepsCountTodayUpdate() => Promise<{ initialSteps: number; }>Starts tracking steps in real-time. Returns the initial number of steps taken since the beginning of the day ({ initialSteps: number }). After calling this method, the SDK will periodically emit the 'measurement' event. Event Payload: { newSteps: steps taken since the tracking started, totalToday: total steps since the beginning of the day }. Usage: LaoOneSDK.addListener('measurement', (data) => { ... })
Returns: Promise<{ initialSteps: number; }>
stopStepsCountUpdates()
stopStepsCountUpdates() => Promise<void>Stops step tracking and halts the 'measurement' events.
showToast(...)
showToast(options: { message: string; duration?: 'short' | 'long'; backgroundColor?: string; textColor?: string; action?: { text: string; textColor?: string; }; }) => Promise<{ actionClicked: boolean; }>Hiển thị một thông báo Snackbar trên màn hình.
| Param | Type |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| options | { message: string; duration?: 'short' | 'long'; backgroundColor?: string; textColor?: string; action?: { text: string; textColor?: string; }; } |
Returns: Promise<{ actionClicked: boolean; }>
showMiniappMenu()
showMiniappMenu() => Promise<void>Hiển thị menu hành động (Action Menu bottom sheet) của Miniapp. Cho phép Miniapp tự kích hoạt hiển thị trình đơn của mình bằng code JavaScript.
pickVideo()
pickVideo() => Promise<{ path: string; webPath: string; size: number; duration: number; }>Mở thư viện thiết bị để người dùng chọn một video.
Returns: Promise<{ path: string; webPath: string; size: number; duration: number; }>
saveVideoToGallery(...)
saveVideoToGallery(options: { videoUrl?: string; base64Data?: string; }) => Promise<void>Lưu một đoạn video vào thư viện thiết bị (Photos/Gallery). Hỗ trợ lưu từ URL mạng (http/https - tự động tải về trước khi lưu), URL máy cục bộ (file://) hoặc chuỗi Base64.
| Param | Type |
| ------------- | -------------------------------------------------------- |
| options | { videoUrl?: string; base64Data?: string; } |
saveFile(...)
saveFile(options: { url?: string; base64Data?: string; fileName?: string; }) => Promise<{ path: string; }>Mở giao diện hệ thống để lưu hoặc chia sẻ một file vào thiết bị (Share/Save native). Hỗ trợ lưu từ URL mạng (http/https - tự động tải về bộ nhớ tạm trước khi mở Share Sheet), URL cục bộ, hoặc chuỗi Base64.
| Param | Type |
| ------------- | ---------------------------------------------------------------------- |
| options | { url?: string; base64Data?: string; fileName?: string; } |
Returns: Promise<{ path: string; }>
pickFile()
pickFile() => Promise<{ path: string; webPath: string; name: string; size: number; type: string; }>Mở trình quản lý file của hệ thống (Files app trên iOS, Document Picker trên Android) để người dùng chọn một file.
Returns: Promise<{ path: string; webPath: string; name: string; size: number; type: string; }>
getSuperAppSettings()
getSuperAppSettings() => Promise<{ theme: { [key: string]: any; mode: 'light' | 'dark'; primaryColor?: string | undefined; secondaryColor?: string | undefined; backgroundColor?: string | undefined; textColor?: string | undefined; fontFamily?: string | undefined; fontScale?: number | undefined; }; language: string; locale: string; timezone: string; is24HourFormat: boolean; }>Lấy cấu hình chung từ Super App đang chạy MiniApp (ví dụ: giao diện tối/sáng, ngôn ngữ hiện hành, màu sắc chủ đạo).
Returns: Promise<{ theme: { [key: string]: any; mode: 'light' | 'dark'; primaryColor?: string; secondaryColor?: string; backgroundColor?: string; textColor?: string; fontFamily?: string; fontScale?: number; }; language: string; locale: string; timezone: string; is24HourFormat: boolean; }>
copyToClipboard(...)
copyToClipboard(options: { text: string; }) => Promise<void>Sao chép một đoạn văn bản vào khay nhớ tạm (Clipboard) của thiết bị.
| Param | Type |
| ------------- | ------------------------------ |
| options | { text: string; } |
setData(...)
setData(options: { key: string; value: string; }) => Promise<void>Lưu trữ dữ liệu cơ bản (UserDefaults trên iOS / SharedPreferences trên Android).
| Param | Type |
| ------------- | -------------------------------------------- |
| options | { key: string; value: string; } |
getData(...)
getData(options: { key: string; }) => Promise<{ value: string; }>Đọc dữ liệu cơ bản đã lưu trước đó.
| Param | Type |
| ------------- | ----------------------------- |
| options | { key: string; } |
Returns: Promise<{ value: string; }>
removeData(...)
removeData(options: { key: string; }) => Promise<void>Xóa một khóa dữ liệu cơ bản.
| Param | Type |
| ------------- | ----------------------------- |
| options | { key: string; } |
setSecretData(...)
setSecretData(options: { key: string; value: string; }) => Promise<void>Lưu dữ liệu nhạy cảm (token, mật khẩu, private key...) một cách bảo mật.
| Param | Type |
| ------------- | -------------------------------------------- |
| options | { key: string; value: string; } |
getSecretData(...)
getSecretData(options: { key: string; }) => Promise<{ value: string; }>Đọc dữ liệu bảo mật đã được mã hóa.
| Param | Type |
| ------------- | ----------------------------- |
| options | { key: string; } |
Returns: Promise<{ value: string; }>
removeSecretData(...)
removeSecretData(options: { key: string; }) => Promise<void>Xóa một khóa dữ liệu bảo mật.
| Param | Type |
| ------------- | ----------------------------- |
| options | { key: string; } |
getCustomDataFromSuperApp()
getCustomDataFromSuperApp() => Promise<{ data: Record<string, any>; }>Lấy dữ liệu tùy chỉnh mà Super App đã gửi xuống cho MiniApp.
Returns: Promise<{ data: Record<string, any>; }>
Interfaces
Photo
| Prop | Type |
| ------------------ | ------------------- |
| path | string |
| webPath | string |
| base64String | string |
| dataUrl | string |
CameraOptions
| Prop | Type |
| ------------------------ | --------------------------------------------- |
| resultType | 'uri' | 'base64' | 'dataUrl' |
| saveToGallery | boolean |
| allowEditing | boolean |
| quality | number |
| width | number |
| height | number |
| correctOrientation | boolean |
| cameraDirection | 'front' | 'rear' |
| source | 'CAMERA' | 'PHOTOS' | 'PROMPT' |
GalleryPhotosOptions
| Prop | Type |
| ------------------------ | ------------------------------------------- |
| resultType | 'uri' | 'base64' | 'dataUrl' |
| quality | number |
| limit | number |
| correctOrientation | boolean |
ConfigAppViewOptions
| Prop | Type | Description |
| ------------------------------------ | -------------------------------------------------- | -------------------------------------------------------------- |
| hideAndroidBottomNavigationBar | boolean | |
| statusBarType | 'normal' | 'hidden' | 'transparent' | |
| statusBarStyle | 'default' | 'light' | 'dark' | |
| hideNavigationBar | boolean | |
| navigationBarTitle | string | Tiêu đề thanh điều hướng. (Chỉ áp dụng cho iOS / iOS only) |
| navigationBarTitleColor | string | Màu chữ tiêu đề Hex. (Chỉ áp dụng cho iOS / iOS only) |
| navigationBarBackgroundColor | string | Màu nền thanh điều hướng Hex. (Chỉ áp dụng cho iOS / iOS only) |
| navigationBarButtonColor | string | Màu các nút điều hướng Hex. (Chỉ áp dụng cho iOS / iOS only) |
Type Aliases
Record
Construct a type with a set of properties K of type T
{ [P in K]: T; }