User Profile Sample: Background App Refresh

Configure your iOS app for Background Fetch support

Setup your app to do a one-shot sync with Couchbase Sync Gateway while in the background

You must have completed the "user profile" tutorial on sync. If you haven’t already done so, please complete the following tutorial first

iOS (Xcode 11+)

git (Optional) This is required if you would prefer to pull the source code from GitHub repo.

curl HTTP client

Allows users to log in and create or update his/her user profile information. The user profile view is automatically updated everytime the profile information changes in the underlying database

The user profile information is synced with a remote Sync Gateway which then syncs it 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

Open the "capabilities" tab in the UserProfileDemo.xcodeproj file. Note that "Background Fetch" is enabled under the "Background models" tab

Open the AppDelegate.swift file and locate the application:didFinishLaunchingWithOptions() function.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.
    self.loadLoginViewController()
UIApplication.shared.setMinimumBackgroundFetchInterval(UIApplicationBackgroundFetchIntervalMinimum)
    return true
}

Here we specify the periodicity at which the app should be woken up. We use a value of UIApplicationBackgroundFetchIntervalMinimum which is the smallest fetch interval supported by the system

Open the AppDelegate.swift file and locate the application:performFetchWithCompletionHandler() function. This callback function is invoked by the system everything the app is launched in the background.

// Support for background fetch
func application( _ application: UIApplication,
                  performFetchWithCompletionHandler
    completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    print(#function)
    
    // Do a one shot replication
    self.cbMgr.startOneShotPullReplicationForCurrentUser { (status) in
        completionHandler(.newData) (1)
        
    }
    
}

Open the DatabaseManager.swift file and locate the startOneShotPullReplicationForCurrentUser() function.

func startOneShotPullReplicationForCurrentUser(completionHandler:@escaping(_ doneStatus:Bool)->Void) {

Let’s examine the replicator configuration

let dbUrl = remoteUrl.appendingPathComponent(kDBName)
let config = ReplicatorConfiguration.init(database: db, target: URLEndpoint.init(url:dbUrl))
config.continuous =  false (1)
config.replicatorType = .pull (2)
config.authenticator =  BasicAuthenticator(username: user, password: password) 

The app must be running in the simulator with the xcode debugger attached. This is important as we will use the xcode debugger for simulating background fetches.

Push the app in the simulator to the background. Typically you can do it with the Shift-Cmd-H key combination

Clear the debug console logs in xcode. This will make it easier to identify what goes on when the app is launched in the background

Open the command terminal and issue the following curl command to get the user profile document on the Sync Gateway via GET Document REST API

curl -X GET \
  http://localhost:4985/userprofile/user::demo@example.com \
  -H 'Accept: application/json' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json'

Your response should look something like the response below. The exact contents depends on the user profile that you provided via your mobile app.

{
  "_attachments": {
    "blob_/image": {
      "content_type": "image/jpeg",
      "digest": "sha1-9OHO0QIk+kREiOaoMlrEg/jU4zU=",
      "length": 15110,
      "revpos": 1,
      "stub": true
    }
  },
  "_id": "user::demo@example.com",
  "_rev": "1-0b9e3efa5ec1b1596564c4db34ba28d4e618f9c5",
  "address": "",
  "email": "demo@example.com",
  "image": {
    "@type": "blob",
    "content_type": "image/jpeg",
    "digest": "sha1-9OHO0QIk+kREiOaoMlrEg/jU4zU=",
    "length": 15110
  },
  "name": "",
  "type": "user"
}

In the command terminal, issue the following command to update the user profile document on the Sync Gateway via PUT Document REST API

curl -X PUT \
  'http://localhost:4985/userprofile/user::demo@example.com?rev=1-0b9e3efa5ec1b1596564c4db34ba28d4e618f9c5' \
  -H 'Accept: application/json' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "address": "101 Main Street",
  "email": "demo@example.com",
  "image": {
    "@type": "blob",
    "content_type": "image/jpeg",
    "digest": "sha1-S8asPSgzA+F+fp8/2DdIy4K+0U8=",
    "length": 14989
  },
  "name": "priya Rajagopal",
  "type": "user",
  "university": "British Institute in Paris, University of London"
}'

Launch the iOS app in the background. You will simulate this through the Xcode Debug menu to "Simulate Background Fetch"

Observe the console logs. You would see a set of messages indicating that the app has pulled the latest changes from the Sync Gateway

Stop the Sync Gateway

Launch the app in the foreground. The user profile doc that was synced in the background will be displayed.