Android library for handling app update notifications
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.circleci Update build tools to 27 Mar 6, 2018
config Update checkstyle Mar 6, 2018
prince-of-versions Update build tools to 27 Mar 6, 2018
.gitignore .gitignore Jul 26, 2016 Modify changelog Feb 15, 2017
LICENCE Update Mar 17, 2017
build.gradle Update build tools to 27 Mar 6, 2018 Renaming Jul 26, 2016
gradlew.bat Renaming Jul 26, 2016
settings.gradle Renamed module and added sources task Aug 31, 2016

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'


  • 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",
	"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.


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("");
  1. Create concrete callback for result implementing co.infinum.princeofversions.callbacks.UpdaterCallback interface.
UpdaterCallback callback = new UpdaterCallback() {
		public void onNewUpdate(String version, boolean isMandatory, Map<String, String> metadata) {

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

		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() {
	        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;

    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


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.