x-app-sdk

Giới thiệu

x-app-sdk là một thư viện hỗ trợ phát triển ứng dụng với các tính năng tương tác với superapp. SDK với dữ liệu thật chỉ được trả ra khi chạy trên Super App. Khi chạy trên web thường sẽ có những data mẫu có cấu trúc tương tự data thật.

Cài đặt

Bạn có thể cài đặt x-app-sdk bằng npm:

npm install x-app-sdk

Hoặc sử dụng yarn:

yarn add x-app-sdk

Các tính năng chính

1. Config - Cấu hình ứng dụng

configUIApp(config)

Cấu hình giao diện ứng dụng trong SuperApp.

import { configUIApp, IViewUiConfig } from 'x-app-sdk';

const config: IViewUiConfig = {
    // EHeaderMode.MINI hoặc EHeaderMode.FULL
    // js: mode: "mini" | "full"
    // Mode header:
    //  + mode full sẽ hiển thị cả thanh header
    //  + mode mini sẽ chỉ hiển thị icon navigation
    // Mặc định sẽ là mode mini
    mode: EHeaderMode.MINI;
    
    // Các option mode mini
    iconNavigationColor: '#000000'; // màu icon
    navigationColor: '#ffffff'; // màu nền icon
    // Vị trí
    // Thanh điều hướng ở phía bên phải hoặc trái.
    // EIconNavigationPosision.RIGHT hoặc EIconNavigationPosision.LEFT
    // js: iconNavigationPosision: "right" | "left"
    // Mặc định bên phải
    iconNavigationPosision: EIconNavigationPosision.RIGHT,

    // Các option mode full
    headerTitle: 'Tên ứng dụng', // Tiêu đề
    headerColor: '#ffffff', // Màu nền tiêu đề
    headerTextColor: '#000000' // Màu chữ tiêu đề
    headerSubTitle: 'Mô tả ngắn ứng dụng'; // Mô tả ngắn phía dứoi tiêu đề
    headerIcon: 'https://linkicon.png/'; // Icon trên header (Link ảnh)

    
};

configUIApp(config).then(response => {
    console.log('Cấu hình thành công:', response);
}).catch(error => {
    console.error('Lỗi cấu hình:', error);
});

2. Device - Tương tác thiết bị

call(phoneNumber)

Thực hiện cuộc gọi đến số điện thoại.

import { call } from 'x-app-sdk';

call('0123456789').then(() => {
    console.log('Bắt đầu cuộc gọi');
}).catch(error => {
    console.error('Lỗi cuộc gọi:', error);
});

sms(phoneNumber)

Mở ứng dụng tin nhắn với số điện thoại.

import { sms } from 'x-app-sdk';

sms('0123456789').then(() => {
    console.log('Mở ứng dụng tin nhắn');
}).catch(error => {
    console.error('Lỗi tin nhắn:', error);
});

vibrate()

Kích hoạt rung thiết bị.

import { vibrate } from 'x-app-sdk';

vibrate().then(() => {
    console.log('Thiết bị rung');
}).catch(error => {
    console.error('Lỗi rung:', error);
});

3. Location - Dịch vụ vị trí

currentLocation()

Lấy vị trí hiện tại của thiết bị.

import { currentLocation } from 'x-app-sdk';

currentLocation().then(location => {
    console.log('Vị trí hiện tại:', location.data);
}).catch(error => {
    console.error('Lỗi lấy vị trí:', error);
});

requestLocationPermission()

Yêu cầu quyền truy cập vị trí.

import { requestLocationPermission } from 'x-app-sdk';

requestLocationPermission().then(response => {
    console.log('Quyền vị trí:', response);
}).catch(error => {
    console.error('Lỗi quyền vị trí:', error);
});

4. Media - Xử lý phương tiện

openPickerImage(type)

Mở trình chọn ảnh từ thiết bị.

import { openPickerImage, EMediaType } from 'x-app-sdk';

openPickerImage(EMediaType.GALLERY).then(imageData => {
    console.log('Dữ liệu ảnh:', imageData.data);
}).catch(error => {
    console.error('Lỗi chọn ảnh:', error);
});

openPickerFile()

Mở trình chọn file từ thiết bị.

import { openPickerFile } from 'x-app-sdk';

openPickerFile().then(fileData => {
    console.log('Dữ liệu file:', fileData.data);
}).catch(error => {
    console.error('Lỗi chọn file:', error);
});

5. Notification - Thông báo

listenNotifiactionEvent(callback)

Lắng nghe các sự kiện thông báo từ SuperApp.

import { listenNotifiactionEvent } from 'x-app-sdk';

const unsubscribe = listenNotifiactionEvent((data) => {
    console.log('Thông báo mới:', data);
});

// Để hủy lắng nghe
unsubscribe();

6. Payment - Thanh toán

paymentRequest(body)

Thực hiện yêu cầu thanh toán qua SuperApp.

import { paymentRequest } from 'x-app-sdk';

const paymentData = {
    partnerOrderId: "ORDER123";
    totalAmount: 100000;
    extra: "JSON data, string...."; // optional
};

