Android guide

Requirements and installation

Android 8.0 / API 26 or later is required. Install the production APK from GitHub releases or the download link in the web sidebar/About page. Android asks you to authorize installation from the downloading application.

The production application ID is fr.zukan.app. Debug builds use fr.zukan.app.dev and can be installed alongside production. Debug and production SSO redirect schemes differ.

Connect to the server

1. Enter your Zukan server URL, including https:// or explicit http:// for a trusted local setup.
2. Use a reachable domain or LAN IP. localhost refers to the phone, not the computer running Docker.
3. Sign in with a local account or select the offered SSO provider.
4. For SSO, complete sign-in in the external browser and return through the app redirect.
5. Confirm the account and server in Settings.

SSO in Android requires a configured public mobile client. A working web SSO client alone is insufficient. Both clients must share the issuer so they reach the same account.

Scan a card

1. Open the scan screen and grant camera permission.
2. Select the game/market when known; Any game is available but can be less specific.
3. Hold a single card steadily with the name and printed identifiers visible. Reduce reflections and keep small collector numbers in focus.
4. Wait for recognition and inspect the candidates.
5. Choose the exact printing. Check set, number, rarity, language and finish against the physical card.
6. Set condition and quantity, then add or remove copies.
7. Use Undo if the last stock adjustment was wrong.

Recognition does not automatically add a card merely because the camera sees it. Review the selected printing before changing stock. The “next card” preference controls whether the camera resumes after adding; it does not authorize unattended inventory updates.

What recognition does

CameraX supplies frames to bundled ML Kit text models. Text recognition runs on the phone. The app sends recognized text lines and normalized bounding boxes to /api/scan/identify; this scan endpoint does not accept a card-photo upload.

The server parses game-specific hints and matches set/number, then number/name, then approximate localized names. It can query catalog sources when a card is missing. This is OCR-assisted matching, not an illustration-embedding or trained visual-card classifier. A confidence score is a ranking signal, not a probability guarantee.

Recognizing text locally does not make collection scanning offline: identification and stock changes need the server. There is no documented offline mutation queue in this revision.

Recognition settings

Text recognition: Auto, Latin, Japanese, Chinese or Korean. Auto samples the bundled models and selects a likely script; a fixed script can be useful for a homogeneous batch. Latin covers supported European text. Thai and Indonesian catalog availability does not imply a dedicated Thai OCR model.

After adding: stay on the result or move to the next card.

Default condition / language: defaults for stock entry. A printing-specific language can be used rather than a fixed language. Verify defaults when switching batches or games.

Price sources: account-level markets and main source are available in Android too.

Search and collection

Manual search is available when OCR fails or the card is not in front of you. Use the printing picker to distinguish versions. The Collection screen shows the same server-held inventory as the web account, with its filters and stock controls; it is not a separate local database.

Error states

State	Meaning and action
Not a card	The recognized text lacks usable card hints; improve framing or use manual search
Card not found	Card-like text was read but no catalog match was returned; inspect the detected text and market
Other game	The selected game does not match detected hints; switch to the suggested game
Network/session error	Check server reachability, certificate and login
Wrong candidate	Choose another printing/candidate; search manually before adding

TLS and local networks

HTTPS needs a certificate matching the hostname and a complete chain. The app trusts system and user-installed CAs; private deployments may use a properly installed private CA. Plain HTTP is allowed by the network configuration and the app warns about it. It does not provide encryption.

The app distinguishes hostname mismatch, untrusted/incomplete chain, and HTTPS sent to a plain HTTP port. Correct the server URL or certificate rather than assuming every TLS failure has the same cause.

Updates and logout

Production builds check for new versions approximately daily and support a manual check in Settings. Downloading an update and confirming installation are separate steps; Android presents the installer. Development builds do not use the same production update workflow.

Settings offers Log out and Change server. Account data stays on the server. Clearing application data removes local connection settings/tokens, not the server collection. Android backup is disabled for this app; the server backup is the authoritative recovery method.

Implementation references

• android/app/src/main/java/fr/zukan/app/ui/ScanScreen.kt
• android/app/src/main/java/fr/zukan/app/scan/TextAnalyzer.kt
• android/app/src/main/java/fr/zukan/app/ui/SettingsScreen.kt
• android/app/build.gradle.kts