wirabasalamah/Emoney-Info---Android
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Emoney-Info---Android/docs/CODE_DOCUMENTATION.md
wirabasalamah ef756b97a1 Initial import
2026-04-22 22:31:52 +07:00

12 KiB
Raw Permalink Blame History

Code Documentation

Dokumen ini menjelaskan struktur code Android Emoney Info agar developer lain bisa lebih cepat memahami project, mencari area yang relevan, dan melakukan perubahan dengan aman.

1. Ringkasan Project

Project ini adalah versi Android dari aplikasi iOS Emoney Info.

Fungsi utama aplikasi:

  • membaca kartu uang elektronik via NFC
  • menampilkan saldo dan riwayat transaksi
  • menampilkan halaman bantuan dan informasi aplikasi
  • mengekspor history transaksi ke PDF
  • menampilkan iklan AdMob banner dan interstitial

Stack utama:

  • Kotlin
  • Jetpack Compose
  • Android NFC (IsoDep, NfcF, MifareClassic)
  • Google Mobile Ads SDK

Package utama:

  • com.korancrew.emoneyinfo

2. Struktur Folder

Struktur code utama ada di:

app/src/main/java/com/korancrew/emoneyinfo
├── ads
├── data
├── nfc
├── pdf
├── ui
├── util
└── MainActivity.kt

Penjelasan singkat:

  • ads Menyimpan konfigurasi AdMob.

  • data Menyimpan model UI utama dan data FAQ.

  • nfc Berisi seluruh logic pembacaan kartu, helper APDU/FeliCa, kriptografi Brizzi, dan router NFC.

  • pdf Logic export history transaksi menjadi PDF.

  • ui Semua screen Compose, komponen UI, tema, dan root app navigation.

  • util Helper umum. Saat ini dipakai untuk logging debug-only.

3. Entry Point Aplikasi

File utama:

Tanggung jawab MainActivity:

  • mengaktifkan theme utama
  • inisialisasi AdMob
  • membuat UnifiedNfcReader
  • me-render root Compose lewat EmoneyInfoApp
  • meneruskan event NFC dari onNewIntent
  • mengaktifkan dan menonaktifkan foreground dispatch NFC pada onResume / onPause

Secara sederhana, MainActivity adalah jembatan antara lifecycle Android dengan UI dan NFC reader.

4. Root UI dan Navigasi

File utama:

EmoneyInfoApp adalah root Compose application. File ini menangani:

  • bottom navigation
  • NavHost dan route screen
  • membaca uiState dari UnifiedNfcReader
  • membaca dan menyimpan preference show card number

Route utama:

  • home
  • settings
  • history
  • faq
  • about
  • terms
  • privacy

Bottom navigation hanya menampilkan:

  • E-Money
  • Settings

5. Screen Utama

Screen Compose ada di folder:

  • /ui/screens

Yang paling penting:

  • HomeScreen.kt Menampilkan hasil scan terakhir, saldo, nomor kartu, dan transaksi terakhir.

  • HistoryScreen.kt Menampilkan list riwayat transaksi, banner ads, dan tombol export PDF fixed di bawah.

  • SettingsScreen.kt Menampilkan 4 menu utama: bahasa, tampilkan nomor kartu, pusat bantuan, dan tentang aplikasi.

  • FaqScreen.kt Menampilkan FAQ dan pencarian pertanyaan.

  • AboutScreen.kt Menampilkan info aplikasi dan navigasi ke terms/privacy.

6. Model Data UI

File utama:

Model inti:

CardType

Enum untuk jenis kartu:

  • MANDIRI
  • FLAZZ
  • BRIZZI
  • TAPCASH
  • JACKCARD
  • MEGACASH
  • KMT

TransactionItem

Mewakili 1 item riwayat transaksi.

Field penting:

  • title
  • date
  • amount
  • isCredit
  • locationName

Method penting:

  • formattedAmount()
  • formattedDate()
  • subtitle()

Catatan:

  • currency selalu diformat sebagai IDR / Rp
  • warna amount di UI ditentukan dari isCredit

EmoneyUiState

State utama yang dipakai UI.

Field penting:

  • cardType
  • balance
  • cardNumber
  • transactions
  • scanMessage
  • isNfcSupported

Semua screen utama membaca state ini, terutama HomeScreen dan HistoryScreen.

7. Arsitektur NFC

Folder utama:

  • /nfc

File yang paling penting:

7.1 UnifiedNfcReader

UnifiedNfcReader adalah orchestrator NFC aplikasi.

Tanggung jawab:

  • mengecek apakah device support NFC
  • menyimpan uiState dalam StateFlow
  • menerima Tag dari onNewIntent
  • memilih reader yang sesuai berdasarkan teknologi kartu
  • mengubah hasil pembacaan menjadi EmoneyUiState
  • mengatur pesan UI seperti tap card hint dan tap again hint

Reader yang didaftarkan saat ini:

  • IsoDepCardRouter()
  • MifareClassicCardReader()
  • FelicaCardReader()

7.2 CardReaders.kt

File ini berisi implementasi pembacaan kartu per keluarga teknologi dan per jenis kartu.

Struktur utamanya:

  • CardReader
  • IsoDepCardRouter
  • FelicaCardReader
  • MifareClassicCardReader
  • object reader spesifik, seperti BrizziReader, MandiriReader, FlazzReader, TapCashReader, dan lainnya

Alur umum:

  1. router menentukan teknologi kartu
  2. router memanggil reader spesifik
  3. reader mengirim command APDU atau FeliCa
  4. response di-parse menjadi saldo, nomor kartu, dan history
  5. hasil akhir dikembalikan sebagai EmoneyUiState

7.3 NfcUtils.kt

