PWA setup
GCM is a Progressive Web App, which means members and staff can install it to their phone or desktop home screen and run it like a native app — full-screen, with an icon, even with offline support on Growth+ plans. The PWA App page (sidebar → PWA App) is where you tell the browser what the installed app should look and behave like.
Open the PWA page
Click PWA App in the sidebar. The page has five cards, top to bottom: App Identity, App Icon, Theme, Display Mode, Push Notifications, and Install App.
App identity
These three fields populate the PWA manifest, which the browser reads when offering "Install app".
App name
The full app name shown on the install prompt and (on some platforms) under the home-screen icon. Defaults to your organization's name. Keep it under 45 characters or it gets truncated on Android.
Short name
The shorter version used when there isn't room for the full name — usually under the home-screen icon on iOS and Android. Defaults to the first word of your org name. Aim for 12 characters or fewer.
Description
A one-paragraph description of what the app does. Shown in some browsers' install dialogs. Optional but helps members understand what they're installing.
App icon
Two sizes are required: 192×192 and 512×512. Both should be PNGs (JPEG and WebP are also accepted but PNG renders most reliably across launchers).
Upload steps:
- Click Upload under the size you want to set.
- Pick a square image. The file is uploaded to your org's
pwa-iconsstorage bucket and the manifest URL is updated immediately — no separate save step for icons. - Repeat for the other size.
TIP
Use the same design at both sizes — don't try to fit more detail into 512 just because there's more room. Launchers display these at radically different sizes (the 192 might render at 48px, the 512 at 256px), so a single clean design that scales is what you want.
File limits:
- Max size: 2 MB per icon.
- Accepted:
image/png,image/jpeg,image/webp.
If you upload the wrong-shape image, the launcher centres it on a coloured background (your theme colour) — so a circular logo on a square white background works fine, but a horizontal logo gets letterboxed.
Theme
Two colours control the manifest's theme_color and background_color.
Theme color
The colour the OS uses for the status bar (on Android) and the title bar (on installed desktop windows). Pick something that matches your brand primary — many churches just paste the same hex code they used in Branding → Colors.
Background color
The colour shown during the brief moment between tapping the home-screen icon and the app's first render. If a member sees a white flash on every cold start and it bothers you, set the background colour to your primary so the flash is on-brand.
Both fields accept a hex code and have a colour-picker swatch. The values save into app_settings under pwa_theme_color / pwa_background_color.
Display mode
How the installed app looks when launched. Three options:
| Mode | Behavior |
|---|---|
| Standalone (default) | Looks like a native app — no browser chrome, your icon in the title bar. Best for most orgs. |
| Fullscreen | True fullscreen — no status bar even. Useful for kiosk check-in tablets. |
| Minimal UI | Keeps a thin browser-style URL bar at the top. Useful if members frequently need to copy URLs from inside the app. |
For 99% of orgs, Standalone is the right pick. Change only if you have a specific reason.
Push notifications
Toggle Enable push on if you want the app to send web-push notifications to installed devices (Android and desktop — iOS supports push only on iOS 16.4+ installed PWAs).
When enabled:
- The first time a member opens the installed app, they're prompted to allow notifications.
- Workflow nodes and reminders can target Push as a channel.
- The
vapid_public_keyfield shows your org's public VAPID key (read-only) — push providers use this to authenticate subscriptions.
WARNING
The VAPID key pair is generated server-side the first time push is enabled. It's tied to your org permanently — if you ever rotate it, every installed device has to re-subscribe (members get re-prompted). Don't rotate unless you have to.
Install app
The last card shows the install button itself. If your browser supports beforeinstallprompt, the button is enabled and you can install GCM as an app right from this screen.
If the browser doesn't support the programmatic prompt (Safari on iOS doesn't), the card shows manual instructions instead — typically "tap Share, then Add to Home Screen" for iOS, or "open the browser menu and select Install app" for desktop Chrome.
Once installed, the card detects standalone mode and shows "App is already installed on this device" with a green checkmark — useful for confirming the install worked before you walk a member through it.
What's saved where
All PWA settings go into app_settings with pwa_* keys:
pwa_app_name,pwa_short_name,pwa_descriptionpwa_icon_192,pwa_icon_512(storage URLs)pwa_theme_color,pwa_background_colorpwa_display_modepwa_push_enabledvapid_public_key(read-only, generated server-side)
The frontend reads these on app startup and writes them into /manifest.webmanifest so the browser sees the right values without an extra round trip.
Updating an installed app
PWAs auto-update on the next launch when a new build deploys. Members don't see an update prompt — the new code just runs the next time they open the app. If you've changed the icon, members may need to remove and reinstall to see the new icon on their home screen (the launcher caches it).
Common pitfalls
"My icon looks fuzzy on iOS." iOS requires the 512×512 specifically. If only 192 is set, iOS scales it up and it blurs. Always upload both sizes.
"Push notifications never arrive." Two things to check: (1) push is enabled here, AND (2) the recipient's installed app has been opened at least once on the target device with notifications allowed. Push subscriptions are per-device-per-browser — installing on phone doesn't give your laptop push.
"I changed the theme colour and the status bar didn't update." The OS reads the theme colour at install time and caches it. Reinstall the app on the affected device to pick up the new colour, or wait for the next browser-driven manifest refresh (which can take days).