paymentRequest(paymentData).then(result => {
    console.log('Kết quả thanh toán:', result.data);
}).catch(error => {
    console.error('Lỗi thanh toán:', error);
});

listenPaymentEvent(callback)

Lắng nghe các sự kiện thanh toán.

import { listenPaymentEvent } from 'x-app-sdk';

const unsubscribe = listenPaymentEvent((data) => {
    console.log('Sự kiện thanh toán:', data);
});

// Để hủy lắng nghe
unsubscribe();

7. Permission - Quyền truy cập

premissionsRequest(type)

Yêu cầu quyền truy cập cho một tính năng cụ thể.

import { premissionsRequest, ETypeRequest } from 'x-app-sdk';

premissionsRequest(ETypeRequest.RequestPickerImage).then(granted => {
    if (granted.data) {
        console.log('Quyền được cấp');
    } else {
        console.log('Quyền bị từ chối');
    }
}).catch(error => {
    console.error('Lỗi kiểm tra quyền:', error);
});

openPermisstionScreen()

Mở màn cấp quyền.

import { openPermisstionScreen } from 'x-app-sdk';

openPermisstionScreen().then(() => {
    console.error('OK');
}).catch(error => {
    console.error('Lỗi kiểm tra quyền:', error);
});

8. Routing - Điều hướng

closeApp(data?)

Đóng ứng dụng và trả về SuperApp.

import { closeApp } from 'x-app-sdk';

// Đóng ứng dụng
closeApp();

// Đóng ứng dụng với dữ liệu trả về
closeApp({ result: 'success', data: 'some data' });

listenFocusEvent(callback)

Lắng nghe sự kiện focus vào mini app.

import { fltSDK, listenFocusEvent } from 'x-app-sdk';

const handelEVventFocus = (event: FlutterMessageResponse) => {
    console.log("focus:", new Date())
}

const unsubscribeFocus = listenFocusEvent(handelEVventFocus, fltSDK);

// Để hủy lắng nghe
unsubscribe();

9. Store - Lưu trữ cục bộ

saveStore(key, data)

Lưu dữ liệu vào bộ nhớ cục bộ của SuperApp.

import { saveStore } from 'x-app-sdk';

const data = JSON.stringify({ key: 'value' });
saveStore("key", data).then(() => {
    console.log('Dữ liệu đã được lưu');
}).catch(error => {
    console.error('Lỗi lưu dữ liệu:', error);
});

getStore(key)

Lấy dữ liệu từ bộ nhớ cục bộ.

import { getStore } from 'x-app-sdk';

getStore("key").then(result => {
    const data = JSON.parse(result.data);
    console.log('Dữ liệu lấy được:', data);
}).catch(error => {
    console.error('Lỗi lấy dữ liệu:', error);
});

clearStore(key)

Xóa tất cả dữ liệu trong bộ nhớ cục bộ.

import { clearStore } from 'x-app-sdk';

clearStore("key").then(() => {
    console.log('Dữ liệu đã được xóa');
}).catch(error => {
    console.error('Lỗi xóa dữ liệu:', error);
});

10. User - Thông tin người dùng

getInfo(key)

Lấy thông tin người dùng từ SuperApp.

import { getInfo, EKeyInfor } from 'x-app-sdk';

getInfo(EKeyInfor.USER_ID).then(info => {
    console.log('ID người dùng:', info.data);
}).catch(error => {
    console.error('Lỗi lấy thông tin:', error);
});

getToken()

Lấy token đăng nhập ngừoi dùng.

import { getToken } from 'x-app-sdk';

getToken().then(token => {
    console.log('Token người dùng:', token);
}).catch(error => {
    console.error('Lỗi lấy thông tin:', error);
});

11. File

saveFile('url download file')

Tải file về máy qua đường dẫn

import { saveFile } from 'x-app-sdk';

saveFile('https://pdfobject.com/pdf/sample.pdf').then(() => {
    console.log('Thành công:');
}).catch(error => {
    console.error('Lỗi:', error);
});

Lưu ý quan trọng

• Tất cả các API đều yêu cầu SDK được khởi tạo trước khi sử dụng
• Một số tính năng yêu cầu quyền truy cập từ người dùng
• Khi chạy trong browser mode, một số tính năng sẽ trả về dữ liệu mẫu
• Luôn xử lý lỗi (catch) khi gọi các API bất đồng bộ
• Nhớ hủy đăng ký các listener khi không cần thiết để tránh memory leak

Import tổng hợp

Bạn có thể import tất cả các services từ entry point chính:

import {
    // Config
    configUIApp,
    
    // Device
    call, sms, vibrate,
    
    // Location
    currentLocation, requestLocationPermission,
    
    // Media
    openPickerImage, openPickerFile,
    
    // Notification
    listenNotifiactionEvent,
    
    // Payment
    paymentRequest, listenPaymentEvent,
    
    // Permission
    premissionsRequest,
    openPermisstionScreen,
    
    // Routing
    closeApp,
    
    // Store
    saveStore, getStore, clearStore,

    // File
    saveFile
    
    // User
    getInfo, getToken
} from 'x-app-sdk';

Kết luận

Thư viện x-app-sdk giúp bạn dễ dàng tương tác với superapp cho ứng dụng của bạn.