Skip to main content

Tổng quan

econtract_task_moduleFlutter plugin cho phép nhúng toàn bộ luồng Danh sách công việc của econtractid vào ứng dụng Flutter của bạn bằng một hàm duy nhất — chạy trên baseUrlaccessToken của bạn.

Một hàm duy nhất

openTaskList() mở thẳng luồng: danh sách → chi tiết → xem PDF → ký số eKYC → từ chối

Native đóng gói sẵn

Bridge eKYC (Android AAR + iOS xcframework) đi kèm và tự đăng ký

Chạy trên hạ tầng của bạn

Truyền baseUrl + token lúc chạy; token giữ in-memory, không đụng dữ liệu app host

Thoát về host

signOut / back / 401 đều quay về app của bạn kèm callback — không hiện màn login riêng

Kiến trúc

Plugin gồm hai phần:
  • Dart (lib/) — luồng Task List và API công khai EContractModule
  • Native bridge eKYCandroid/ (SDK qua Maven repo bundled) và ios/ (EContractIDSDK.xcframework vendored), tự đăng ký qua GeneratedPluginRegistrant

Yêu cầu

Bắt buộc cấu hình native một lần. Vì luồng có ký số/eKYC dùng SDK native, app host phải cấu hình ở tầng nền tảng (Hilt, quyền camera/NFC). Đây là ràng buộc của hệ điều hành và SDK — không plugin nào thay thế được.
Không cần Firebase. Module đã loại bỏ Firebase — host không cần google-services.json hay GoogleService-Info.plist.

Cài đặt

1. Thêm dependency

Trong pubspec.yaml của app host (phân phối qua private git repo):
Khi phát triển tại máy, dùng path dependency:

2. Lấy package

Đây là plugin, không phải package thường. Native eKYC được kéo theo và tự đăng ký khi bạn thêm dependency — không cần copy bridge hay sửa MainActivity/AppDelegate để add plugin.
Thêm dependency xong vẫn chưa build được — phải cấu hình host Android/iOS ở phần Tích hợp bên dưới.

Tích hợp

Gọi module

Ở bất kỳ đâu có BuildContext:
openTaskList tự khởi tạo (Hive + DI + eKYC) một lần, không gọi runApp, và đẩy route chứa toàn bộ luồng lên navigator của host.

Cấu hình host — Android

eKYC SDK dùng Hilt và camera/NFC. Các mục sau phải nằm ở app host. a. android/settings.gradle
b. android/app/build.gradle
c. Application class @HiltAndroidApp
d. MainActivity kế thừa FlutterFragmentActivity
Không cần flutterEngine.plugins.add(...) — plugin tự đăng ký.
e. AndroidManifest.xml

Cấu hình host — iOS

a. Deployment target ≥ 13 Trong ios/Podfile: platform :ios, '13.0' (hoặc cao hơn), và đặt cùng giá trị IPHONEOS_DEPLOYMENT_TARGET trong Xcode. b. ios/Runner/Info.plist
c. Entitlements NFC Xcode → target RunnerSigning & Capabilities → thêm Near Field Communication Tag Reading.
pod install tự kéo plugin và EContractIDSDK.xcframework (vendored). Plugin tự đăng ký — không sửa AppDelegate.

Hành vi thoát luồng

Module không hiển thị màn login của riêng nó — đăng nhập và làm mới token do app host lo.

Luồng token

Module không tự đăng nhập. Backend của bạn cấp token qua partner-login:
API Key không được đưa vào app di động. Ứng dụng đã cài đặt trên máy người dùng là môi trường không tin cậy — bất kỳ khoá nào nhúng trong app đều có thể bị trích xuất. Luôn để backend của bạn gọi partner-login rồi trả token về cho app.
Trên production, access token có hiệu lực 15 ngày và hệ thống không có endpoint refresh (môi trường development cấu hình dài hơn nhiều). Cách xử lý duy nhất khi hết hạn là backend gọi lại partner-login. Xem Vòng đời token.

API Reference

Lớp EContractModuleđiểm vào công khai duy nhất. Import package:econtract_task_module/econtract_module.dart.

openTaskList

ensureInitialized

Khởi tạo idempotent — gọi nhiều lần chỉ chạy một lần, mọi caller cùng await một future. Thường không cần gọi trực tiếp.

updateAccessToken


Khắc phục sự cố

Thư mục example/ trong repo plugin là app host demo đã build được cả Android lẫn iOS — dùng làm tham chiếu cấu hình chuẩn.

Câu hỏi thường gặp

Module là Flutter plugin (không phải package thường). Nhờ đó thư mục android/ + ios/ chứa bridge eKYC được biên dịch vào app host và tự đăng ký — bạn chỉ cần thêm 1 dependency.
Không. Module đã loại firebase_core/firebase_remote_config và local notification. Host không cần google-services.json / GoogleService-Info.plist.
eKYC SDK dùng Hilt nội bộ — EKycSdkActivity cần @HiltAndroidApp trên Application của host. Đây là ràng buộc của SDK, plugin không thể tự thêm Application class.
Token truyền vào module được giữ in-memory theo phiên, gắn vào header mỗi request, và xoá khi thoát luồng. Module không ghi token xuống thiết bị và không đụng tới dữ liệu lưu trữ của app host.
Toàn bộ request trong phiên của module (qua interceptor) và cả đường tải PDF riêng. Khi thoát luồng, mọi thứ trở về mặc định.
Không — tích hợp nền tảng nào thì cấu hình host nền tảng đó. Cả hai đều đã được kiểm chứng build trong example/.
Không. Flutter package/plugin phân phối dưới dạng source Dart. Private git repo chỉ giới hạn ai được truy cập, không giấu được nội dung source. Muốn giấu hoàn toàn cần host native + Flutter module đã biên dịch — ngoài phạm vi hiện tại.

Checklist trước khi lên production

Hai hạng mục sau phải được xử lý trước khi phát hành ứng dụng thật:
  • Xác thực chứng chỉ SSLdio_consumer.dart hiện bỏ qua kiểm tra chứng chỉ SSL. Với baseUrl tuỳ ý, điều này khiến kết nối có thể bị chặn và đọc bởi bên thứ ba. Bỏ phần bypass và cân nhắc bật certificate pinning.
  • Lưu trữ token phía host — nếu app host lưu token trong Hive dạng văn bản thuần, hãy chuyển sang secure storage của nền tảng (Keychain / Keystore).

Xem thêm

Xác thực API

Lấy access token qua partner-login

Nhúng web (iframe)

Tích hợp cho nền tảng web