Make your Flutter web app installable on iPhone and Android
Before you start
- A Flutter app with a web build (web/manifest.json with its name, background_color and icons)
- Abrova Push for Flutter web (its worker at the root of the site)
- Google Chrome on your computer, for the iPhone splash images
In this guide you turn a Flutter web app into one people add to the Home Screen of their phone and open like any other app. One package, abrova_web, does the work: a command writes the launch screen, the iPhone and iPad splash images and the offline page, one widget shows people how to install the app wherever they opened it, and two more tell them when a new version is out.
On iPhone, Web Push works only in an app added to the Home Screen. An installed app also opens from its own icon, with its own launch screen.
Step 1: Add the package from Abrova Center#
The package comes from Abrova Center. Add it with the Abrova registry as its hosted source:
# pubspec.yaml
dependencies:
abrova_web:
hosted: https://center.abrova.ir/api/packages/abrova/pub
version: ^0.5.4Then install:
flutter pub get
Step 2: Launch screen, splash images and offline page#
The offline page is served by the Abrova Push worker at the root of your site (AbrovaPushConfig(webPush: true, webPushAtRoot: true)), so set that up first (Flutter Web Push), then run the setup:
dart run abrova_push:web_push_setup --root dart run abrova_web:setup --accent "#1C72C8"
It reads your app's name, background_color and icons from web/manifest.json (--accent is the glow, loading bar and button colour) and writes:
- the launch screen in
web/index.html, shown until your app draws its first frame; - the iPhone and iPad splash images in
web/splash/and their tags inweb/index.html(this needs Google Chrome;--no-splashskips them); web/offline.html, added toweb/abrova-push-sw.js.
Tapping the icon on the Home Screen now shows the splash image at once, then the launch screen with a loading bar until the app appears. Opened with no network, the app shows "You're offline" with a Try again button, and reloads by itself once the connection is back. The offline page works once the app has been opened online with push started.
Run both commands again after upgrading abrova_push, and when your manifest or icons change. Details: Launch screen and offline page.
Step 3: Show the install guide#
Put AbrovaInstallGuide where people see it, for example at the top of the home page:
import 'package:abrova_web/abrova_web.dart';
AbrovaInstallGuide(appName: 'Lino', icon: Image.asset('assets/icon.png'))It shows only what is needed where the app is open:
| Where the app is open | What people see |
|---|---|
| iPhone or iPad, Safari | Share › Add to Home Screen › open from the icon, with look-alikes of the iPhone controls |
| Android browser | An Install button (the browser’s install prompt), or the menu steps |
| Inside Instagram, Facebook or another app | Open it in the browser, with Copy link |
| Installed | “It’s on your home screen” once, on the first start from the Home Screen; then nothing |
| On a computer, or a native build | Nothing |
Its texts are in Persian for a fa locale and English otherwise; pass strings: for your own. "Not now" hides it for 7 days (dismissDays).
To decide yourself, read where the app runs:
final where = AbrovaWeb.context; where.installed; // opened from the Home Screen where.installNeed; // none, iosAddToHomeScreen, androidInstall, openInBrowser where.inAppBrowser; // 'Instagram', … or null
Ask for notifications once where.installed is true. Details: Install guide (web).
Step 4: Tell people about new versions#
Start the update check in main, cover the app with AbrovaUpdateGate for required updates, and show AbrovaUpdatePrompt where people look:
import 'package:abrova_web/abrova_web.dart';
void main() {
AbrovaWebUpdates.start();
runApp(MaterialApp(
builder: (context, child) => AbrovaUpdateGate(child: child!),
home: const HomePage(),
));
}
// For example at the top of the home page:
AbrovaUpdatePrompt(icon: Image.asset('assets/icon.png'))After each deploy the prompt shows "New version available" with Reload and Later. It checks when the app opens, when it comes back to the front, and every 10 minutes.
When an old version must stop, add web/update.json:
{ "minimum": "0.6.0", "notes": { "en": "Faster sign-in.", "fa": "ورود سریعتر." } }A page running a version older than minimum is covered by AbrovaUpdateGate until it reloads, with notes shown as "What's new". Details: New versions (web).
Step 5: Build and deploy#
Build with the engine files inside your build, and give each deploy its own build number:
flutter build web --release --no-web-resources-cdn --build-number=13
--no-web-resources-cdn puts Flutter's engine files (CanvasKit) in build/web, so the app loads them from your own site instead of Google's servers. The build number lets open pages see the new deploy: when only the build changed, the prompt shows "Version 0.5.1 (build 13)".
Upload the whole build/web folder to the root of your site, as you deploy it today. abrova-push-sw.js must stay at the root, next to index.html.
Step 6: Check that it worked#
- On an iPhone, open the app in Safari: the install guide shows the Share › Add to Home Screen steps. Add it, then open it from the icon: the splash image and launch screen show, and instead of the steps the guide shows “It’s on your home screen” once.
- On Android, open it in Chrome: the guide shows an Install button.
- Open the link inside Instagram: the guide asks to open it in the browser, with Copy link.
- Turn on flight mode and open the installed app: the offline page shows. Turn the network back on: the app reloads.
- Deploy again with
--build-number=14: the open app shows "New version available".
Troubleshooting#
Offline page not served: no web/abrova-push-sw.js
Run dart run abrova_push:web_push_setup --root first, then dart run abrova_web:setup again.
Splash images skipped
The setup needs Google Chrome to draw them (set CHROME to its path if it is not found) and an icon file in web/manifest.json.
No update prompt after a deploy
Call AbrovaWebUpdates.start() in main, and build each deploy with a new --build-number.
- On iPhone, Web Push works only in the app added to the Home Screen: ask for notifications once AbrovaWeb.context.installed is true.
- The offline page is served by web/abrova-push-sw.js: run abrova_push:web_push_setup --root before abrova_web:setup, and both again after upgrading abrova_push or changing the manifest or icons.
- Without a new --build-number, open pages don’t see a deploy that kept the same version.
Where next: Install guide (web)