ResearchKit Tutorial with Swift: Getting Started

Learn how to make a medical research app with this ResearchKit tutorial for iOS. By Matt Luedke.

Leave a rating/review
Save for later


In April 2015, Apple enacted its vision to advance medical research by sharing ResearchKit, a new open source framework which includes all the elements you need to create an app for a medical study. Within moments, your study can be available to millions of potential test subjects who have a powerful iOS device with them at all times!

And since the main competitors of ResearchKit in the study-recruitment space are the tabbed fliers posted in cafés and on college bulletin boards, Apple is well-poised to make a significant impact in the area of large-scale research studies.

But you can share in this opportunity and build your own research app — and even to contribute to ResearchKit itself!

This ResearchKit tutorial will show you how to verify user consent, collect qualitative and quantitative information with a survey, and use an active task to record audio clips with the iPhone microphone.

But first, a few points about what ResearchKit is and isn’t:

  • It is a tool for research studies, not for medical treatment itself.
  • It does help you easily obtain user consent, but does not replace HIPAA or IRB approval. You are responsible for ensuring your app follows all applicable laws. Note that Apple’s Review Guideline 27.10 specifically requires you obtain IRB approval.
  • It does help you collect data, but does not provide mechanisms for getting this data to your secure server.
  • It uses data from public HealthKit and CoreMotion APIs, but does not collect background sensor data directly.
Note: For more info on HealthKit integration, see HealthKit Tutorial with Swift: Getting Started

Getting Started

This tutorial’s sample app, Camelot, simulates a research study delving into the following question: “Does one’s name, quest, or favorite color affect vocal chord variations?” Just to keep things simple, the airspeed velocity of an unladen swallow is assumed to be a constant in this case. :]

To begin, create a new project in Xcode using File\New\Project and choose Single View Application. Name the product Camelot, select Swift for the language, and choose iPhone for the device as shown below:

Create a Swift project

Next, you’ll need to include ResearchKit in your project. If you prefer to use a dependency manager such as CocoaPods or Carthage, you can follow the directions for these tools in the ResearchKit docs and bypass the rest of this section.

Note: Need an introduction to CocoaPods? Take a look at the Introduction to CocoaPods Tutorial on this site.

To proceed without a dependency manager, simply clone or download ResearchKit on GitHub. This specific commit was used when writing this tutorial – if you’re having problems, you may wish to use that version rather than the latest content of the master branch.

The repository includes the following:

  • The ResearchKit core framework, including modules contributed by Apple and other developers.
  • A sample project entitled ORKCatalog.
  • Documentation for the framework and for the module types.

Drag ResearchKit.xcodeproj from Finder into your Xcode project. Your Project Navigator should now look like this:

Project structure

Next, select Camelot.xcodeproj in the Project Navigator, choose the Camelot target and the General tab, and then click +under Embedded Binaries, shown below:


Finally, select ResearchKit.framework and click Add:


ResearchKit is now included in your project and ready for use. To make sure it’s been included correctly, add the following import to the top of ViewController.swift:

import ResearchKit

Build your project; if your build succeeds, you’re ready to start using the ResearchKit framework!


Informed Consent

A crucial piece of a medical research study is the consent of the test subject. This is an ethical mandate that dates all the way back to the Hippocratic Oath over two thousand years ago; this mandate has been supplemented with modern laws that may vary among the regions where your app is available.

It’s your job to make sure your study obtains consent in a legal manner, and the Consent Module included in ResearchKit is a great place to start as you can spell out the goals and requirements of the study in a series of views with simple, engaging animations.

To begin, create a new, empty Swift file named ConsentDocument.swift, then add to it the following code:

import ResearchKit

public var ConsentDocument: ORKConsentDocument {
  let consentDocument = ORKConsentDocument()
  consentDocument.title = "Example Consent"
  //TODO: consent sections
  //TODO: signature
  return consentDocument

Here, you’ve created an ORKConsentDocument, ResearchKit’s representation of the informed consent document for your study. Think of it as the stack of papers on the clipboard handed to you when you arrive at the lab, ready for your signature at the bottom of each page.


Consent Document Contents

The first thing you’ll need to do is define the series of steps you need to spell out the ways this study might impact the user. In ConsentDocument.swift, replace //TODO: consent sections with the following code:

let consentSectionTypes: [ORKConsentSectionType] = [

An ORKConsentSectionType is an enum that designates a pre-fab page that covers part of the consent document. You’ve simply defined an array of these enums you’ll use when creating consent sections for displaying the various pages.

Note: If you order the ORKConsentSectionType array in the specific order given above, the pages will automatically have smooth, animated transitions as the user navigates forward. They look quite fancy, if you ask me! :]

These sections are only recommended, though, not mandatory. If your study doesn’t need any or all of these sections, you can remove them as required, or use one of the following options for ORKConsentSectionType:

  • .Custom: These sections have no default content, so you can add anything you need with text, images, or HTML.
  • .OnlyInDocument: These sections aren’t displayed to the user, but their contents are included in the summary document for the user’s approval.

Now that you’ve identified the section types to use, you need to create them and give them some content.

Add the following code just below the spot where you defined consentSectionTypes:

var consentSections: [ORKConsentSection] = { contentSectionType in
  let consentSection = ORKConsentSection(type: contentSectionType)
  consentSection.summary = "If you wish to complete this study..."
  consentSection.content = "In this study you will be asked five (wait, no, three!) questions. You will also have your voice recorded for ten seconds."
  return consentSection

consentDocument.sections = consentSections

Here you iterate through the consentSectionTypes array and create an ORKConsentSection for each type. These sections correspond to pages in the consent form. Each section has a default image based on the type, which you can change by setting the customImage property.

The textual content is set by the summary and content properties which provide the title and text for each section. In a real app, you’d definitely use different text on each page, according to its purpose. But for this tutorial, you can simply add the same summary and content to each section.

Matt Luedke


Matt Luedke


Over 300 content creators. Join our team.