A recent piece about the New York Times tech team “How to Push a Story” chronicled the lengths they go to make sure that the push notifications they send are relevant, timely, and interesting.

The publishing platform at the NYT lets editors to put notifications through an approval process, measures the tolerance for the frequency of notifications, and tracks whether users un-subscribe from them.

In this article we are going to build a news notification service. It will publish articles from The Guardian - who offer public APIs. We will send push notifications for every news article they publish, and let user users subscribe to their interests so they get notified when news breaks.

Prerequisites

In order to follow along, you will need some experience with the Kotlin programming language, which we are going to use for both the backend and frontend of our application.

You will also need appropriate IDEs. We suggest IntelliJ IDEA and Android Studio. Finally, you will need a free Pusher Account and a free Guardian Open Platform account. Sign up now if you haven’t already done so.

Setting up your Pusher account

In order to use the Push Notifications API and SDKs from Pusher, you need to create a new Beams instance in the Pusher Beta Dashboard.

Next, on your Overview for your Beams instance, click Open Quickstart to add your Firebase Cloud Messaging (FCM) Server Key to the Beams instance.

After saving your FCM key, you can finish the Quickstart wizard by yourself to send your first push notification, or just continue as we’ll cover this below.

It’s important to make sure that you download and keep the google-services.json file from the Firebase Console as we are going to need this later on.

Once you have created your Push Notifications instance, you will also need to note down your “Instance ID” and “Secret Key” from the Pusher Dashboard, found under the “Keys” section of your Instance settings.

Building the backend

The backend of our system is responsible for recognising that a new news story has been published and broadcasting out push notifications about it. We are going to build this in Kotlin using the Spring Boot framework, as this is a very quick way to get going for server-side Kotlin applications. All of the backend work will be done in IntelliJ.

Head over to https://start.spring.io/ to create our project structure. We need to specify that we are building a Gradle project with Kotlin and Spring Boot 2.0.1 (or newer if available at the time of reading), and we need to include the “Web” and “Cache” components:

The Generate Project button will give you a zip file containing our application structure. Unpack this somewhere. At any time, you can execute ./gradlew bootRun to build and start your backend server running.

Note: when you run this, the output will appear to stop at 80%. This is because gradle expects to run to completion, whereas we are starting a long-running application here.

Firstly though, we need to add some dependencies. Open up the build.gradle file and add the following to the dependencies section:

    compile 'com.pusher:push-notifications-server-java:0.9.0'
    runtime 'com.fasterxml.jackson.module:jackson-module-kotlin:2.9.2'

The first of these is the Pusher library needed for triggering push notifications. The second is the Jackson module needed for serialising and deserialising Kotlin classes into JSON.

Now, build the project. This will ensure that all of the dependencies are downloaded and made available and that everything compiles and builds correctly:

    $ ./gradlew build
    
    > Task :test
    2018-04-28 09:47:14.913  INFO 41535 --- [       Thread-5] o.s.w.c.s.GenericWebApplicationContext   : Closing org.springframework.web.context.support.GenericWebApplicationContext@656af5fa: startup date [Sat Apr 28 09:47:13 BST 2018]; root of context hierarchy
    
    
    BUILD SUCCESSFUL in 6s
    5 actionable tasks: 5 executed

Retrieving the list of sections

Our application is going to allow subscription to a number of sections from the news feed provided by The Guardian. This means that we need to offer a list of the sections that can be subscribed to.

In order to do this, we need to create some classes that can represent the response structure from the Guardian API. In this case we are listing sections, so we need to create the following classes under src/main/kotlin/com/pusher/newsbackend:

    data class Section(
            val id: String,
            @JsonProperty("webTitle") val title: String
    )
    
    data class SectionResponse(
            val results: List<Section>
    )
    
    data class SectionPayload(
            val response: SectionResponse
    )

