Veecheck 2.0

If you are currently using an older version of the Veecheck library please read the Changes section.

Veecheck is a small library that can be configured to periodically retrieve a small XML document and issue a Notification based on the current version of the application and the versions listed in the document.

It is designed to be used to notify users when new versions of an application are available.

Licencing

Veecheck is distributed under the Apache Version 2.0 licence with the exception of the source code for the sample application which is public domain. Please consult the terms of this licence before using the software. Previous versions of Veecheck were licensed under the GPL v2 licence

For alternative licencing please email me at tomgibara dot com.

Downloads

Veecheck Jar – the Java classes
Veecheck Source Code – the Java source files
Veecheck Javadocs – documentation generated from the source code
Sample Application – demonstrating how to use the library

Sample Screenshots

The screenshots below are from the Veecheck Sample application.

Settings

Notification

Confirmation

How to use Veecheck

By far the simplest way to start using the Veecheck library, is to download the source code for the sample application and modify it to meet your needs.

Download the jar file.
Add it as a dependency to you Android project.
Create a concrete extension of the VeecheckReceiver class.
Create a concrete extension of the VeecheckService class.
If using the DefaultNotifier class create a concrete extension of the VeecheckActivity class.
Put entries in your AndroidManifest.xml file for these components so that the receiver receives intents with actions <your app package name>.VEECHECK_RESCHEDULE_CHECKS and <your app package name>.VEECHECK_CONSIDER_CHECK and the service receives intents with the action <your app package name>.VEECHECK_PERFORM_CHECK (see the sample application).
Ensure that your application has the android.permission.INTERNET permission.
If using the PrefSettings convenience class, add code to your application that will initialize the settings for your application (see the sample application).
If everything works as planned, your application should be making periodic requests to a server of your choosing. When an intent that is relevant to your application is found within the returned document, an appropriate notification will be generated and displayed to the user.

The "versions" document format

The document that is parsed by this library is an XML document in which:

the namespace is http://www.tomgibara.com/android/veecheck/SCHEMA.1
the attributes are not namespaced
the root element is unimportant, but by convention is <versions>.
all content data (text between elements) is ignored.

The only elements recognized by the parser are:

<version>: This represents a possible version of the application. Each element is, in turn, matched against the version information for the current application. As soon as a match is found an appropriate action is determined and the rest of the document is ignored. Each version element should contain zero or one intent elements. If a version element contains no intent element, this is interpreted as meaning "do not notify the user", otherwise the application may take the opportunity to notify the user that some action should be taken regarding this version of the application.
<intent>: This represents an action that the application should undertake when the user 'activates' a notification. Intent elements should be contained within version elements otherwise they will be ignored.

If no matching version elements are found in the document, the user is not notified.

Version Attributes

The attributes on the version element are used to specify values for the application version to match. Every supplied attribute must exactly match the current application version otherwise the element will be ignored. A version element with no attributes will match any application version.

packageName: The package name of the application.
versionCode: The version code of the application.
versionName: The version name of the application.
buildBrand: The brand associated with the device's build.
buildId: The ID of the device's build.
buildModel: The device model.

Intent Attributes

The attributes on an intent element closely model the key properties of the Android Intent class. There is no requirement that the attributes of this element be mapped directly onto the corresponding Intent properties – this is under the control of the application which uses the veecheck library (though the default VeecheckNotifier implementation does this).

action: A nominal action.
data: A nominal data URI.
type: A nominal content type.
extras: A nominal extras bundle. Bundle properties are declared in this attribute using a similar format to that used by CSS style attributes; a semicolon delimited list of colon separated key/value pairs. Whitespace is automatically trimmed from keys and there is no support for escaping semicolons or colons.

Sample "versions" Documents

Direct users of the application versioned 1.0.0 to a (eg. an upgrade activity)

<versions xmlns="http://www.tomgibara.com/android/veecheck/SCHEMA.1">
  <version versionName="1.0.0" >
    <intent action="com.example.app.ACTION_UPGRADE" />
  </version>
</versions>

Direct the user of any application without version code 4 to a webpage:

<versions xmlns="http://www.tomgibara.com/android/veecheck/SCHEMA.1">
  <version versionCode="4"></version>
  <version>
    <intent
        action="android.intent.action.VIEW"
        data="http://www.example.com/upgrade" type="text/html"
    />
  </version>
</versions>

Use extras to communicate the type and importance of an upgrade:

<versions xmlns="http://www.tomgibara.com/android/veecheck/SCHEMA.1">
  <version versionCode="1">
    <intent extras="importance: urged; type: security" />
  </version>
  <version versionCode="2">
    <intent extras="importance: recommended; type: fixes" />
  </version>
  <version versionCode="3">
    <intent extras="importance: optional; type: cosmetic" />
  </version>
</versions>

Providing upgrade information for more than one application:

<versions xmlns="http://www.tomgibara.com/android/veecheck/SCHEMA.1">
  <version packageName="com.example.app1" versionCode="1">
    <intent ... />
  </version>
  <version packageName="com.example.app2" versionCode="1">
    <intent ... />
  </version>
</versions>

Changes

The first release of Veecheck contained a significant (and rather stupid bug) which causes multiple applications that use the Veecheck library to interfere with each other's update checks. This issue is fixed by this version and it is strongly recommended that applications be upgraded to use this new version.

Changes since 1.0

The actions defined for various broadcast intents are now qualified by the application's package name. This prevents applications receiving intents not intended for them. This was a stupid oversight and I apologize though I did provide the appropriate caveats :-)
The PrefSettings class has changed the name of the check interval preference key (KEY_CHECK_INTERVAL) from "min_period" to "check_interval". Applications wishing to preserve this setting (should it differ from the default) will need to 'copy over' the preference value.
The state modified by the Veecheck library is stored separately from the settings state which now becomes the application exclusive responsibility to set and maintain. This makes for a clearer separation of responsibilities.
A VeecheckActivity has been added to allow users to confirm if they want to proceed with the update. Applications do not need to use such an activity, but a new DefaultNotifier class has been added to make it easy to do so.
Users can now be given the option of ignoring a particular update. This option is provided automatically by the new VeecheckActivity. Note that this is not the same as disabling update checks; the update intent supplied by the versions document is ignored until a different intent is chosen. Note further that for this option to work updates to different versions should have different Intents. In practice this should be easy to achieve.

Notes

This library is has not been extensively tested; it is certain there will be bugs. Please test this software before deploying it as part of your application.
Please heed the advice given about verifying the update intent parameters. This is especially important for applications that have a large number of privileges - by hijacking your versions file, an attacker could exercise control over all the phones on which your application is installed.
There are comments in the source code, use those to get more information.
The SVN repository for this library is hosted at Google Code.
pjv took the time to point out that it may be necessary to use the https scheme if your veecheck document resides on a secure server. For example, this could be done for the SampleService class by adding a call to filter.addDataScheme("https"). If you forget to do this then it can be very difficult to diagnose the problem.