react-native-timacare

Tima Care SDK — bộ SDK React Native cho phép nhúng toàn bộ luồng vay/quản lý khoản vay của Tima vào ứng dụng của bạn: định danh eKYC, xác thực khuôn mặt (liveness), ký hợp đồng điện tử (eSign), giải ngân số (digital lending), lịch trả nợ, thanh toán và chi tiết khoản vay.

SDK cung cấp sẵn một cây điều hướng (navigator) với đầy đủ các màn hình nghiệp vụ. Ứng dụng chủ (host app) chỉ cần khởi tạo cấu hình, gắn <RNTimacare /> vào NavigationContainer của mình và điều hướng vào SDK khi cần.

Tính năng

• eKYC / định danh: chụp CCCD (mặt trước/sau), quét MRZ, selfie, OCR giấy tờ xe.
• Liveness: xác thực khuôn mặt (bao gồm bản v2).
• eSign & hợp đồng: xem trước, ký và xác nhận hợp đồng điện tử (Tima, CIMB, MySign Viettel).
• Digital lending: luồng nộp hồ sơ nhanh (quick submit) và đầy đủ (full submit), toàn trình số.
• Quản lý khoản vay: chi tiết khoản vay, lịch trả nợ, thanh toán, mã QR, minh chứng chuyển khoản.
• Điều hướng có kiểm soát: deep-link trực tiếp vào chi tiết khoản vay từ bên ngoài SDK (ví dụ từ push notification hoặc danh sách của host app).
• Bền bỉ với mạng yếu: tự động retry request GET khi lỗi tạm thời, phát hiện offline qua NetInfo (tuỳ chọn), xử lý phiên hết hạn (401) tập trung.

Yêu cầu

• React Native >= 0.72 (đã kiểm thử với 0.77.x)
• React >= 18
• @react-navigation/native và @react-navigation/native-stack (v6+)
• react-native-safe-area-context

SDK sử dụng nhiều thư viện native (camera, vision-camera, pdf, svg, fast-image, ...). Các thư viện này được khai báo là peer dependencies — host app phải tự cài đặt. Xem danh sách đầy đủ trong mục peerDependencies của package.json.

Cài đặt

# npm
npm install react-native-timacare

# yarn
yarn add react-native-timacare

Sau đó cài các peer dependencies được liệt kê trong package.json và chạy pod install cho iOS:

cd ios && pod install && cd ..

Tích hợp nhanh

Host app tự sở hữu NavigationContainer của mình, đăng ký ref đó cho SDK, khởi tạo cấu hình bằng initSDK, rồi render <RNTimacare />.

import * as React from 'react';
import { StatusBar } from 'react-native';
import {
  NavigationContainer,
  useNavigationContainerRef,
} from '@react-navigation/native';
import {
  initialWindowMetrics,
  SafeAreaProvider,
} from 'react-native-safe-area-context';
import { RNTimacare, initSDK, setNavigationRef } from 'react-native-timacare';

export default function App() {
  // Host app tự quản lý ref của NavigationContainer...
  const navigationRef = useNavigationContainerRef();

  // ...và đăng ký ref đó cho SDK một lần, để goDetail() có thể điều hướng.
  React.useEffect(() => {
    setNavigationRef(navigationRef);
  }, [navigationRef]);

  initSDK({
    baseUrl: 'https://apilos.tima.vn/',
    token: 'YOUR_JWT_TOKEN',
    timeout: 300000,
    logout: () => {
      // Phiên hết hạn (401): điều hướng về màn hình đăng nhập, xoá token, ...
      console.log('[App] 401 - Session expired, logging out...');
    },
  });

  return (
    <SafeAreaProvider initialMetrics={initialWindowMetrics}>
      <StatusBar
        translucent
        backgroundColor="transparent"
        barStyle="dark-content"
      />
      <NavigationContainer ref={navigationRef}>
        <RNTimacare />
      </NavigationContainer>
    </SafeAreaProvider>
  );
}

Xem ví dụ đầy đủ, chạy được trong thư mục example/.

API

SDK export 4 thành phần chính từ react-native-timacare:

import { RNTimacare, initSDK, setNavigationRef, goDetail } from 'react-native-timacare';

RNTimacare

