One of the key features of Couchbase Mobile data platform is the ability to sync data across the Couchbase Lite enabled mobile clients and the Sync Gateway. The ability to run apps in the background is typical in the mobile application life cycle on iOS, Android and .Net platforms and has several uses, for instance, to reduce initial sync/startup costs by ensuring that the app is launched with the latest data.

In this post, we will introduce you to a simple tutorial that discusses how you can use iOS Background App Refresh capability to sync data when in the background. While the tutorial itself is iOS specific, concepts discussed here apply to all of the supported Couchbase Lite platforms.


Every mobile platform has its own implementation of app backgrounding. In some instances, they may even vary with version of the OS. For instance, among the various options, you have Background Services on Android, Background App Refresh on iOS and Background Tasks on UWP apps . For these reasons, with some exceptions, backgrounding support is an app level concern and is not built into Couchbase Lite. In other words, the mobile app will have to support the platform’s built-in backgrounding capability and then invoke Couchbase Mobile’s data sync capabilities whenever it gets the opportunity to execute in the background.

It is to be noted that on some platforms, the system uses its discretion to terminate the app when it is in the background. Hence, there are no guarantees that the app will even have an opportunity to run in the background.

Backgrounding Options in iOS

Background Task

Everytime the app is pushed into the background, Couchbase Lite will use the iOS Background Task capability to wrap up ongoing sync before going into idle mode. With the Background Task capability, the system provides the app with a finite amount of time to run in the background to perform critical tasks before suspending it.

Silent Notifications

In this mode, your backend system can be configured to send out silent push notifications to your apps whenever there is data available to be synced by the clients. Silent push notifications are like regular push notifications except that the end user is not notified. Instead, your app is notified and given the oppportunity to handle the notification. When your app is woken up in this mode, it can do a one-shot replication to sync and pending changes with the remote server.

Background App Refresh

Background App Refresh lets your app run periodically in the background so that it can update its content. Over time, the system learns the usage of your app , will wake up your app at appropriate times and give it some finite amount of time to execute. When your app is woken up in this mode, it can do a one-shot replication to sync and pending changes with the remote server.



The tutorial introduced in this post uses Background App Refresh mode and is available here. In this tutorial, you will learn how to –

  • Configure your iOS app for Background App Refresh support
  • Setup your app to do a one-shot sync with Couchbase Sync Gateway while in the background

We will be usiing a Swift App as an example of a Couchbase Lite enabled client.

App Overview

We will be working with a simple “User Profile” app which we introduced in the Fundamentals Tutorial and extended to support data sync capabilities in the Sync Tutorial. In the tutorial, we will be extending that app to support data sync when in the background.
The app does the following
– Allows users to log in and create or update his/her user profile information. The user profile view automatically updates every time the profile information changes in the underlying database
– The user profile information syncs with a remote Sync Gateway which then syncs it over to other devices (subject to access control and routing configurations specified in the sync function)
– When the app is woken up in the background, it does a one-shot replication with the remote Sync Gateway

Next Steps

At the end of the tutorial, you should have an understanding of how to sync between your Couchbase Lite enabled iOS apps and Sync Gateway while your app is in the backhround. While we discussed one background mode, you can apply it to Silent Notifications. The concepts apply to other platforms as well.

If you have questions or feedback, please leave a comment below or feel free to reach out to me at Twitter @rajagp or email me at The Couchbase Forums are another good place to reach out with questions.



Posted by Priya Rajagopal, Senior Director, Product Management

Priya Rajagopal is a Senior Director of Product Management at Couchbase responsible for developer platforms for the cloud and the edge. She has been professionally developing software for over 20 years in several technical and product leadership positions, with 10+ years focused on mobile technologies. As a TISPAN IPTV standards delegate, she was a key contributor to the IPTV standards specifications. She has 22 patents in the areas of networking and platform security.

Leave a reply