Abrova

Make your Flutter web app installable on iPhone and Android

At the end: a Flutter web app people add to the Home Screen, with a launch screen, iPhone splash images, an offline page, an install guide and a prompt for new versions.
Abrova PushFlutter webBeginner · 20 min

Before you start

Flutter web appabrova_webApp on the Home Screen

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.

Why install it.

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:

yaml
# pubspec.yaml
dependencies:
  abrova_web:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.5.4

Then install:

bash
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:

bash
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 in web/index.html (this needs Google Chrome; --no-splash skips them);
  • web/offline.html, added to web/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:

dart
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 openWhat people see
iPhone or iPad, SafariShare › Add to Home Screen › open from the icon, with look-alikes of the iPhone controls
Android browserAn Install button (the browser’s install prompt), or the menu steps
Inside Instagram, Facebook or another appOpen 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 buildNothing

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:

dart
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:

dart
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:

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:

bash
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#

  1. 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.
  2. On Android, open it in Chrome: the guide shows an Install button.
  3. Open the link inside Instagram: the guide asks to open it in the browser, with Copy link.
  4. Turn on flight mode and open the installed app: the offline page shows. Turn the network back on: the app reloads.
  5. 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.

Pitfalls
  • 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)