File ini berisi helper low-level:

  • ApduResponse
  • transceiveApdu
  • transceiveSelect
  • helper FeliCa read
  • helper hex, endian, format card number, parsing tanggal

Ini adalah file utility inti untuk operasi byte-level dan APDU.

7.4 BrizziCrypto.kt

Khusus untuk flow Brizzi yang membutuhkan proses auth/crypto.

File ini sebaiknya disentuh dengan hati-hati karena error kecil pada:

  • mode cipher
  • IV
  • padding
  • urutan challenge

bisa membuat kartu gagal dibaca.

8. Dukungan Kartu

Kartu yang saat ini sudah menjadi target utama:

  • Brizzi
  • Flazz BCA
  • Mandiri e-Money
  • BNI TapCash
  • KMT
  • JackCard
  • MegaCash

Catatan penting:

  • tidak semua kartu memakai flow yang sama
  • beberapa kartu memakai IsoDep
  • KMT memakai NfcF
  • ada fallback MifareClassic untuk kasus tertentu

Untuk perubahan parser, validasi terbaik tetap lewat test pada kartu fisik nyata.

9. Alur Scan NFC

Secara sederhana:

  1. MainActivity.onResume() mengaktifkan foreground dispatch
  2. user menempelkan kartu
  3. Android mengirim Intent NFC ke activity yang sedang aktif
  4. MainActivity.onNewIntent() meneruskan intent ke UnifiedNfcReader
  5. UnifiedNfcReader memilih reader yang cocok
  6. reader membaca data kartu
  7. hasil scan dimasukkan ke uiState
  8. UI Compose otomatis recompose dan menampilkan saldo/history terbaru

Setelah scan berhasil, scanMessage akan berubah lalu kembali ke hint scan ulang setelah 5 detik.

10. Localization

String resource:

App mendukung:

  • Inggris
  • Indonesia

Catatan:

  • bahasa UI mengikuti locale device
  • currency tetap IDR
  • beberapa pesan scan dari layer NFC juga dilokalisasi melalui AndroidStrings

11. AdMob

File utama:

Penempatan saat ini:

  • banner di Home
  • banner di History
  • banner di Settings
  • interstitial sebelum export PDF

Catatan implementasi:

  • test device IDs hanya diaktifkan pada BuildConfig.DEBUG
  • logging ads dibatasi ke debug build melalui AppLog

12. Export PDF

File utama:

Fungsi utama:

  • menghasilkan PDF dari EmoneyUiState
  • menyertakan tipe kartu, saldo, nomor kartu, dan tabel transaksi
  • membuka chooser agar file bisa dibuka atau dibagikan

Flow dari UI:

  1. user menekan Export PDF
  2. jika interstitial tersedia, iklan ditampilkan dulu
  3. setelah iklan selesai atau gagal tampil, PDF dibuat
  4. file dibuka lewat chooser

13. Preference Lokal

Saat ini preference utama yang dipakai:

  • masked

Disimpan di:

  • SharedPreferences("emoney_info_prefs")

Dipakai untuk:

  • menentukan apakah nomor kartu ditampilkan penuh atau dimasking

Catatan:

  • key masked saat ini bernilai true ketika nomor kartu ditampilkan penuh
  • nama key ini tidak ideal secara semantik
  • kalau nanti ingin dirapikan, sebaiknya diganti menjadi key yang lebih jelas, misalnya show_card_number

14. Logging dan Build Production

File utama:

Prinsip saat ini:

  • log sensitif hanya aktif di debug build
  • release build memakai:
    • minifyEnabled = true
    • shrinkResources = true

Ini penting karena flow NFC dan ads punya banyak data internal yang tidak perlu muncul di production log.

15. File Yang Paling Sering Diedit

Kalau ingin ubah tampilan:

  • /ui/screens
  • /ui/theme
  • /res/values

Kalau ingin ubah parser kartu:

  • /nfc/CardReaders.kt
  • /nfc/NfcUtils.kt
  • /nfc/BrizziCrypto.kt

Kalau ingin ubah model dan formatting:

  • /data/Models.kt

Kalau ingin ubah ads:

  • /ads/AdMobConfig.kt
  • /ui/components/AdMobBanner.kt

Kalau ingin ubah PDF:

  • /pdf/HistoryPdfExporter.kt

16. Risiko dan Catatan Maintenance

Beberapa area sensitif:

  • parser NFC Perubahan kecil bisa memutus pembacaan kartu tertentu.

  • flow Brizzi Paling sensitif karena ada auth dan kriptografi.

  • formatting UI berdasarkan locationName KMT memakai lokasi valid, tapi kartu lain tidak selalu punya mapping lokasi yang berguna.

  • preference masked Namanya membingungkan dan bisa memicu bug kalau dibaca tanpa konteks.

  • ads production Pastikan testing device ID tidak dipakai untuk release path, dan lakukan uji di device nyata.

17. Saran Pengembangan Selanjutnya

Beberapa perbaikan yang layak dipertimbangkan:

  • pecah CardReaders.kt menjadi beberapa file per kartu agar lebih mudah dirawat
  • ganti SharedPreferences sederhana ke wrapper preference yang lebih eksplisit
  • buat test parser terpisah untuk data response yang sudah diketahui
  • tambahkan dokumentasi mapping kartu dan APDU per provider
  • rapikan naming key masked

18. Ringkasan Cepat

Kalau hanya ingin memahami project dengan cepat, mulai dari file ini:

  1. MainActivity.kt
  2. EmoneyInfoApp.kt
  3. Models.kt
  4. UnifiedNfcReader.kt
  5. CardReaders.kt
  6. HistoryScreen.kt
  7. HistoryPdfExporter.kt

Dengan urutan itu, sebagian besar arsitektur project sudah akan terlihat.