Skip to the page
Beck Links

Force update

Force update

Require or offer an app update by version, per platform, with a Flutter package.

Force update lets you tell old versions of your app to update: versions below a minimum must update before they can be used, and versions below the latest are offered an update. You set the versions in the dashboard; the app asks Beck Links with its platform and version and gets ok, update_available or update_required.

The Flutter package becklinks_force_update does the asking and draws the screens. It works on its own: it needs no deep links and no other Beck Links package. If you build the screens yourself or use another framework, the REST endpoint is all there is to it.

Get it: becklinks_force_update on pub.dev

Set the policy#

  1. Open the dashboard, your project, Settings.
  2. Under Environments, find Force update for the environment you use (Test or Live). Android and iOS have their own policy.
  3. Enter the minimum version (older versions must update), the latest version (older versions are offered an update), and the store URL of your app: an https address of its Google Play or App Store page.
  4. Optionally add a title and a message; the app shows them on its update screen.
  5. Turn the platform on and select Save. A change reaches apps within a minute.

A platform that is on needs a version and a store URL, and the minimum cannot be higher than the latest. A platform that is off tells every version it is fine.

Versions are compared as releases: 2.1 equals 2.1.0, 2.10.0 is newer than 2.9.0, and a build suffix (2.1.0+45) or pre-release tag (2.1.0-beta.1) is ignored.

Install the Flutter package#

Bash
flutter pub add becklinks_force_update

Put the gate above your navigator so its screens cover every page:

Dart
import 'package:becklinks_force_update/becklinks_force_update.dart';
import 'package:flutter/material.dart';

final forceUpdate = BeckLinksForceUpdate(apiKey: 'pk_live_YOUR_KEY');

void main() => runApp(
      MaterialApp(
        builder: (context, child) => ForceUpdateGate(
          forceUpdate: forceUpdate,
          child: child ?? const SizedBox.shrink(),
        ),
        home: const HomeScreen(),
      ),
    );

The gate checks when the app starts and each time it returns to the foreground (at most once a minute). A required update shows a screen that cannot be left, with an Update button to your store page; an available update shows a dismissible offer. Translate the built-in words with texts: ForceUpdateTexts(...), or draw your own screens with requiredBuilder and availableBuilder.

To decide yourself, call check() and read the result (isRequired, isAvailable, storeUrl, title, message).

Use the publishable key (pk_test_… or pk_live_…). A secret key is refused.

Safe by design#

  • It fails open. If the check cannot be made (no network, a damaged setting, a version the server cannot read), the app is told it is fine. The one exception: an update that was already required for this exact version stays required while the phone is offline.
  • It is anonymous. The request holds the platform and the app version, and no device or user identifier. Nothing is stored about the person.
  • Test before you require. Use the Test environment with a pk_test_… key first; a wrong live minimum locks every older user out until you correct it.

The endpoint#

Any client can call the same endpoint with a publishable key:

Bash
curl -X POST https://api.becklinks.com/v1/sdk/app-version \
  -H "Authorization: Bearer $PUBLISHABLE_KEY" \
  -H "X-SDK-Name: my_client" \
  -H "X-SDK-Version: 1.0.0" \
  -H "Content-Type: application/json" \
  -d '{"platform": "android", "app_version": "1.9.0"}'
JSON
{
  "status": "update_required",
  "minimum_version": "2.0.0",
  "latest_version": "2.3.0",
  "store_url": "https://play.google.com/store/apps/details?id=com.acme.shop",
  "title": "Please update",
  "message": "This version is no longer supported."
}

store_url, title and message are null when status is ok. The policy itself is part of the environment settings (force_update) in the REST API.

Verify it works#

  1. In the Test environment, set the Android policy: minimum 99.0.0, latest 99.0.0, your Play Store URL, on, Save.
  2. Run a debug build with a pk_test_… key. The update screen covers the app and Update opens the store page.
  3. Set the minimum to 0.0.1 and the latest to 99.0.0: the app shows the dismissible offer instead.
  4. Turn the platform off (or set both to 0.0.1) and restart the app: no screen appears. Then switch your phone to airplane mode and start the app once more: it opens normally.