When developing an application, it’s very helpful to use the push and pull replication in continuous mode. Everything is handled by the replicators to make sure your app and Sync Gateway always have the latest documents synced.

However, a continuous pull replication means that Couchbase Lite will be using techniques such as long polling or web sockets to check if there’s new data to fetch from Sync Gateway. This can have an impact on battery life and consequently user experience.

In this post, we will explore an alternative to continuous pull replication by using Google Cloud Messaging, Android’s push notification service.

You can check out a working example in ToDoLite Android. Let’s see how you can include GCM syncing in your application!

Enabling GCM in your app

First, let’s configure ToDoLite Android to register for Google Cloud Messaging. We’ll create a new Google API project on the developer console. Follow this guide to set it up. You should have a project number and API key. Now we can update the project’s AndroidManifest.xml with the required permissions, intent filter and service. It should look like this:

Note: Check out the example from the android developer site as well.

If the project is configured correctly, we can retrieve the device token with the project number we got when creating the app in the google developer console. Add a method in the Main Activity to retrieve the device token from GCM and save it on the user profile document for example:

Note: Device tokens on Android always start with APA91 so keep an eye out for them in LogCat 😉

Next, we have to add some code to handle an incoming notification. We subclassed the WakefulBroadcastReceiver class where the onReceive method gets called every time we receive a notification.

From there, the wakeful service kicks off the GcmMessageHandler class and performs a one-shot pull replication. The wakeful service executes even if your app is running in the background. Then your app would show the new data accordingly when opening the app.

Notice we’re using the replication change listener to get notified when it’s done and to shut down the wakeful service.

That’s all we have to do on the Android side to handle the sync notification.

Saving the device tokens

Now we can store the device token on the user profile document. Each user may be logged into more than one device at a time so we should store each one of them. The user document will look like this:

In the next section, we’ll talk about adding additional application logic to Sync Gateway using the Changes Feed.

The Sync Gateway Changes Feed

The /database/changes endpoint returns a sorted list of changes made to documents in the database. This endpoint is part of the CouchDB spec and both the Couchbase Lite Listener and Sync Gateway implement it.

It’s very easy to hook into the Changes Feed of Sync Gateway to add extra logic to the back-end such as, in our case, sending push notifications.

You can use any library that implements the changes feed api:

Out of all the parameters available in the query string, the most important ones in our case are:

  • feed=continuous to ensure that we get changes immediately
  • since=now to get the changes from the current time, otherwise it will log all changes since the database was created!

Finally, let’s focus on the the last piece of the puzzle: given a document change from the changes feed, we need to get the user profile documents “interested” in that change because they hold the device tokens.

Changes Feed → GCM

In ToDoLite, there are 3 types of documents: a profile, a list and a task. The task document holds a reference to the list it belongs to and a list has an owner and a members array.

When a task document or a list document changes we’d like to notify the owner and members of that list. There are two types of events we’d like to handle:

1. A list document change event:

  • get the profile document of the owner
  • get the profile document for each member

2. A task document change event:

  • get the list document it belongs to
  • follow the same steps as 1)

With the device tokens retrieved, the last step is to send a request to Google Cloud Messaging servers with our API Key and notification payload. You can also find many libraries on GitHub that make it simple to interact with the GCM servers:

Wrap up

Using Google Cloud Messaging to trigger data fetching from the server side can provide a great user experience without any additional battery and network usage overhead.

Follow the readme instructions to run the ToDoLite demo.

I would love to know how you are using Google Cloud Messaging notifications in your app. Let me know in the comments below!

More reading:

Posted by James Nocentini, Technical Writer, Mobile, Couchbase

James Nocentini is the Technical Writer in charge of the documentation for Couchbase Mobile. Previously, he worked as a Developer Advocate and before that as a front-end developer for HouseTrip. He also enjoys writing Android tutorials for raywenderlich.com in his spare time.


  1. A tiny pool of experienced and reliable mobile app development companies
    in Los Angeles
    makes it next to impossible for a common web surfer to
    find a suitable app development company. Finding an app developer in Los Angeles
    with an ability and willingness to work on complex projects within the
    constraints of time and budget can be achieved by following these simple steps.

  2. rajveer solanki February 5, 2016 at 8:50 am

    \”I like what you guys are usually up too. Such clever work and coverage! Keep up the wonderful works guys I\’ve added you guys to blogroll. \”

    If you love gaming for unity games kindly visit….

    mobile app & game development

  3. I go through this article, it is nice and informative. As a marketing tool push notification has playing a huge role. Today through push company can easily promote their brand to customers and expand their market easily. Today i want to introduce Pushify brand. It support Chrome and Firefox. By GCM the push will be deliver to customer Mobile and Desktop, without any App. It also providing Geo-Targeting, Scheduled Notifications, Free Plugins, Unlimited REST API calls,RSS 2 Push and many more free features. To know more the Edition\’s provide by Pushify, you have to visit- http://www.pushify.com

  4. Google

    That will be the finish of this post. Here you’ll discover some web-sites that we feel you will enjoy, just click the hyperlinks.

  5. lefkoşa kirakık ev fiyatları

    […]always a big fan of linking to bloggers that I really like but do not get a great deal of link adore from[…]

  6. Rukyah

    […]Here is a good Blog You might Locate Intriguing that we Encourage You[…]

  7. sportovni podprsenky

    […]although sites we backlink to beneath are considerably not associated to ours, we really feel they may be actually really worth a go by way of, so have a look[…]

  8. snuff bottles

    […]below you’ll uncover the link to some websites that we assume you ought to visit[…]

  9. global franchise

    […]Sites of interest we have a link to[…]

  10. unique antiques

    […]Here are a number of the web sites we advocate for our visitors[…]

  11. adam and eve sex toys

    […]Here is an excellent Blog You might Discover Intriguing that we Encourage You[…]

  12. cheap cock rings

    […]we like to honor many other net web pages on the web, even though they aren’t linked to us, by linking to them. Under are some webpages really worth checking out[…]

  13. butterfly sex toys

    […]although sites we backlink to beneath are considerably not connected to ours, we really feel they’re basically worth a go by, so possess a look[…]

  14. sex toys cleaner

    […]that is the finish of this write-up. Right here you’ll uncover some websites that we assume you will appreciate, just click the hyperlinks over[…]

  15. discount sex toys

    […]below you will come across the link to some web pages that we assume you should visit[…]

  16. adam & eve sex toys

    […]below you’ll find the link to some sites that we assume you should visit[…]

  17. bullet sex toy

    […]always a major fan of linking to bloggers that I enjoy but really don’t get a great deal of link really like from[…]

  18. rampant rabbit sex toys

    […]Wonderful story, reckoned we could combine a few unrelated information, nonetheless really really worth taking a appear, whoa did one discover about Mid East has got a lot more problerms also […]

  19. Google

    Here is a superb Weblog You may Obtain Interesting that we encourage you to visit.

  20. surfboard for hire huntington beach

    […]one of our guests lately recommended the following website[…]

Leave a reply