Veecheck 1.0

A newer version of Veecheck is available.

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 GPL v2 licence. Please consult the terms of this licence before using the software.

For alternative licencing please email me at tomgibara dot com.

Downloads

How to use Veecheck

  1. Download the jar file.
  2. Add it as a dependency to you Android project.
  3. Create a concrete extension of the VeecheckReceiver class.
  4. Create a concrete extension of the VeecheckService class.
  5. Put entries in your AndroidManifest.xml file for these components so that the receiver receives intents with actions com.tomgibara.android.veecheck.RESCHEDULE_CHECKS and com.tomgibara.android.veecheck.CONSIDER_CHECK and the service receives intents with the action com.tomgibara.android.veecheck.PERFORM_CHECK (see the sample application).
  6. Ensure that your application has the android.permission.INTERNET permission.
  7. If using the PrefSettings convenience class, add code to your application that will initialize the settings for your application (see the sample application).
  8. 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 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.

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>

Notes