Component React render cây điều hướng của SDK (PrimaryNavigator) với toàn bộ các màn hình nghiệp vụ. Đặt bên trong NavigationContainer của host app.

initSDK(options: SDKConfig)

Khởi tạo SDK. Nên gọi trước khi render <RNTimacare />. Ngoài việc lưu cấu hình, hàm này còn thu thập thông tin thiết bị (deviceId, IP công khai, appId, payload thiết bị) phục vụ nghiệp vụ.

| Tham số | Kiểu | Bắt buộc | Mô tả | | ------------ | ----------------------- | :------: | -------------------------------------------------------------------------------------------------------- | | baseUrl | string | ✅ | Base URL của API Tima (ví dụ https://apilos.tima.vn/). | | token | string | – | JWT xác thực người dùng, gắn vào header mỗi request. | | timeout | number | – | Timeout (ms) cho các request ghi/upload. Mặc định do SDK quản lý. | | getTimeout | number | – | Timeout (ms) riêng cho request GET (idempotent). Mặc định 30000. Fail nhanh để cơ chế retry tiếp quản. | | logout | () => void | – | Callback khi API trả về 401. Dùng để đưa người dùng về màn hình đăng nhập, xoá token, ... | | netInfo | NetInfoLike | – | Truyền default export của @react-native-community/netinfo để fail ngay khi mất kết nối thay vì đợi timeout. |

Gọi bất kỳ API nào của SDK trước khi initSDK sẽ ném lỗi SDK not initialized. Call initSDK() first.

setNavigationRef(ref, hostRoute?)

Đăng ký ref của NavigationContainer (từ useNavigationContainerRef() hoặc createNavigationContainerRef()) cho SDK. Nhờ đó goDetail() có thể điều hướng ngay cả khi được gọi từ bên ngoài React.

• ref: ref của container (chấp nhận cả dạng object có method trực tiếp lẫn useRef() gắn qua .current).
• hostRoute (tuỳ chọn): tên route của host app đang render <RNTimacare />. Cần khai báo khi SDK chưa được mount sẵn (host có màn hình riêng và chỉ mount SDK dưới một route riêng) để deep-link vào SDK trong một lần điều hướng.

goDetail(loan)

Điều hướng thẳng vào màn hình chi tiết khoản vay một cách imperative — hữu ích khi mở từ push notification hoặc danh sách khoản vay do host app tự render.

// Chỉ với id khoản vay
goDetail(12345);

// Hoặc với object khoản vay
goDetail({ id: 12345, disbursementPartner: 'CIMB' });

• Chỉ cần id để tải dữ liệu chi tiết.
• disbursementPartner === 'CIMB' → mở màn DetailLoan; ngược lại → DetailLoanTima.

Thứ tự phân giải điều hướng: (1) nếu navigator của SDK đang mount → điều hướng trực tiếp; (2) nếu chưa mount nhưng host đã đăng ký ref + hostRoute → mount SDK và deep-link trong một lần; (3) fallback: dispatch qua ref của host (chỉ hoạt động khi SDK là navigator gốc).

Cấu trúc source

src
├── RNTimacare.tsx        # Component gốc render PrimaryNavigator
├── sdkConfig.ts          # initSDK / getSDKConfig, kiểu SDKConfig
├── index.tsx             # Public API export
├── navigation/           # PrimaryNavigator, root-navigator, navigationRef, goDetail
├── screens/              # Toàn bộ màn hình nghiệp vụ (eKYC, eSign, liveness, loan, ...)
├── services/api/         # Lớp API (apisauce) + retry, xử lý 401, api-problem
├── components/           # Component dùng chung
├── constants/            # Hằng số
├── theme/                # Màu sắc, spacing, typography
├── utils/                # Tiện ích (log, storage, ...)
└── assets/               # Ảnh, icon, animation

Phát triển

Dự án sử dụng react-native-builder-bob để build thư viện.

# Cài đặt dependencies cho cả thư viện và example
yarn bootstrap

# Chạy app ví dụ
yarn example android
yarn example ios

# Kiểm tra
yarn typecheck   # Kiểm tra kiểu TypeScript
yarn lint        # ESLint
yarn test        # Jest

# Build thư viện
yarn prepack

App demo nằm trong thư mục example/ và import trực tiếp từ mã nguồn thư viện.

License

MIT © Quang Duc