How we built notifications in Congress for iOS

by
iPhone lock screen showing a notification that Sen. Ted Cruz has sponsored four bills

We recently launched a new version of [Congress for iOS](http://cngr.es/ios) with push notifications for the legislators and bills you follow. In user surveys and focus groups we conducted, we heard a consistent pattern in the way people spoke of notifications. Discussion of notifications focused on specific actions around the legislators and bills people had an interest in rather than the intricate details of the legislative process. Our implementation was designed to be simple, but meet the needs of our users.

Notifications are tailored to followed bills and legislators, limiting them to things a user has already indicated an interest in. By using an existing feature of the app, no new toggle or setting is needed to enable notifications on things. The notification settings are designed to encompass the simple types that our users discussed in focus groups, for example:

* Notify me when a bill I follow is voted on. * Notify me when a legislator I follow introduces a bill. * Notify me when a bill is signed into law by the president.

We think these simple choices will help users avoid overly complicated settings or chatty notifications, [which people find annoying](https://twitter.com/search?q=stupid%20notifications&f=realtime). With the service figured out, it was time to write some code.

## Urban Airship

We chose [Urban Airship](http://urbanairship.com) to be our notification provider due to the flexibility of their service and solid reputation. When a user allows Congress push notifications on their device, a unique token is registered with Urban Airship. Along with this token, a list of enabled notification types and followed entities are included as tags (paths that map to our internal app URI scheme). These tags are updated as the user follows and unfollows entities or changes notification settings.

When there is a new notification to send, we craft an audience selector that targets a group of users and pass it on to Urban Airship. To illustrate this, let’s assume H.R. 9999 (/bills/hr9999-113) is signed into law. Our target audience includes users with “A bill I follow is signed into law” (/bill/action) and “Any bill is signed into law” (/bill/signed) notificatons enabled. Given this criteria, the audience selector would look something like:

(/bill/action AND /bills/hr9999-113) OR /bill/signed

With Urban Airship handling the coordination of tags, we can send to subsets of users instead of having to target individual device tokens as recipients. Nice.

So what is this magical service we have that watches for congressional action and generates audience selectors?

## Norrin

[Norrin](https://github.com/sunlightlabs/norrin) is our push notification generator and “dashboard.” It allows us to monitor the current state of notifications and even throw a kill switch if something goes terribly wrong.

a web-based dashboard displaying push notifications and their status

Norrin monitors our [Congress API](https://sunlightlabs.github.io/congress/) for updates to bills and creates the appropriate notifications. The notifications are placed in a queue and then passed through a configurable set of service adapters. We have adapters for sending through Urban Airship, writing to a log file, sending via email, and writing to the console. This allows us to easily add new functionality or reconfigure based on environment (my dev instance does not use the Urban Airship adapter). If we ever need to move away from Urban Airship, heaven forbid, we’ll just need to write an adapter for the new service.

Failed notifications are marked as such and can be resent once we fix whatever caused the error. If something goes haywire and we throw the kill switch, new notifications are marked as stalled and can be manually sent once we turn the system on again.

In the few months that I’ve been testing them, push notifications have proven to be a great way to stay passively informed of congressional activity that interests me. I hope you’ll find them useful too.

[![Congress for iOS on the App Store](http://cngr.es.s3.amazonaws.com/ios/appstore.png)](http://cngr.es/ios)

[Congress for iOS](http://cngr.es/ios) is available in the App Store. Give it a try! We’d love to hear your feedback and appreciate all App Store rating and reviews. Also available for [Android](http://cngr.es/android).