A custom React provider with TypeScript support
npm install tek-wallet- Cấu hình
- Components
- States
- Methods
- Hướng dẫn sử dụng
- Lưu ý
---
Để sử dụng TekWallet, bạn cần wrap ứng dụng của mình trong TekWalletProvider. Provider này yêu cầu một số cấu hình cơ bản:
``jsx
import "swiper/css";
import { TekWalletProvider, ThemeModes } from "tek-wallet";
// Cấu hình cơ bản
accessToken={accessToken} // Token từ SSO
>
;
`
Cấu hình nâng cao:
`jsx
import { TekWalletProvider, ThemeModes } from "tek-wallet";
themeMode={ThemeModes.DARK} // Chế độ theme: DARK hoặc LIGHT
isSSO
accessToken={accessToken}
options={{
useDefaultToastMessage: true, // Sử dụng toast message mặc định
hideDefaultActivities: true, // Ẩn activities mặc định
hideActivitySectionInAssetView: true, // Ẩn section activities trong AssetView
useBasicAmountGroupInAssetView: true, // Sử dụng basic amount group trong AssetView
hideBackButtons: {
// Ẩn nút back trong các view cụ thể
activity: true,
},
disableRefetchOnFocus: true, // Vô hiệu hóa việc refetch dữ liệu khi focus lại vào cửa sổ
}}
topOffset={viewportStatusBarHeight || 0} // Offset từ top (thường dùng cho mobile)
onLogout={handleLogout} // Callback khi logout
overrideQRScanMethod={isMobileApp ? scanQRCode : undefined} // Override QR scan method
>
{children}
;
`
Props cơ bản:
| Prop | Type | Required | Mô tả |
| ------------- | --------- | -------- | ----------------------------- |
| isSSO | boolean | ✅ | Bật chế độ SSO authentication |accessToken
| | string | ✅ | Token xác thực từ SSO |
Props nâng cao:
| Prop | Type | Required | Mô tả |
| ---------------------- | ------------ | -------- | ---------------------------------------------------- |
| theme | object | ❌ | Custom theme object |themeMode
| | ThemeModes | ❌ | Chế độ theme: DARK hoặc LIGHT |topOffset
| | number | ❌ | Offset từ top (thường dùng cho mobile status bar) |onLogout
| | function | ❌ | Callback function khi user logout |overrideQRScanMethod
| | function | ❌ | Override QR scan method (thường dùng cho mobile app) |
Options object:
| Option | Type | Default | Mô tả |
| -------------------------------- | --------- | ------- | --------------------------------------------------------- |
| useDefaultToastMessage | boolean | false | Sử dụng toast message mặc định của hệ thống |hideDefaultActivities
| | boolean | false | Ẩn activities mặc định |hideActivitySectionInAssetView
| | boolean | false | Ẩn section activities trong AssetView |useBasicAmountGroupInAssetView
| | boolean | false | Sử dụng basic amount group trong AssetView |hideBackButtons
| | object | {} | Ẩn nút back trong các view cụ thể |disableRefetchOnFocus
| | boolean | false | Vô hiệu hóa việc refetch dữ liệu khi focus lại vào cửa sổ |
hideBackButtons object:
| Property | Type | Mô tả |
| ---------- | --------- | ------------------------------- |
| activity | boolean | Ẩn nút back trong activity view |
Các biến môi trường cần thiết:
`env`
NEXT_PUBLIC_TEK_WALLET_APP_SLUG=your_app_slug
NEXT_PUBLIC_TEK_WALLET_SERVER_URL=your_server_url
NEXT_PUBLIC_TEK_WALLET_ABLY_API_KEY=your_ably_api_key
---
Component này được sử dụng để kiểm tra trạng thái kết nối ví trước khi thực hiện các hành động yêu cầu ví phải được kết nối.
`jsx
import { RequiredConnect, useWallet } from "tek-wallet";
const { tokens } = useWallet();
`
| Component | Mô tả |
| --------------------- | ------------------------------------------ |
| LockToken | Cho phép người dùng khóa token trong ví |
| SwapToken | Hỗ trợ chức năng hoán đổi token |
| UpdateLockedToken | Cho phép cập nhật thông tin token đã khóa |
| ReceiveFunction | Xử lý chức năng nhận token |
| ReceiveDirectly | Component nhận token trực tiếp qua QR code |
| AssetView | Hiển thị tài sản trong ví |
| WithdrawFunction | Xử lý chức năng rút token |
| Component | Mô tả |
| ----------------------- | ---------------------------------------------------------------- |
| ConfirmSwapToken | Xử lý chức năng swap token bản đơn giản (khả năng custom cao) |
| ConfirmSendExternal | Xử lý chức năng rút token bản đơn giản (khả năng custom cao) |
| ConfirmSendInternal | Xử lý chức năng chuyển nội bộ bản đơn giản (khả năng custom cao) |
| Component | Mô tả |
| -------------------- | ---------------------------------------------------------------------- |
| SwapView | Xử lý chức năng swap token bản đầy đủ, có validate, input amount... |
| SendExternalView | Xử lý chức năng rút token bản đầy đủ, có validate, input amount... |
| SendInternalView | Xử lý chức năng chuyển nội bộ bản đầy đủ, có validate, input amount... |
| AssetView | Quản lí asset người dùng |
Component như một app wallet mini (có router nội bộ)
Sử dụng cơ bản:
`jsx
// page: "tek-wallet/[[...pathname]]/page.tsx"
"use client";
import { TekWalletView } from "tek-wallet";
function WalletPage() {
return
}
export default WalletPage;
`
Với basePath:
Nếu phía trước có path: thì thêm basePath vào options:
`jsx`
accessToken={accessToken}
options={{
useDefaultToastMessage: true,
basePath:
}}
>
{props.children}
Ví dụ cấu hình đầy đủ cho mobile app:
`jsx
import { TekWalletProvider, ThemeModes } from "tek-wallet";
function App() {
const handleLogout = () => {
// Xử lý logout logic
console.log("User logged out");
};
const scanQRCode = (callback) => {
// Custom QR scan implementation cho mobile
// Gọi native QR scanner
window.nativeQRScanner?.scan(callback);
};
return (
themeMode={ThemeModes.DARK}
isSSO
accessToken={accessToken}
options={{
useDefaultToastMessage: true,
hideDefaultActivities: true,
hideActivitySectionInAssetView: true,
useBasicAmountGroupInAssetView: true,
hideBackButtons: {
activity: true,
},
}}
topOffset={viewportStatusBarHeight || 0}
onLogout={handleLogout}
overrideQRScanMethod={isMobileApp ? scanQRCode : undefined}
>
);
}
`
Component cho phép hiển thị QR code và địa chỉ nhận token trực tiếp, hỗ trợ cả nhận nội bộ và nhận từ blockchain.
Props:
| Prop | Type | Required | Mô tả |
| ------------- | ----------------------- | -------- | ------------------------------------------------------------ |
| tokenSlug | string | ✅ | Slug của token muốn nhận |method
| | ReceiveDirectlyMethod | ✅ | Phương thức nhận: RECEIVE_INTERNAL hoặc RECEIVE_EXTERNAL |networkSlug
| | string | ❌ | Slug của network (bỏ qua nếu muốn cho user chọn network) |amount
| | string \| number | ❌ | Số lượng token muốn nhận (hiển thị trong QR code) |userInfo
| | object | ❌ | Thông tin người nhận để hiển thị |
Ref Methods:
| Method | Mô tả |
| ------- | ---------- |
| open | Mở modal |close
| | Đóng modal |
Enum ReceiveDirectlyMethod:
`typescript`
enum ReceiveDirectlyMethod {
RECEIVE_INTERNAL = "Internal Transfer", // Nhận token nội bộ
RECEIVE_EXTERNAL = "Blockchain Deposit", // Nhận token từ blockchain
}
Ví dụ 1: Nhận token nội bộ (Internal Transfer)
`jsx
import { ReceiveDirectly, ReceiveDirectlyMethod } from "tek-wallet";
import { useRef } from "react";
function MyComponent() {
const receiveRef = useRef(null);
return (
<>
tokenSlug="usdt"
method={ReceiveDirectlyMethod.RECEIVE_INTERNAL}
amount={100}
userInfo={{
nickname: "John Doe",
username: "@johndoe",
avatar: "https://example.com/avatar.jpg",
}}
/>
>
);
}
`
Ví dụ 2: Nhận token từ blockchain (Blockchain Deposit)
`jsx
import { ReceiveDirectly, ReceiveDirectlyMethod } from "tek-wallet";
import { useRef } from "react";
function MyComponent() {
const receiveRef = useRef(null);
return (
<>
{/ Cách 1: Chỉ định network cụ thể /}
tokenSlug="usdt"
method={ReceiveDirectlyMethod.RECEIVE_EXTERNAL}
networkSlug="trc20"
/>
{/ Cách 2: Cho phép user chọn network /}
tokenSlug="usdt"
method={ReceiveDirectlyMethod.RECEIVE_EXTERNAL}
// Không truyền networkSlug - user sẽ chọn network
/>
>
);
}
`
Ví dụ 3: Sử dụng với trigger children
`jsx`
Lưu ý:
- 🔸 Khi sử dụng RECEIVE_INTERNAL, không cần truyền networkSlugRECEIVE_EXTERNAL
- 🔸 Khi sử dụng mà không truyền networkSlug, user sẽ được yêu cầu chọn network
- 🔸 Component tự động validate token và network, hiển thị lỗi nếu không hợp lệ
- 🔸 QR code được tạo tự động dựa trên method và các thông tin được truyền vào
- 🔸 Với Internal Transfer, QR code chứa thông tin JSON để xử lý chuyển khoản nội bộ
- 🔸 Với Blockchain Deposit, QR code chứa địa chỉ blockchain wallet
---
| State | Type | Description |
| ------------------- | ---------- | ------------------------------------- |
| tokens | Token[] | Danh sách tokens trong ví |isTokensLoading
| | boolean | Trạng thái đang tải danh sách tokens |masterWallet
| | string | Địa chỉ ví hệ thống |blockchainWallets
| | string[] | Mảng địa chỉ ví blockchain |isConnected
| | boolean | Trạng thái đã kết nối Ably (realtime) |
| State | Type | Description |
| ------------------------------- | --------- | -------------------------------------------------------------- |
| isLoadingWithdrawToken | boolean | Trạng thái đang get list các token được phép withdraw |isLoadingSendInternalToken
| | boolean | Trạng thái đang get list các token được phép gửi nội bộ |isLoadingLockToken
| | boolean | Trạng thái đang get list các token được phép khóa |isLoadingLockedToken
| | boolean | Trạng thái đang get list các token đã khóa |isLoadingSwapToken
| | boolean | Trạng thái đang get list các token được phép swap |isLoadingReceiveExternalToken
| | boolean | Trạng thái đang get list các token được phép nhận từ bên ngoài |isLoadingReceiveInternalToken
| | boolean | Trạng thái đang get list các token được phép nhận nội bộ |
| State | Type | Description |
| -------------- | --------------- | ----------------------------------------------------------- |
| lockedTokens | LockedToken[] | Danh sách tokens đã khóa |fromTokens
| | Token[] | Danh sách tokens có thể swap |transaction
| | Transaction | Dữ liệu event realtime mới nhất (swap token, send token...) |
---
| Method | Description |
| ---------------------- | ---------------------------------------------------------------- |
| updateWalletDetail() | Cập nhật lại chi tiết ví, bao gồm địa chỉ ví và danh sách tokens |
| Method | Description |
| ------------------------------ | -------------------------------------------------------- |
| updateWithdrawToken() | Cập nhật danh sách các token được phép withdraw |updateSendInternalToken()
| | Cập nhật danh sách các token được phép gửi nội bộ |updateLockToken()
| | Cập nhật danh sách các token được phép khóa |updateLockedToken()
| | Cập nhật danh sách các token đã khóa |updateSwapTokens()
| | Cập nhật danh sách các token được phép swap |updateReceiveExternalToken()
| | Cập nhật danh sách các token được phép nhận từ bên ngoài |updateReceiveInternalToken()
| | Cập nhật danh sách các token được phép nhận nội bộ |
| Method | Description |
| -------------------------------- | ------------------------------------ |
| validateWalletAddressService() | Validate địa chỉ ví nội bộ / Onchain |
| Method | Description |
| -------------------- | ---------------------- |
| pushNotification() | Hiển thị toast message |
---
Để bắt đầu sử dụng TekWallet, hãy đảm bảo:
1. ✅ Đã cài đặt đầy đủ các dependencies cần thiết
2. ✅ Đã cấu hình đúng các biến môi trường
3. ✅ Đã wrap ứng dụng trong TekWalletProvider
4. ✅ Đã import các components cần thiết từ package
---
- 🔒 Đảm bảo luôn sử dụng RequiredConnect` cho các hành động yêu cầu ví phải được kết nối
- 🔧 Các biến môi trường phải được cấu hình đúng để đảm bảo ứng dụng hoạt động chính xác
---
##