Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CodexaCP/DG_APK/llms.txt

Use this file to discover all available pages before exploring further.

Dragon Guard Handheld WMS targets rugged Android devices running API 21 or higher. This guide walks you through every step needed to get a working build running on a physical device — from cloning the repository to seeing the four home modules appear after first login.
Shell navigation is disabled. AppShell.xaml is excluded from compilation because it crashes on rugged Android firmware. Never re-add it or use Shell.Current.GoToAsync() anywhere in the codebase. All navigation goes through NavigationService.
1

Meet the prerequisites

Make sure you have the following installed and available before you start:
RequirementVersion / notes
.NET SDK8.0 or later (dotnet --version to verify)
.NET MAUI workloaddotnet workload install maui-android
Android SDKAPI level 21 (Android 5.0) minimum, API 34 recommended
Java / JDK17 recommended (required by Android tooling)
Android deviceUSB debugging enabled; rugged terminal or standard phone
Dragon Guard backendRunning and reachable from the device’s network
If you are using Visual Studio 2022 or later, the MAUI and Android SDK components can be installed directly from the Visual Studio Installer under Mobile development with .NET.
2

Clone the repository and open the solution

git clone <repository-url>
cd DG_APK
Open Handheld.sln in Visual Studio 2022, JetBrains Rider, or your preferred .NET IDE. The solution contains a single project targeting net8.0-android.
The active <TargetFramework> in Handheld.csproj is net8.0-android. Other frameworks (Windows, iOS, MacCatalyst, Tizen) appear in project tooling but are untested — keep the active target as Android.
3

Configure the backend base URL

The app resolves the Dragon Guard backend using compile-time constants in Constants/ApiConstants.cs. Edit this file to point at your backend server before building:
Constants/ApiConstants.cs
namespace Handheld.Constants;

public static class ApiConstants
{
    public const string DefaultAndroidBaseUrl = "http://192.168.100.4:5262/";
    public const string DefaultDesktopBaseUrl = "http://localhost:5262/";
    public const string PlaceholderBaseUrl = "http://placeholder.invalid/";
}
  • DefaultAndroidBaseUrl — used at runtime when the app runs on Android. Replace 192.168.100.4 with the IP address of your Dragon Guard backend server on the local network.
  • DefaultDesktopBaseUrl — used when running on non-Android targets (development/testing only).
  • PlaceholderBaseUrl — the initial BaseAddress assigned to every HttpClient at DI registration time. DynamicBaseUrlMessageHandler overwrites it before each request; you should never see traffic actually reach this address.
In DEBUG builds, operators can override the base URL from the Settings screen on-device. Official (Release) builds ignore any saved override and always use DefaultAndroidBaseUrl. This is enforced by AppExperienceService.AllowConnectionOverride, which returns true only in DEBUG.
4

Build and deploy to the Android device

Connect the device via USB and confirm it appears in adb devices, then publish:
dotnet publish -f net8.0-android -c Release
To deploy directly to a connected device during development:
dotnet build -f net8.0-android -c Debug -t:Run
Debug APKs are built with EmbedAssembliesIntoApk = true (set in Handheld.csproj). This makes Debug builds self-contained because some rugged Android firmware breaks MAUI’s fast-deployment assembly override mechanism. Debug builds are therefore larger and slower to deploy, but they run reliably on all tested terminals.
5

Register the device with a Supreme Admin

Dragon Guard enforces device-level authorisation. Before any user can log in, a Supreme Admin must register the device in the Dragon Guard backend using the device’s identifier.The app resolves its identity through the following fallback chain (implemented in DeviceIdentityService):
  1. WiFi MAC address
  2. ANDROID_ID
  3. Randomly generated GUID (persisted to SecureStorage)
To register the device:
  1. Launch the app — it will show the SafeBootPage splash screen while initialising.
  2. Note the device ID shown on the registration prompt (or retrieve it from the app’s Settings screen).
  3. Have a Supreme Admin add that device ID in the Dragon Guard backend admin panel.
  4. The device is now authorised to accept login credentials for that tenant.
Login will be rejected with an authorisation error until the device is registered. This is by design — the backend authorises only Supreme-registered device identities for each tenant.
6

Log in for the first time

With the device registered, enter your operator credentials on the Login screen:
  1. Enter username and password.
  2. The app calls POST api/auth/grupomas-handheld-login, sending username, password, deviceId, and deviceName.
  3. The backend validates the device identity and returns a Dragon Guard JWT.
  4. SessionService stores the token and the list of companies the user has access to.
  5. Exactly one company must be available. Zero companies or multiple companies block login — the app never silently picks the first entry.
  6. On success, App.xaml.cs calls ShowHomeAsync() and the NavigationPage root is replaced with MainPage.
While the session is being restored on startup, the app displays the SafeBootPage splash — a full-screen gradient (Dragon Guard navy) with a “Preparando entorno operativo” spinner. This page is shown briefly on every cold start while SessionService.InitializeAsync() reads from SecureStorage. Once the session check completes, the app routes to MainPage (valid session) or LoginPage (no valid session).
7

Verify the four home modules appear

After a successful login you should see the MainPage home screen with exactly four operational tiles:
TileNavigates to
ItemsItemInquiryPage — product and RFID lookup
ReceiptsReceivingPage — receiving header list
ShipmentsShipmentHeadersPage — outbound shipment list
MovementsMovementsPage — inventory movement list and journals
If you see these four tiles, the app is correctly connected to the backend and the session is fully initialised. You are ready to use Dragon Guard Handheld WMS in your warehouse environment.
Users, Companies, Picks, and admin shortcuts are intentionally hidden on the handheld home screen. If you need to verify those code paths, they remain in the codebase but are not exposed in the navigation.

Build docs developers (and LLMs) love

Get started for freeTalk to us