Building an iOS App That Syncs in the Background with Couchbase Mobile

A few months ago James Nocentini, an evangelist on the Couchbase Mobile team, talked about creating an iOS app that syncs Hacker News articles in the background for online/offline access with Couchbase Mobile. Here, in his own words, he talks about how to do it (full source code included):

Introduction

In this article, you will learn how to use Sync Gateway and Couchbase Lite to sync the Hacker News latest stories to an iOS app.

We'll focus specifically on the Background Fetch feature that was added in iOS 7: applications can now perform small operations in the background to fetch the latest data from the server. If your app has registered for Background Fetch, the operating system will periodically wake up your application to perform a refresh and the maximum time allocated in one Background Fetch is 30 seconds.

That's a perfect use case for a one-shot pull replication. So let's get started!

The source code for this tutorial is on GitHub.

Working with Sync Gateway

The first step is to set up Sync Gateway. Download the latest community edition here. Let's use a very simple configuration for this example. In a new file called config.json paste the following:

{
  "log": ["CRUD", "REST+", "Access"],
  "databases": {
    "hackernews": {
      "server": "walrus:",
      "users": {
        "GUEST": {"disabled": false, "admin_channels": ["*"]}
      }
    }
  }
}

The important point to note is that we are using the walrus database which saves documents in memory. With walrus, documents are not persisted when restarting Sync Gateway. Secondly, we have enabled the GUEST account and gave it access to all channels. You can add access control and user management logic but for this example we'll develop without restrictions which is often a good way to prototype.

Now let's start it from the command line with this config file:

$ ~/Downloads/sync_gateway/bin/sync_gateway config.json

Starting the iOS app

I've setup the Xcode project with Cocoapods to manage dependencies, run pod install to be sure to have the CouchbaseLite framework linked to the project. Open HackerNewsSync+BackgroundFetch.xcworkspace in Xcode and run the app on the simulator.

You should see an empty table view:

Indeed, we must first add some Hacker News stories to Sync Gateway.

Hacker News top stories

Let's use the NodeJS script in worker.js to fetch top stories from the Hacker News API. We'll use Mashape for that. Grab a Mashape Key from here and paste it in the worker.js file in place of XXXX-XXXX-XXXX-XXXX.

Install the dependencies by running npm install and start the worker:

$ node worker.js

It will fetch top stories from the Hacker News API and save 5 of them to Sync Gateway. There's no need to process the data, we just pipe the response straight to the admin port of Sync Gateway which will create a new document for each top story.

Trigger a Background Fetch

To trigger a background fetch we can use the Debug > Simulate Background Fetch option in Xcode:

This will send your app to the background and call the application:performFetchWithCompletionHandler: method, notice that we kick off a pull replication and register a change event listener to close the background fetch operation when the status of the replication has finished (kCBLReplicationStopped). Open the app and you will see the table view already populated:

Using background fetch in your application can greatly improve the user experience and speed perceived by users.