Next we’ll create the start of our component for interacting with the Guardian API. Create a new class called GuardianApi as follows:

    @Component
    open class GuardianApi(
        @Value("\${guardian.apiKey}") private val apiKey: String
    ) {
        private val restTemplate = RestTemplate()
    
        open fun listSections(): List<Section> {
            val uri = UriComponentsBuilder.fromUriString("http://content.guardianapis.com/sections")
                    .queryParam("api-key", apiKey)
                    .build()
                    .toUri()
    
            return restTemplate.getForObject(uri, SectionPayload::class.java)
                    ?.response?.results ?: emptyList()
        }
    }

Calls to the listSections() method will now go and retrieve the full list of sections from The Guardian, as represented by our SectionPayload class, and then return the results list from this class.

Note: The presence of the @Component annotation means that Spring will automatically find this class during Component Scanning and make it available.

Note: Both the class and method are marked as open. This will become important in a short while when we introduce caching.

Next we need a controller to actually make the data available to our clients. Create a new class called SectionController as follows:

    @RestController
    class SectionController(
            private val api: GuardianApi
    ) {
        @RequestMapping("/sections")
        fun getSections() = api.listSections()
    }

The only thing we need now is to configure our API key. Add this to the existing src/main/resources/application.properties file, using the value you obtained earlier by registering with The Guardian Open Platform:

    guardian.apiKey=<GUARDIAN API KEY HERE>

Note: this value should be put in exactly as it was provided, without any quotes or whitespace present.

At this point, we can start our application and retrieve a list of sections by calling our handler.

Caching of sections

One thing to be careful of whenever you work with a third-party API is any usage limits they have. For example, The Guardian restricts you to:

• Up to 12 calls per second
• Up to 5,000 calls per day

We can help alleviate that by reducing the number of calls we make. The list of sections is going to be relatively static, so why not cache it in our application and dramatically reduce the number of calls going out. Spring makes this really easy as we will see.

Firstly we need some Spring configuration. Create a new class called CachingConfig as follows:

    @Configuration
    @EnableCaching
    open class CachingConfig {
        @Bean
        open fun cacheManager() = ConcurrentMapCacheManager("sections")
    }

This enables caching in our application, and creates a cache manager that knows about one cache - “sections”.

