Skip to content

levin-riegner/app_versioning

Repository files navigation

App Versioning

Keep track of app versions and prompt users to update the app whenever there are new updates available.

Overview

This packages provides a simple yet customisable way to suggest or force updates to Android & iOS apps. Built on top of the in_app_update package for Android and upgrader for iOS.

The package also leverages the version_tracker plugin to track the app versions accross updates.

Features

  • Retrieve information about available updates from the Play Store or App Store.
  • Version bomb. Force users to update the app if the update is mandatory by configuring a minimum version using your custom Backend or Firebase Remote Config.
  • Launch Android updates using the native In-App Updates flows, supporting flexible and immediate updates.
  • Request iOS updates by redirecting the user to the App Store.
  • Track version update history and launches to trigger onboarding flows, database migrations, and more.

Get Started

View the example project for a complete working example.

Installation

Add the following dependency to your pubspec.yaml file:

dependencies:
  app_versioning: latest

Initializing

  1. Initialize the AppVersioning class with your app's identifiers and minimum version provider. You can use one of the following factories or create your own implementation of the AppVersioning interface:

    • Use the apiService factory to retrieve the versioning from your backend.
    final appVersioning = AppVersioning.apiService(
        apiConfig: ApiConfig(
            endpoints: ApiVersioningEndpoints(
            "https://api.example.org",
            minimumVersioningEndpoint: "api/api-compatibility",
            ),
        ),
        updateConfig: UpdateConfig(
            appStoreAppId: "1234567890",
            playStoreAppId: "org.example.versioning",
            appstoreCountryCode: "US",
        ),
        );
    • Use the firebaseService factory to retrieve the versioning from Firebase Remote Config.
    final appVersioning = AppVersioning.firebaseService(
      remoteConfigKeys: const RemoteConfigKeys(
        minimumIosVersionKey: "minimumIosVersion",
        minimumAndroidVersionKey: "minimumAndroidVersion",
      ),
      updateConfig: const UpdateConfig(
        appStoreAppId: "1234567890",
        playStoreAppId: "org.example.versioning",
        appstoreCountryCode: 'US',
      ),
    );
  2. Track the current version when the app is launched.

    await appVersioning.tracker.track();
  3. Check whether a new update is available.

    final appUpdateInfo = await appVersioning.getAppUpdateInfo();
  4. If an update is available, prompt the user to update the app using your own UI elements.

    if (appUpdateInfo.isUpdateAvailable) {
      switch (appUpdateInfo.updateType) {
        case AppUpdateType.Optional:
          _showUpdatePopup(forceUpdate: false);
          break;
        case AppUpdateType.Mandatory:
          _showUpdatePopup(forceUpdate: true);
          break;
      }
    }
  5. If the user accepts the update, or the update is mandatory, launch the update flow.

    appVersioning.launchUpdate(updateInBackground: true);

Backend Services

Apps using a version below the minimum version will be forced to update with a mandatory update type. This plugin currently supports 2 different backends to set the minimum version supported on the app.

  1. API: An arbitrary URL endpoint that returns the minimum versions JSON.
  2. Firebase Remote Config: Key/value pairs with the minimum versions specified on Firebase.

    This requires the project to include and set up Firebase separately. You can import the configuration using the remote_config.json file.

Contributing

Check the CONTRIBUTING.md guide for more information.

Deployment

  1. Set the new version on the pubspec.yaml version field.
  2. Update the CHANGELOG.md file documenting the changes.
  3. Update the README.md file if necessary.
  4. Run dart pub publish --dry-run to ensure the package can be published successfully.
  5. Create a new tag with the release version git tag -a x.y.z -m "x.y.z" && git push --tags.
  6. Navigate to GitHub Releases and create a new release for the previously created tag, including the CHANGELOG.md changes.
  7. Finally run dart pub publish to deploy the project.

Credits

License

This repo is covered under the MIT License.