Build a research and care app, part 1: Setup onboarding
Learn how ResearchKit and CareKit can work together to take the tedium out of paper surveys. Code along with us and build a working care pilot app. Explore best practices for onboarding and consent with ResearchKit, and find out how your app can require participants to sign consent documents by leveraging CareKit's store and UI components.
This is the first session in a three-part Code-Along series. To get the most out of this series, we recommend that you have some basic familiarity with both ResearchKit and CareKit. For more background, watch "ResearchKit and CareKit Reimagined” from WWDC19.
♪ Bass music playing ♪ ♪ Erik Hornberger: Good afternoon, everyone, and thank you for joining us today. We’ve got some great content planned out for you. We’re going to walk through a code-along where you and I will build out a research and care app together. ResearchKit is an open source iOS framework that Apple maintains in collaboration with our GitHub community. It provides UI elements for gathering consent, administering surveys, and recording sensor data while participants perform activities, such as physical or cognitive exercises. CareKit, likewise, is also a fully open source framework, and it’s designed to help with building out patient-facing care apps. It excels at scheduling tasks that you want patients to perform, like taking medications or calling their doctor. It also provides a secure persistence layer for health-related data and has utilities for charting. Now, in past WWDC sessions, we’ve often discussed these two sibling frameworks in isolation, but this year we’re going to show you how they can be used together to create even better experiences for patients... Sorry. Should we just -- I should have had it on silent. Do we cut? Crew: No, just answer it.
Erik: Yo, Jamie. What's up? Jamie: Hey, Erik. I know you’re busy prepping for WWDC right now, but I wanted to tell you that funding just came through for our physical therapy study app! This cutting-edge research is going to help so many people! So, do you think we can get a first rev of the app out, like, right away? Erik: Hey, Jamie, that is -- that is awesome news, and I'm -- I'm really excited about it. The thing is we're just very much in the middle of our- of our Dub Dub code-along. Jamie: Oh, so you're coding already? That's perfect! So, the app is going to be called "Recover." It’s going to be a physical therapy app to help participants strengthen their knees following surgery, and it’s going to be a game changer! I’ve got tons of great ideas, but first, it’s really important that participants consent to participating in the study before we let them start using the app. We’ve got to explain to them all the legalese, but I really want to do it in a way that isn’t intimidating, you know? We’ll also need to get a signature from participants and have them agree to share data with us as well. Uh, one sec, Erik. I’m getting a message from the clinical team. Oh, wow. It looks like the first participants will be released from post-op on Monday. Erik, can you just get started with onboarding for now? I have to catch up with the rest of team, but I’ll call you back in a bit! This is going to be great! Erik: OK. Uh... Alrighty then! I guess this is just going to be our code-along now! So let's -- let's see if we can finish up onboarding before Jamie gets out of that meeting! So, for this session, let’s focus on onboarding and consent. Explaining to the participant what data we’re going to collect, who's going to have access to it, what it’ll be used for, how long it will be retained -- and making all of that easy to understand -- is of paramount importance to a good study. We’re going to show you some new best practices for ResearchKit that will help you get this very important part of your app just right. And as a bonus, we’re going to demonstrate a clever way to bake that onboarding and consent flow right into a CareKit-based app. Specifically, we’re going to set up a standard CareKit app, but in a way that participants must complete onboarding before the care plan’s contents are revealed. As part of that consent and onboarding flow, we’re going to build out some instruction steps telling the participants about what they’re about to be asked to do. We’ve found that orienting participants like this, before jumping into the actual consent parts, really helps improve their experience. We’ll show you how to collect a signature, and we’ll also demonstrate how to use ResearchKit to ask for authorization for HealthKit, notifications, and device motion all up front, all as part of onboarding. If you’d like to follow along, you can find the starter project in the session resources. Let’s open Xcode and get started! This is where we’ll be starting from. We're going to be touching four files today. First is the AppDelegate. This is where we're going to be interacting with CareKit’s store. Over in Surveys.swift, we’ll be writing out some surveys using ResearchKit. Next up, we've got the CareFeedViewController and InsightsViewController, where we’ll be building out the UI for our app. Now, if you run the starter app, you’ll see that there’s actually not much there right now. It's just the OCKDailyPageViewController with no content. It allows us to jump around between days, but there’s nothing there yet. It’ll be our job to fill all of that in. There’s also the Insights tab down here in the corner, and we'll be returning to that during part three. Now, what we want to do is make a consent card show up here in the participant’s feed. That consent task will gate access to the rest of the app. Nothing else will show up until it’s been completed, and once it has been, all the other tasks should appear.
Jumping over here to AppDelegate.swift, our first step will be to persist a CareKit task for onboarding. Now, whenever we create a task, we need to define a schedule that specifies how often the task will appear in the participant’s feed. For onboarding, we’ll use a daily schedule so they’ll be prompted to onboard every day until they finish consenting. Next, we’ll create a task. We give it an ID, which can be anything we want, so long as it’s unique. Random identifiers are fine, but in this case, I’ve just got a constant we’ve defined over here in another file. We also need to pass in the schedule that we just created. We’ll also specify some instructions and indicate that onboarding should not impact adherence. What this means is basically that onboarding won’t count toward filling the completion rings that you see at the top of most CareKit apps. And finally, we can persist the task into our store. We’ll just go ahead and print out a message to let us know if it was successful or not. All right, we’ve got our onboarding task in the store, ready to go, and now, we’re ready to make it appear in the participant’s feed. We’ll hop over CareViewController.swift where we’ll tell CareKit how we want it to be displayed. Here, we’re subclassing OCKDailyPageViewController, which is the calendar and feed that we saw just a moment ago. We’re overriding the prepare listViewController for date method. This method will be invoked each time the user swipes to a new date, and it’s our job to inspect the date, determine what we want to show on that date, and append the appropriate content into the listViewController. Now, the first thing we want to do is check if the participant has finished onboarding or not, since we’ll display different content based on the answer to that question. Let’s drop down a bit further and write out a method to do just that. Inside of our checkIfOnboardingIsComplete method, we’ll create an OCKOutomeQuery, and we’ll query for all outcomes associated with the onboarding task. When our query returns, we’ll check to see if any outcomes were found or not. If there aren’t any, that means onboarding hasn’t finished yet. If there is one, that means that onboarding is already complete. We’ll use our new method right up here, and based on whether or not onboarding is complete, we’ll either show just the consent task or all the other tasks. All right. So far, so good! We now have a mechanism in place for requiring the participant to onboard before letting them into the rest of the app. The next step is to set up that onboarding flow. Right here, we want to create a CareKit task card that presents a ResearchKit survey, but before we can do that, we need to actually create a ResearchKit survey so that we have something to display. We’ll pop over to Surveys.swift and get that taken care of. Let’s stub out our function to start. Our onboarding survey is going to consist of five steps: a welcome step, an instruction step, a signature step, a permissions step, and finally, a completion step. The first is going to be the welcome step, which will be an ORKInstructionStep. We’re going to see a lot of these instructions steps today. Whenever we create a ResearchKit step, we need to give it a unique identifier. You can use any pattern that you’d like, including random identifiers. I’ve found that this key path-inspired approach works really well for me. We’ll also specify a title and some detailText as well as a header image. All right. So up next: step two is going to be our informed consent step, and this will also be an instruction step. But this time, we’re going to add some body items. Body items are basically bullet points, but we have the option to use an image -- and in this case, an SF Symbol -- in place of the bullet. This body item tells participants they’re going to be asked to share some health data. Let’s create a second body item to tell them they’ll be asked to complete tasks and a third to inform them they’ll be asked to provide their signature. Let's add one more to remind them that their data will be kept private and secure. Finally, we’ll insert these body items into our instruction step. And that covers the instructions. Next up is gathering a signature, and fortunately, ResearchKit makes this part really easy. The signature can be collected with an ORKWebViewStep. Setting the showSignature AfterContent property to true prompts ResearchKit to show the signature box at the bottom of the step. We can supply the actual consent document as HTML, and it will be shown right above the signature box. There we go; the signature was pretty quick and easy! The last bit will be requesting permissions. For this fourth step, we’ll collect permissions with the HealthKitPermissionType that my teammate Pariece introduced at WWDC last year. It requires that we specify two sets of HealthKit types: one that’s we’d like permission to write to and one that we’d like permission to read from. This year, we’re introducing two new permission types. The first is ORKNotificationPermissionType, and it allows us to request permission to show alerts, badge the app, and play sounds. We’re also introducing the ORKMotionActivity PermissionType, which will help us ask for access to device motion data. We’ll pass all three of these into a requestPermissionStep, which wraps up our fourth step. The fifth and final step is just going to be a completion step that thanks the participant for joining Jamie’s study. All of these steps will be chained together inside of an ORKOrderedTask. We’ll pass in the steps in the order we’d like ResearchKit to present them and then return the task from this method. All right. Now that we’ve defined the whole onboarding and consent flow, let’s jump back into CareFeedViewController and revisit how to display it from our CareKit-based app. We’re introducing a brand-new class, the OCKSurveyTaskViewController, and it is specifically built for this purpose. Like all other CareKit view controllers, we pass in the ID of the task we’d like to display along with an eventQuery and the storeManager. Additionally, we’ll also need the survey we just created and a closure that translates a ResearchKit result into an array of CareKit outcome values. We’ll revisit this closure in more detail during part two. For now, we’ll just say it's sufficient to persist the date that the participant completed onboarding. We’ll also want to append this task card into our feed. Now, there is actually one more step, and that is to make sure that the feed reloads once the participant finishes onboarding. One way we can accomplish that is by setting ourselves as the survey task view controller’s delegate. Then, down here, we can implement the delegate method, survey task view controller didFinish task with result. In the body of this method, we can check that onboarding was completed successfully, which is basically just to say that the participant didn’t cancel out partway through; they went all the way to the end and completed it successfully. If that’s the case, we can call reload() to refresh the feed. All right, so our onboarding card is set up. When the participant completes onboarding, we’ll save an OCKOutcome and then reload the feed. This is looking good! I think that’s -- that's everything, actually! Let’s run our app and confirm that this all works.
You can see that we’re being asked to consent before we can begin using the app. And that’s exactly what we want! Let’s tap on the Begin button here, and we'll see that we’re greeted by the welcome step we created just a moment ago. The next step is our instruction step with the body items that we defined. The SF Symbols that we chose really bring it to life. Next up is the signature step, so l’ll just scroll down here and sign that... ...and then we move on to the authorization step. First, we'll authorize HealthKit. Just go ahead and allow that. Next up is notifications, and then device motion. The last page is our completion step that lets us know we’re all done and thanks us for participating. And now we’re back in our Care Feed. Note that we don’t see the prompt to complete consent anymore because we’re done with that now. Instead, this is where all of the true content of our app is going to appear. We’re going to get to that in our next session.
Hey Siri, can you message Jamie and tell him that we’re done with the onboarding and consent? You can find more info about our frameworks on researchandcare.org. If you’d like to read the source code -- or contribute -- both frameworks are available on GitHub. Please join us again for our next session. I’m going to check with Jamie real quick, and then I’ll rejoin you for part two. See you soon! ♪
Looking for something specific? Enter a topic above and jump straight to the good stuff.
An error occurred when submitting your query. Please check your Internet connection and try again.