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
  • Local failover — an app set up with the External URL probes the LAN path while disconnected and switches to it when the controller answers there, then back to the external path when it leaves the site, keeping the same session. Before it moves to the external path it checks that the controller itself answers through the cloud proxy, not merely that the proxy is listening. An app set up with the Internal URL never switches on its own

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 the release 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.

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 the App Store link, the bundled APK if available, and one setup code per configured server address: External (the cloud URL, for phones that leave the building) and Internal (the local network URL, for devices that stay on site). Each card shows the address it encodes so the person can pick the path that fits the device. A site with neither URL configured in Server settings gets a single setup code for the address the page was loaded from.

Home Screen Shortcut (Web App)​

If you don't want the full native app, GEM can be added to a phone's home screen as a web app (PWA). The shortcut opens full-screen without browser chrome, uses the GEM icon and name, and receives web push notifications through the browser.

iOS (Safari):

  1. Open the server URL in Safari
  2. Tap the Share button (square with an arrow)
  3. Scroll down and tap Add to Home Screen
  4. Tap Add

Android (Chrome):

  1. Open the server URL in Chrome
  2. Tap the ⋮ menu in the top-right corner
  3. Tap Add to Home screen (shown as Install app on some versions)
  4. Confirm with Add / Install

Chrome may also show its own install banner at the bottom of the page — tapping it does the same thing.

What the home screen shortcut does not provide compared to the native app:

  • Native push via APNs / FCM — web push works, but on iOS it requires iOS 16.4+ and the shortcut must be launched from the home screen (Safari tabs don't receive push)
  • Incoming call UI for gate and intercom alerts
  • Certificate auto-install from the setup QR code
warning

Web push and full-screen install require a secure context — HTTPS with a certificate the device trusts. If the server uses a self-signed or private CA certificate, install it first (see Certificate Auto-Install); over plain HTTP the shortcut still works but behaves like a browser bookmark.

Server URL​

The server URL is the address the mobile app uses to connect to your GEM server. Pick its source:

  • External URL: resolves live from the External URL in Server settings — the right choice for apps that roam off-site (connected apps discover the Internal URL on their own and fail over to it automatically when the external path is unreachable on the local network)
  • Internal URL: resolves live from the Internal URL in Server settings (explicit value or auto-detected LAN address) — for devices that never leave the site. An app set up this way never fails over to the external path on its own; while the controller restarts it simply waits for it to come back
  • Custom: a hand-entered URL for exotic setups; stored in the mobile_app_url system attribute
  • Click Save to persist the choice — the resolved URL is embedded in the setup QR code

Existing installations that saved a URL before the source picker existed keep working unchanged (they load as Custom).

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.

To point an already-connected device at a different GEM server later, use the Change GEM Url button in the UI selector's toolbar — the app clears its stored server URL and returns to this setup screen.

Connected Clients​

The bottom section shows clients with a live connection to the server right now — read from the server's socket registry, so it never lists stale sessions:

  • Native count: iOS and Android app installs, identified by their native push registration
  • Web / PWA count: Browsers and home-screen web apps, with or without a push subscription
  • Client list: Each client shows its platform badge (iOS, Android, or Web), client ID, the address it is currently loaded from, and last seen time. The client ID is a link — it opens that one row on the Clients page, where its full history, user and session details live

The platform and address come from the client itself — the page asks every live client where it is running when it loads. A client that does not answer (an old page still open from before an update) shows no response; reload it and refresh the list.

Push Server URL to Connected Apps​

Installed apps keep the server URL they were set up with and boot to it on every launch. When that address turns out to be the wrong one — panels that never leave the building were set up with the external cloud URL, or the site moves to a new hostname — the section under the client list moves them without touching each device:

  1. Choose the address in the Server URL section above (External, Internal, or Custom). The push always sends the URL shown there.
  2. Tick the apps to move. Native apps whose current address differs from the chosen URL are pre-selected; browsers and web apps cannot be pushed and are not selectable.
  3. Click Push & Reload. Each app saves the URL as its startup address and reloads there. The session travels with it, so a logged-in panel comes back logged in.

Each app checks that it can reach the new address from its own network before it saves anything. A device that cannot reach it answers unreachable from this device and stays exactly where it was, so a typo or a LAN-only address pushed to a phone on cellular never strands the app on its setup screen.

The result for every app is shown inline. A few seconds after a successful push the list reloads and the moved apps reappear under their new address.

Only a connected app can be moved

The push travels over the app's live connection to this server. An app sitting on a sign-in page in front of the server — the GEM Cloud sign-in when the external URL goes through the cloud proxy — is not connected to GEM yet and cannot be reached. Sign in on that device first; once the GEM interface has loaded, it appears in the list and can be pushed.

Panels that never leave the building

Set in-house iPads and wall panels to the Internal URL. Through the cloud proxy every connection counts as remote, which means the full username and password sign-in instead of the PIN keypad, and a cloud sign-in page whenever that session expires. On the internal address they are local clients again, and they stay there: an app set up with the internal address never switches to the external one by itself, not even while the controller restarts.

Push Notifications​

Once connected, the mobile app registers for push notifications automatically. Delivery works out of the box with no per-server configuration:

  • Default (relay) — the server sends a signed push request to the GEM push relay, which holds the APNs (iOS) and FCM (Android) credentials and performs the actual send. No push keys live on the controller.
  • Bring your own — a site that prefers to send directly with its own developer credentials can set the apns_config (iOS) and/or fcm_config (Android) system attribute; when present, that platform is sent locally and bypasses the relay. Each platform is independent — you can override one and relay the other.

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)
Android registration requires a current APK

On Android the app registers for push from the native shell, which hands the FCM token to the web client after it loads. APKs built before this path existed never registered — the device appears in Connected Clients with an Android badge but receives no push. Reinstall from the current bundled APK to fix it; no server-side change is needed. The same native bridge stores the failover session, so an outdated APK also loses its session when the app switches between the LAN and external paths.

  • 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