Skip to main content

Mobile App

The Mobile App page configures the GEM native mobile app (iOS and Android). It generates a QR code for first-launch setup and shows connected native clients.

Open Mobile App

Overview​

The GEM mobile app connects phones and tablets directly to your GEM server. It provides:

  • Native push notifications via Apple Push Notification service (iOS) and Firebase Cloud Messaging (Android) — even when the app is closed
  • Incoming call UI for gate and intercom alerts (CallKit on iOS, full-screen notification on Android)
  • Offline resilience — the app reconnects automatically when the server comes back online

Download the App​

A Download the App section at the top of the page lets users install the mobile app without visiting an app store.

Android​

When an Android APK has been bundled into the running GEM release, a card shows:

  • App version and file size
  • A Download APK button that serves the installer directly from the controller
  • A QR code that encodes the download URL — scan from an Android device to install

The installer needs "Install unknown apps" permission granted to the phone's browser. This is a one-time prompt on Android.

The APK is bundled into the release when ./scripts/deploy-mobile.sh android --release is run before npm run build. The build probes dist/client/mobile/gem.apk and writes a sidecar dist/client/mobile/version.json with the app version, file size, and download URL. If no APK is bundled, the card shows "Not bundled in this release" and gives the build command.

iOS​

iOS builds are distributed through the App Store as an unlisted listing — reachable only via the direct link, not surfaced in App Store search. The page shows an Open in App Store button and a QR code that opens the listing on the scanning device:

https://apps.apple.com/us/app/gem-controller/id6763400332

tip

The Android APK bundled into the release is signed with the Play Store upload key (if configured via GEM_KEYSTORE_FILE and related properties in ~/.gradle/gradle.properties) so it can be installed alongside an existing Play Store install without conflict.

:::tip Self-serve from the UI selector End users can reach the same iOS / Android / Setup Code QR codes without admin access — the UI selector screen has a Mobile App button that opens a modal with all three QR codes (App Store link, bundled APK if available, and the current server URL). :::

Server URL​

The server URL is the address the mobile app uses to connect to your GEM server.

  • Default: The URL you are currently browsing the admin on
  • Custom: For installations behind a reverse proxy or cloud relay, enter the public URL instead
  • Click Save to persist the URL — it is stored as a system attribute and used to generate the QR code
tip

If your GEM server uses a cloud proxy (e.g., https://home.mygem.us), set that as the server URL so mobile devices can connect from anywhere.

Certificate Auto-Install​

If your GEM server uses HTTPS with a self-signed or private CA certificate, the QR code can include the certificate URL. When the mobile app scans this code, it offers a one-tap Install Certificate button that opens the CA cert in the device's system browser.

  • Toggle: Enable or disable including the certificate URL in the QR code
  • Cert URL: Derived automatically from your server URL and the SSL HTTP port (e.g., http://192.168.1.10:8080/ssl/ca.pem)

The user only needs to install the certificate once per device. After installation, the mobile app trusts your server's HTTPS automatically.

warning

If SSL is enabled but no CA certificate exists yet, generate one first on the Server page's SSL / TLS tab.

Certificate Installation Steps​

iOS:

  1. Scan QR code and tap Install Certificate
  2. Go to Settings > General > VPN & Device Management > Install the profile
  3. Go to Settings > General > About > Certificate Trust Settings > Enable trust for the GEM CA

Android:

  1. Scan QR code and tap Install Certificate
  2. The certificate is saved to Downloads and Settings opens automatically
  3. Navigate to Security > Encryption & credentials > Install a certificate > CA certificate
  4. Select the gem-ca.crt file from Downloads

Setup Code​

The QR code encodes the server URL (and optionally the certificate URL) for the mobile app's first-launch setup screen.

QR Code Payload​

The QR code uses one of two formats:

  • Plain URL: Just the server address (e.g., https://gem.example.com)
  • Structured JSON: Includes certificate URL and site name: 
    {"url":"https://gem.example.com","ca":"http://192.168.1.10:8080/ssl/ca.pem","name":"My Home"}

The mobile app accepts both formats. The structured format is used when the certificate toggle is enabled.

Connecting a Device​

  1. Install the GEM app using the Download the App section (Android APK) or your App Store / TestFlight link (iOS)
  2. Open the app for the first time
  3. Tap Scan QR Code and point the camera at the code on screen
  4. Or tap the URL field and enter the server address manually
  5. If a certificate is included, tap Install Certificate and follow the on-screen instructions
  6. Tap Connect

The QR code can also be downloaded as an SVG for printing or embedding in documentation.

Connected Clients​

The bottom section shows currently connected clients with push notification subscriptions:

  • Native count: iOS and Android devices with active push tokens
  • Web / PWA count: Browsers with web push subscriptions
  • Client list: Each client shows its platform badge (iOS, Android, or Web), client ID, and last seen time

Push Notifications​

Once connected, the mobile app registers for push notifications automatically. Notifications are delivered via:

  • APNs (iOS) — configured via the apns_config system attribute
  • FCM (Android) — uses a built-in default configuration, or a custom fcm_config system attribute

Push notifications are sent through the same channels as web push notifications, with additional support for:

  • Urgent notifications — bypass Do Not Disturb on Android, show as time-sensitive on iOS
  • Incoming call notifications — trigger the native incoming call UI (see Macros call notification step)
  • Server — SSL / TLS certificate management and cloud tunnel
  • Users — User accounts for mobile app login
  • Notification Profiles — Control which notifications users receive
  • Macros — Call notification macro step
  • Triggers — Call notification trigger action