Next, add the @Cachable annotation to our listSections() method of the GuardianApi class:

    @Cacheable("sections")
    open fun listSections(): List<Section> {

At this point, we are now caching the calls to The Guardian API. If you make repeated calls to our handler in quick succession - regardless of whether they come from the same client or not - then we will only make a single call out to The Guardian. This will dramatically cut down on our API usage limits.

Publishing events about new articles

Now that we can have clients get the list of article sections, we want to publish events whenever a new article appears on the Guardian’s API. The process for this will be:

• Periodic task to go and do a search of the Guardian’s API, ordered by oldest first and returning everything since the most recent date we’ve seen
• For every article returned, emit a push notification event about the article, with the interest specified as the section ID.

Clients can then register to receive push notifications filtered by the Section ID, and will automatically receive only notifications that they are interested in.

First then, lets build the classes to represent the API response:

    data class ArticleFields(
            val headline: String,
            val trailText: String?,
            val thumbnail: String?
    )
    
    data class Article(
            val id: String,
            @JsonProperty("webUrl") val url: String,
            @JsonProperty("webPublicationDate") val publicationDate: String,
            val fields: ArticleFields,
            val sectionId: String
    )
    
    data class ArticleResponse(
            val results: List<Article>
    )
    
    data class ArticlePayload(
            val response: ArticleResponse
    )

Then we want to be able to actually retrieve the articles. Add the following to GuardianApi:

    open fun listArticles(from: Instant?): List<Article> {
        val uriBuilder = UriComponentsBuilder.fromUriString("http://content.guardianapis.com/search")
                .queryParam("api-key", apiKey)
                .queryParam("rights", "syndicatable")
                .queryParam("page-size", "50")
                .queryParam("show-fields", "headline,trailText,thumbnail")
                .queryParam("order-by", "oldest")
                .queryParam("order-date", "published")
                .queryParam("use-date", "published")
    
        if (from != null) {
            uriBuilder.queryParam("from-date", from.toString())
        }
        val uri = uriBuilder.build().toUri()
    
        return restTemplate.getForObject(uri, ArticlePayload::class.java)
                    ?.response?.results ?: emptyList()
    }

Next we want to be able to send details of articles to Pusher to pass on as push notifications. For this we will create a new ArticleNotifier class as follows:

    @Component
    class ArticleNotifier(
            @Value("\${pusher.instanceId}") private val instanceId: String,
            @Value("\${pusher.secretKey}") private val secretKey: String
    ) {
        private val pusher = PushNotifications(instanceId, secretKey)
    
        fun notify(article: Article) {
            pusher.publish(
                    listOf(article.sectionId.replace("[^A-Za-z0-9-]".toRegex(), "")),
                    mapOf(
                            "fcm" to mapOf(
                                    "data" to mapOf(
                                            "url" to article.url,
                                            "published" to article.publicationDate,
                                            "section" to article.sectionId,
                                            "headline" to article.fields.headline,
                                            "trailText" to article.fields.trailText,
                                            "thumbnail" to article.fields.thumbnail
                                    )
                            )
                    )
            )
        }
    }

We need to change the section ID that we are using for the interest slightly so that it is valid for the Pusher Beams service. An interest can only contain letters, numbers and the characters “_-=@,.:”, whilst some of the section IDs from the Guardian API contain other characters too.

You will also need to add to the application.properties file the credentials needed to access the Pusher API:

    pusher.instanceId=<PUSHER_INSTANCE_ID>
    pusher.secretKey=<PUSHER_SECRET_KEY>

Note: this value should be put in exactly as it was provided, without any quotes or whitespace present.

Finally, a new component to call the Guardian API and retrieve the articles. This simply calls our GuardianApi class, does some manipulation of the results and then calls our ArticleNotifier for each article. Create a new ArticleRetriever class as follows:

    @Component
    class ArticleRetriever(
            private val guardianApi: GuardianApi,
            private val articleNotifier: ArticleNotifier
    ) {
        private var lastDate: Instant? = null
    
        private val lastSeenIds = mutableSetOf<String>()
    
        @Scheduled(fixedDelayString = "PT10S")
        fun retrieveArticles() {
            val articles = guardianApi.listArticles(lastDate)
                    .filter { !lastSeenIds.contains(it.id) }
    
            lastSeenIds.clear()
            lastSeenIds.addAll(articles.map { it.id })
    
            lastDate = articles.map { it.publicationDate }
                    .map(Instant::parse)
                    .sorted()
                    .reversed()
                    .first()
    
            articles.forEach(articleNotifier::notify)
        }
    }

Note here that we have an @Scheduled annotation on our method. Spring will automatically call this method at this delay - here we have 10 seconds purely for the purposes of this article. In reality it would be whatever is appropriate for your needs.

We are also keeping track of the most recently seen publication date - so that next time we can request articles newer than it - and the list of IDs that we have seen on the last pass - because the Guardian API includes articles with the same publication date as specified, so we need to filter them out by hand.

Note: in reality these would be kept in a data store so that they can be persisted between restarts, but for now this is good enough.

Finally, we need to actually enable scheduling. This is done by simply adding the @EnableScheduling annotation to the NewsBackendApplication class:

    @SpringBootApplication
    @EnableScheduling
    class NewsBackendApplication {
    
       static void main(String[] args) {
          SpringApplication.run NewsBackendApplication, args
       }
    }

At this point we can start the application up, and it will periodically go to the Guardian API, retrieve the next 50 articles and send push notifications for them all.

Note: we’re not specifying a start date in our application. It just so happens that The Guardian has news articles going back to November 1805, so there will be plenty of examples for us to test with.

In this application, we are broadcasting out notifications of new stories on a third party site. If we wished, we could actually have a site where we author and publish the articles ourselves and this would work just as well. In that case though, we would be able to broadcast the notifications immediately on the article being published instead of polling the remote site for updates.

Now that our backend is complete, we can start and leave it running whilst we build our UI. For this, we simply execute ./gradlew bootRun or run it from inside IntelliJ.

Building the Android application

The frontend Android application will also be built in Kotlin, using Android Studio. To start, open up Android Studio and create a new project, entering some appropriate details and ensuring that you select the Include Kotlin support option. Note that the Package name must exactly match that specified when you set up the FCM Server Key earlier.

Then on the next screen, ensure that you select support for Phone and Tablet using at least API 16:

Ensure that an Empty Activity is selected:

And leave the Activity Name as “MainActivity”:

Next we need to add some dependencies to our project to support Pusher. Add the following to the project level build.gradle, in the existing dependencies section:

    classpath 'com.google.gms:google-services:3.2.0'

Then add the following to the dependencies section of the app level build.gradle:

    implementation 'com.google.firebase:firebase-messaging:12.0.1'
    implementation 'com.pusher:push-notifications-android:0.10.0'
    
    compile 'com.loopj.android:android-async-http:1.4.9'
    compile 'com.google.code.gson:gson:2.2.4'

And this to bottom of the app level build.gradle:

    apply plugin: 'com.google.gms.google-services'

Next, copy the google-services.json file we downloaded earlier into the app directory under your project. We are now ready to actually develop our specific application using these dependencies.

Finally, we need to add some permissions to our application. Open up the AndroidManifest.xml file and add the following immediately before the <application> tag:

    <uses-permission android:name="android.permission.INTERNET"/>

List of sections

Our primary screen in the UI is simply going to be a list of sections provided by our API. The user will then be able to select which of these they are subscribed to, which will then be managed by receiving push notifications on those stories.

Firstly we need our UI layout. Update app/res/layout/activity_main.xml as follows:

    <?xml version="1.0" encoding="utf-8"?>
    <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:orientation="vertical"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:background="#fff">
        <ScrollView
            android:layout_width="match_parent"
            android:layout_height="wrap_content">
            <LinearLayout
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:orientation="vertical">
    
                <TableLayout
                    android:layout_marginTop="10dp"
                    android:id="@+id/table_layout"
                    android:layout_width="match_parent"
                    android:layout_height="wrap_content">
    
                    <TableRow
                        android:layout_height="wrap_content"
                        android:layout_width="match_parent"
                        android:id="@+id/table_row1"
                        android:padding="10dp">
    
                        <TextView
                            android:id="@+id/selected"
                            android:fontFamily="serif"
                            android:layout_height="wrap_content"
                            android:layout_width="match_parent"
                            android:layout_weight="1"
                            android:textColor="#000"
                            android:text=""/>
                        <TextView
                            android:id="@+id/name"
                            android:textColor="#000"
                            android:fontFamily="serif"
                            android:layout_height="wrap_content"
                            android:layout_width="match_parent"
                            android:layout_weight="3"
                            android:text="Section"/>
    
                    </TableRow>
                    <View
                        android:layout_height="3dip"
                        android:layout_width="match_parent"
                        android:background="#ff0000"/>
                </TableLayout>
    
                <ListView
                    android:id="@+id/records_view"
                    android:layout_width="match_parent"
                    android:layout_height="500dp"
                    android:layout_marginTop="16dp">
                </ListView>
            </LinearLayout>
        </ScrollView>
    </LinearLayout>

Note: in order to paste this snippet in, the Text tab at the bottom of the screen should be selected.

Note: sometimes, copy and paste of the entire file into the Text tab will cause a blank line at the very top. This is invalid XML and needs to be removed.

Now we need a class to represent each entry in this list. Create a new class called SectionEntry as follows:

    data class SectionEntry(
            val id: String,
            val webTitle: String,
            val subscribed: Boolean
    )

You will notice that this is basically the same as the Section class on the backend. This is not surprising because it represents the same data on the same API.

Next we need a layout to represent a single row in our list. For this, create a new layout resource called app/res/layout/section.xml as follows:

    <?xml version="1.0" encoding="utf-8"?>
    <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:orientation="horizontal" android:layout_width="match_parent"
        android:layout_height="match_parent">
        <CheckBox
            android:id="@+id/section_selected"
            android:layout_height="wrap_content"
            android:layout_width="match_parent"
            android:fontFamily="serif"
            android:layout_weight="3"
            android:textColor="#000" />
        <TextView
            android:id="@+id/section_name"
            android:textColor="#000"
            android:fontFamily="serif"
            android:layout_height="wrap_content"
            android:layout_width="match_parent"
            android:layout_weight="1"
            android:text="Name"/>
    </LinearLayout>

This has two entries in it - a checkbox and a section name. We will use the checkbox later on to decide which sections we are subscribed to.

Now we need to be able to render this new layout for each of our sections. For this, create a new class called SectionEntryAdapter as follows:

    class SectionEntryAdapter(private val recordContext: Context) : BaseAdapter() {
        var records: List<SectionEntry> = listOf()
            set(value) {
                field = value
                notifyDataSetChanged()
            }
    
        override fun getView(i: Int, view: View?, viewGroup: ViewGroup): View {
            val theView = if (view == null) {
                val recordInflator = recordContext.getSystemService(Activity.LAYOUT_INFLATER_SERVICE) as LayoutInflater
    
                val theView = recordInflator.inflate(R.layout.section, null)
                val newSectionViewHolder = SectionViewHolder(
                        theView.findViewById(R.id.section_selected),
                        theView.findViewById(R.id.section_name)
                )
                theView.tag = newSectionViewHolder
    
                theView
            } else {
                view
            }
    
            val sectionViewHolder = theView.tag as SectionViewHolder
    
            val section = getItem(i)
            sectionViewHolder.name.text = section.webTitle
            sectionViewHolder.id = section.id
            sectionViewHolder.selected.isChecked = section.subscribed
    
            return theView
        }
    
        override fun getItem(i: Int) = records[i]
    
        override fun getItemId(i: Int) = 1L
    
        override fun getCount() = records.size
    }
    
    data class SectionViewHolder(
            val selected: CheckBox,
            val name: TextView
    ) {
        var id: String? = null
    }

Finally we just need to get the data into this list. Update MainActivity by adding the following field to the class:

    private lateinit var recordAdapter: SectionEntryAdapter

and then initialize this by adding the following to our MainActivity class:

    override fun onResume() {
        super.onResume()
        recordAdapter = SectionEntryAdapter(this)
        val recordsView = findViewById<View>(R.id.records_view) as ListView
        recordsView.setAdapter(recordAdapter)
    
        refreshEventsList()
    }

Next we just need to implement the refreshEventsList method, as follows:

    private fun refreshEventsList() {
        val client = AsyncHttpClient()
        client.get("http://10.0.2.2:8080/sections", object : JsonHttpResponseHandler() {
            override fun onSuccess(statusCode: Int, headers: Array<out Header>, response: JSONArray) {
                super.onSuccess(statusCode, headers, response)
                runOnUiThread {
                    val events = IntRange(0, response.length() - 1)
                            .map { index -> response.getJSONObject(index) }
                            .map { obj ->
                                    val id = obj.getString("id")
                                    SectionEntry(
                                        id = id,
                                        webTitle = obj.getString("webTitle"),
                                        subscribed = false
                                )
                            }
    
                    recordAdapter.records = events
                }
            }
        })
    }

Note: The import for Header should be cz.msebera.android.httpclient.Header

Note: 10.0.2.2. is the IP Address that the host machine appears when running inside the Android emulator. In reality you will want to use the real host of your service.

At this point we can start up the Android application and see all of the sections:

Subscribing to notifications

Now that we have a list of notifications, we want to be able to subscribe to them, and to show the list that we are subscribed to.

Firstly we need to register with the Pusher Beams service. This is done by adding the following to the top of the o``nCreate method in MainActivity:

        PushNotifications.start(getApplicationContext(), "YOUR_INSTANCE_ID");

Next we want to be able to subscribe and unsubscribe to notifications for the sections as we toggle them. For this, add the following to bottom of the getView method of SectionEntryAdapter:

    sectionViewHolder.selected.setOnCheckedChangeListener { _, isChecked ->
        if (isChecked) {
            PushNotifications.subscribe(section.id.replace("[^A-Za-z0-9-]".toRegex(), ""))
        } else {
            PushNotifications.unsubscribe(section.id.replace("[^A-Za-z0-9-]".toRegex(), ""))
        }
    }

We need to update the section IDs that we use in the Pusher Beams subscriptions in the same way that we did in the actual sending of the notifications.

Finally we need to update our checkboxes to show which sections we have previously subscribed to. We only need to do this when loading the list from the server in the first place - any other time the UI is already correctly in sync. For this, add the following to the top of refreshEventsList in MainActivity:

    val subscriptions = PushNotifications.getSubscriptions()

Then we can use it by updating the code lower down in the same method where we are processing the received sections as follows:

    SectionEntry(
            id = id,
            webTitle = obj.getString("webTitle"),
            subscribed = subscriptions.contains(id)
    )

Note: the change here is to give a real value for the subscribed parameter.

Displaying notifications

Now that we can subscribe to notifications on different sections, we need to be able to actually receive and display them. In order to do this, we need to add a listener to PushNotifications for every message received. To do this, add the following to MainActivity:

    fun getBitmapfromUrl(imageUrl: String): Bitmap? {
        return try {
            val url = URL(imageUrl)
            val connection = url.openConnection() as HttpURLConnection
            connection.doInput = true
            connection.connect()
            val input = connection.inputStream
            BitmapFactory.decodeStream(input)
        } catch (e: Exception) {
            null
        }
    }
    
    private fun receiveNotifications() {
    
        val notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
    
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            val channel = NotificationChannel("news",
                    "Pusher News",
                    NotificationManager.IMPORTANCE_DEFAULT)
            notificationManager.createNotificationChannel(channel)
        }
    
        var notificationId = 0
    
        PushNotifications.setOnMessageReceivedListenerForVisibleActivity(this, object : PushNotificationReceivedListener {
            override fun onMessageReceived(remoteMessage: RemoteMessage) {
                Log.v("ReceivedMessage", remoteMessage.data.toString())
                val headline = remoteMessage.data["headline"]
                val url = remoteMessage.data["url"]
                val trailText = remoteMessage.data["trailText"]
                val thumbnail = remoteMessage.data["thumbnail"]
    
                val intent = Intent(Intent.ACTION_VIEW)
                intent.data = Uri.parse(url)
                val pendingIntent = PendingIntent.getActivity(applicationContext, 0, intent, 0)
                
                val notification = NotificationCompat.Builder(applicationContext, "news")
                        .setSmallIcon(R.mipmap.ic_launcher)
                        .setContentTitle(headline)
                        .setContentText(trailText)
                        .setLargeIcon(thumbnail?.let { getBitmapfromUrl(it) })
                        .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
                        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
                        .setContentIntent(pendingIntent)
    
                notificationManager.notify(notificationId++, notification.build())
            }
        });
    }

Note: The import for URL should be java.net.URL, and the import for NotificationCompat should be android.support.v4.app.NotificationCompat

There is quite a lot going on here, so lets break it down a bit. The method getBitmapFromUrl is a little helper that can take a URL, download the Image that it points to and convert it into an Android Bitmap object. The method receiveNotifications will ensure that the NotificationManager is correctly configured for raising notifications, and then will add a listener to PushNotifications to do the bulk of the work.

This listener is called on every single push notification received, and will raise an Android notification for them. This notification will have the headline and trail text from the push notification, the thumbnail displayed as an image if there is one, and clicking on the notification will then load the full news article in the system web browser.

Finally, add a call to onResume to the receiveNotifiactions method so that we can start to receive and display our push notifications:

    override fun onResume() {
        super.onResume()
        recordAdapter = SectionEntryAdapter(this)
        val recordsView = findViewById<View>(R.id.records_view) as ListView
        recordsView.setAdapter(recordAdapter)
    
        refreshEventsList()
        receiveNotifications()
    }

Conclusion

This article has shown how to consume details from a third-party API and broadcast them out to your users by utilizing Pusher Beams.

The full source code for this article is available on GitHub. Why not try extending it to allow multiple news sources to be consumed instead? Or to allow specific searches to be performed?