Today Extensions Tutorial: Getting Started

Learn how to create a today extension in iOS 8!

Learn how to create a today extension in iOS 8!

Note from Ray: This is an abbreviated version of a chapter from iOS 8 by Tutorials released as part of the iOS 8 Feast to give you a sneak peek of what’s inside the book. We hope you enjoy!

iOS 8 introduces a new concept called App Extensions: a way for you to share your app’s functionality with other apps, with to the OS itself.

One of these types of extensions are Today Extensions, also known as Widgets. These allow you to present information in the Notification Center, which can be a great way to provide immediate and up-to-date information that the user is interested in.

In this tutorial, you’ll write a Today Extension that renders the current market price of a Bitcoin based on the United States Dollar.

Never has it been so easy to deliver valuable information so quickly to your users. Let’s get started!

Introducing Bitcoin

If you’re not familiar with Bitcoin, the short explanation is that it’s a digital cryptocurrency that’s still in its infancy. Aside from using it for peer-to-peer exchanges and purchases, Bitcoin trading allows the user to exchange it for a number of other cryptocurrencies like Dogecoin and Litecoin, and flat currency such as the US Dollar and the Euro.

As a relatively new currency, its market value fluctuates by the minute; there have been huge peaks and troughs in its short lifetime. Thus, it’s a perfect candidate for a Today Extension since investors will want up-to-the-second price quotes!

Introducing Crypticker

Since you’re writing an extension, you’ll first need a host app to extend; meet Crypticker.

Crypticker is a simple app that displays the current Bitcoin price, the difference between yesterdays price and the current price, as well as a price history chart. The chart includes 30 days of history; sliding your finger on the chart reveals the exact price for a specific day in the past.

The extension will contain all of these features, except for touching the chart to see the price for a specific day. There are some limitations within Today Extensions, especially when it comes to swiping. The swipe gesture often triggers swiping between the Today and Notifications sections within Notification Center, so it doesn’t really provide the best or most reliable user experience.

Getting Started

Download the Crypticker starter project to get started. The project contains the entire Crypticker app as described above. This tutorial will not focus on the development of the container app, so you may be pleasantly surprised to find this tutorial to be rather succinct. After all, you’re writing an extension, not an entire app.

Build and run. Please note that you’ll need a working Internet connection to pull the real-time prices from a web service.

The app looks very similar to the screenshot above; the data displayed will, of course, depend on how the Bitcoin market looks right now. Touching the chart near the bottom of the view will draw a line and display the price for the relevant day.

BTC widget

For the unfamiliar, BTC is shorthand for Bitcoin; much like USD stands for United States Dollar. The Today Extension will render a scaled down version of Crypticker’s primary view.

Theoretically, the Crypticker app has the ability to show pricing for multiple Cryptocurrencies, but your extension is specific to BTC. Therefore, its name shall be BTC Widget.

Note: Extensions, by nature, have just one simple purpose. If you wanted to provide information for another cryptocurrency, like Dogecoin, it would be best to package a second widget with the app or design your UI appropriately, perhaps like the Stocks widget.

By the end of the tutorial, your Today Extension will look something like this:

Extensions are packaged as a separate binary from their host app. So you’ll need to add a Today Extension target to the Crypticker project.

In Xcode’s Project Navigator, select the Crypticker project and add a new target by selecting Editor\Add Target… When the template picker appears, choose iOS\ Application Extension, and then Today Extension. Click Next.

Set the Product Name to BTC Widget, and verify that the language is Swift, the project is Crypticker and Embed in Application is also Crypticker. Click Finish.

When prompted activate the BTC Widget scheme. As the text indicates, another Xcode scheme will be created for you.

Congratulations! BTC Widget will now appear in your list of targets.

Make sure you select BTC Widget, then the General tab, and then press the + button under Linked Frameworks and Libraries.

Select CryptoCurrencyKit.framework and click Add.

CryptoCurrencyKit is a custom framework used by the Crypticker app to retrieve currency prices from the web. Luckily for you, the incredibly kind and thoughtful developer behind Crypticker modularized the code into a framework, so that it can be shared between multiple targets :]

In order to share code between a host app and its extensions you must use a custom framework. If you don’t, you’ll find yourself duplicating a lot of code and violating an important rule of software engineering: DRY – or, Don’t Repeat Yourself. I’ll say it again: “Don’t repeat yourself”.

At this point, you’re ready to begin implementing the extension.

Notice there’s now a group in the Project navigator named after your new target, BTC Widget. This is where the Today Extension’s code is grouped, by default.

Expand the group and you’ll see there is a view controller, a storyboard file and an Info.plist file. Its target configuration also tells it to load its interface from MainInterface.storyboard, which contains a single view controller with the class set to TodayViewController.swift.

You’ll notice some files you might expect to see are missing from the Today Extension template; like an app delegate for instance. Remember that extensions run inside another host app, so they don’t go through the traditional app lifecycle.

In essence, the lifecycle of the extension is mapped to the lifecycle of the TodayViewController.

Open MainInterface.storyboard. You’ll see a dark colored view with a light Hello World label. Today Extensions are most legible when they have a clear background and light or vibrantly colored text in order to harmonize with the dark, blurred background of Notification Center.

Make sure the BTC Widget scheme is selected in Xcode’s toolbar and build and run. This will cause a window to appear asking which app to run. Xcode is asking you which host app to run. Choose Today. This tells iOS to open Notification Center in the Today view, which in turn launches your widget. Notification Center is effectively the host app for Today Extensions.

This also causes Xcode to attach its debugger to the widget’s process.

Behold your widget. Cool, right? Whilst this is super-exciting stuff, the widget clearly needs a little work. It’s time to make it do some interesting things!

Note: You might notice a lot of Auto Layout errors printed to the console when launching the widget. This is an issue with the Xcode template, and will hopefully be resolved by Apple in the future. Don’t worry though, since you’ll be adding your own interface, including Auto Layout constraints.