Android library for handling app update notifications
Java
Clone or download
Latest commit e0caf64 Mar 6, 2018

README.md

Prince of Versions

CircleCI Download

Library checks for updates using configuration from some resource.

Getting via jcenter

compile 'co.infinum:prince-of-versions:latest_version'

Features

  • Load update configuration from network resource or from input stream resource
  • Accept custom loader for loading update configuration resource
  • Use predefined parser for parsing update configuration in JSON format
  • Accept custom parser for parsing update configuration
  • Make asynchronous loading and use callback for notifying result
  • Loading and verifying versions happen outside of UI thread
  • Use thread pool to cap concurrent resource usage.
  • Provide functionality for canceling once started verifications

Default parser and JSON file

If you are using a default parser, version in your application and the JSON file has to follow Semantic Versioning. JSON file has to look like this:

{
	"ios": {
		"minimum_version": "1.2.3",
		"latest_version": {
			"version": "2.4.5",
			"notification_type": "ALWAYS",
		}
	},
	"android": {
		"minimum_version": "1.2.3",
		"minimum_version_min_sdk": 15,
		"latest_version": {
			"version": "2.4.5",
			"notification_type": "ONCE",
			"min_sdk":18
		}
	},
	"meta": {
		"key1": "value1",
		"key2": "value2"
	}
}

Depending on notification_type property, the user can be notified ONCE or ALWAYS. The library handles this for you, and if notification type is set to ONCE, it will notify you via onNewUpdate(String version, boolean isMandatory) method only once. Every other time the library will return onNoUpdate for that specific version. Key-value pairs under "meta" key are optional metadata of which any amount can be sent accompanying the required fields.

The library supports min sdk version. If defined, it will show a new update only if user's device is supported.

minumum_version_min_sdk represents the minSdk value of the minimum supported version of the application. min_sdk represents minSdk value of the latest version of the application. Fields minimum_version_min_sdk and min_sdk are optional fields thus not including them makes no difference to the library implementation whatsoever.

Examples

Full example application is available here.

Most common usage - loading from network resource

  1. Create new instance of updater associated with application context.
PrinceOfVersions updater = new PrinceOfVersions(this);
  1. Create loader factory for loading from network passing resource URL.
LoaderFactory loaderFactory = new NetworkLoaderFactory("http://pastebin.com/raw/41N8stUD");
  1. Create concrete callback for result implementing co.infinum.princeofversions.callbacks.UpdaterCallback interface.
UpdaterCallback callback = new UpdaterCallback() {
		@Override
		public void onNewUpdate(String version, boolean isMandatory, Map<String, String> metadata) {
		}

		@Override
		public void onNoUpdate(Map<String, String> metadata) {
		}

		@Override
		public void onError(@ErrorCode int error) {
		}
};
  1. Use updater with previously created loader factory and callback. Call checkForUpdates method to start update check.
UpdaterResult result = updater.checkForUpdates(loaderFactory, callback);
  1. To cancel update check, call cancel method on UpdaterResult object.

Writing tests

For testing purposes you can create your own LoaderFactory. For ease of use, StreamLoader object exists in the library. Here is an example of loading a JSON file from raw.

  1. Create new instance of updater associated with application context.
PrinceOfVersions updater = new PrinceOfVersions(this);
  1. Create loader factory for creating stream loader by passing new input stream in its constructor.
LoaderFactory loaderFactory = new LoaderFactory() {
		@Override
	        public UpdateConfigLoader newInstance() {
	              return new StreamLoader(getResources().openRawResource(R.raw.update));
	        }
};

Note: Be aware that once used input stream in StreamLoader is read and closed. For that purpose always create new stream in newInstance method of LoaderFactory.

3rd, 4th and 5th step are same as in previous example.

Writing tests using minSdk value

All the steps are the same just like writing tests without minSdk values. The only and single difference in writing tests with minSdk values is the PrinceOfVersions object, to be more precise, it's constructor's arguments.

PrinceOfVersions updater = new PrinceOfVersions(context, provider, repository, sdkVersionProvider);

Since we've added the support for minSdk values of the device you can mock and customize them when writing tests by using the interface SdkVersionProvider.

When creating a PrinceOfVersions object a few things need to be kept in mind:

  • context argument in PrinceOfVersions constructor can be mocked using Mockito library.

  • provider argument in PrinceOfVersions constructor can be mocked using Mockito library.

provider = Mockito.mock(VersionVerifierFactory.class);

and it's used for creating a new instance of specific VersionVerifier and it has a single method that provides a new instance of VersionVerifier which is used for verifying updates and cancellation of verification.

  • repository argument is used for representing repository which persists library data and is also mocked with Mockito library.
repository = Mockito.mock(VersionRepository.class);
  • And finally, sdkVersionProvider is an abstraction used to fetch Build.Version.SDK_INT value. In order to use sdkVersionProvider in tests you need to create a custom mock class which will accept a mock integer which represents the minSdkValue you wish to use in your test, e.g.
public class SdkVersionProviderMock implements SdkVersionProvider {

    private int sdkInt;

    public SdkVersionProviderMock(int sdkInt) {
        this.sdkInt = sdkInt;
    }

    @Override
    public int getSdkInt() {
        return sdkInt;
    }
}

Multiple flavors

If your application has multiple product flavors (e.g. paid/free) you might need more than one JSON configuration file. If that is the case, do not forget to set a different URL for each flavor configuration.

Deploying a new version

  1. Bump libraryVersion in build.gradle
  2. ./gradlew clean build generatePomFileForMavenPublication bintrayUpload -PbintrayUser=<bintray username> -PbintrayKey=<bintray api key> -PdryRun=false
  3. Add a new entry in the CHANGELOG

Contributing

Feedback and code contributions are very much welcome. Just make a pull request with a short description of your changes. By making contributions to this project you give permission for your code to be used under the same license.