By Tom Reznik, on May 29, 2015

Vault: an Android library for content sync

Vault is a new addition to our Android developer tool set. This post is written for the developers of Android apps, and it describes how Vault simplifies syncing content between a mobile device and Contentful.

Content sync in mobile apps

Synchronizing content between the server and local device storage greatly improves the user experience in mobile applications. In addition to making the content available in offline mode and improving loading times, it reduces data consumption and battery usage.

Contentful provides a Sync API, which enables delta content updates. This endpoint delivers only new and changed content and notifies the client(s) about deleted content.

Vault: a library for syncing content in Android apps

We've decided to further simplify developing Contentful-powered Android apps. Meet Vault: an Android library that simplifies persistence of data from Contentful via SQLite. It enables defining Java representations for your existing Contentful models. On the compilation step Vault creates a corresponding database schema by generating all the required boilerplate code and injecting it into the classpath.

Vault is bundled with a complementary lightweight runtime which exposes a simple ORM-like API for pulling resources from the generated database.

Usage

First add the dependencies to the project (assuming that you use Gradle for the builds):

Replace VERSION with the latest version of Vault, which you can find on the GitHub repository.

Configuration

Have a look at the Cat content type of the official demo space: Cat Content Type

The models are defined by declaring a subclass of the Resource class. Annotate the class with @ContentType, which takes the content type ID as the value.

Notice that fields are defined by annotating class attributes with the @Field annotation, which by default uses the name of the attribute as the field ID, but can also be specified explicitly:

The spaces can be defined by declaring a class annotated with the @Space annotation, which requires the space ID and an array of model classes:

Arrays of resources are also supported:

And so is the embedded JSON type:

Synchronization

At runtime Vault should be used with a pre-configured CDAClient:

Calling requestSync() will spawn a worker thread that fetches content via the Sync API to synchronize the remote state with its database. Once the sync is complete, a broadcast with the action Vault.ACTION_SYNC_COMPLETE will be fired. This should only be done if you want to refresh the state from the server, because the locally cached data is available without it.

Alternatively you can provide a SyncCallback which will be invoked once the sync is complete, but make sure to cancel it according to its host lifecycle events:

Queries

Vault provides a wrapper around the databases it generates, which can be easily used to pull persisted resources. Here are some examples:

Summary

Vault helps Android developers to save time on syncing content between local storage and the server: instead of writing lots of boilerplate code, in particular to represent the remote content model locally, they can now just include the library in the project and have proper models and syncing available at once. Vault is open source and available on GitHub. If you need help in setting this up, let us know, our customer success team is happy to assist you.

Tom Reznik

Former android developer at Contentful. You can follow Tom on Twitter.