Merge pull request #332 from erik-apple/update-readme

Update README with details about integrating ResearchKit

Author: erik-apple

README.md

@@ -32,6 +32,7 @@ CareKit™ is an open source software framework for creating apps that help peop
     * [Schema](#schema)
     * [Scheduling](#scheduling)
     * [Custom Stores and Types](#custom-stores-and-types)
+* [Integrating with ResearchKit](#integrating-with-researchkit)
 * [Getting Help](#getting-help)
 * [License](#license)
 
@@ -41,6 +42,7 @@ The primary CareKit framework codebase supports iOS and requires Xcode 11.0 or n
 
 # Getting Started <a name="getting-started"></a>
 
+* [Documentation](https://developer.apple.com/documentation/carekit)
 * WWDC Video: [ResearchKit and CareKit Reimagined](https://developer.apple.com/videos/play/wwdc2019/217/)
 
 ### Installation (Option One): SPM
@@ -498,10 +500,120 @@ your underlying data store to achieve greater performance or efficiency.
 
 If you are considering implementing your own store, read over the protocol notes and documentation carefully.
 
+# Integrating with ResearchKit <a name="integrating-with-researchkit"></a>
+
+CareKit and ResearchKit are sister frameworks and are designed to integrate well with one another.
+
+When integrating a ResearchKit into your CareKit app, there are a series of steps you will need to follow.
+
+1. Subclass an existing task view controller
+2. Override the method that is called when the task is completed
+3. Present a ResearchKit survey and wait for the user to complete it
+4. Get the survey result and save it to CareKit's store
+
+Here is an example demonstrating how to prompt the user to rate their pain on a scale of 1-10.
+Keep in mind as you're reading the code below that CareKit and ResearchKit both use the term "task", but that they are distinct.
+
+
+```swift
+// 1. Subclass a task view controller to customize the control flow and present a ResearchKit survey!
+class SurveyViewController: OCKInstructionsTaskViewController, ORKTaskViewControllerDelegate {
+
+    // 2. This method is called when the use taps the button!
+    override func taskView(_ taskView: UIView & OCKTaskDisplayable, didCompleteEvent isComplete: Bool, at indexPath: IndexPath, sender: Any?) {
+
+        // 2a. If the task was marked incomplete, fall back on the super class's default behavior or deleting the outcome.
+        if !isComplete {
+            super.taskView(taskView, didCompleteEvent: isComplete, at: indexPath, sender: sender)
+            return
+        }
+
+        // 2b. If the user attempted to mark the task complete, display a ResearchKit survey.
+        let answerFormat = ORKAnswerFormat.scale(withMaximumValue: 10, minimumValue: 1, defaultValue: 5, step: 1, vertical: false,
+                                                 maximumValueDescription: "Very painful", minimumValueDescription: "No pain")
+        let painStep = ORKQuestionStep(identifier: "pain", title: "Pain Survey", question: "Rate your pain", answer: answerFormat)
+        let surveyTask = ORKOrderedTask(identifier: "survey", steps: [painStep])
+        let surveyViewController = ORKTaskViewController(task: surveyTask, taskRun: nil)
+        surveyViewController.delegate = self
+
+        // 3a. Present the survey to the user
+        present(surveyViewController, animated: true, completion: nil)
+    }
+    
+    // 3b. This method will be called when the user completes the survey. 
+    func taskViewController(_ taskViewController: ORKTaskViewController, didFinishWith reason: ORKTaskViewControllerFinishReason, error: Error?) {        
+        taskViewController.dismiss(animated: true, completion: nil)
+        guard reason == .completed else {
+            taskView.completionButton.isSelected = false
+            return
+        }
+
+        // 4a. Retrieve the result from the ResearchKit survey
+        let survey = taskViewController.result.results!.first(where: { $0.identifier == "pain" }) as! ORKStepResult
+        let painResult = survey.results!.first as! ORKScaleQuestionResult
+        let answer = Int(truncating: painResult.scaleAnswer!)
+
+        // 4b. Save the result into CareKit's store
+        controller.appendOutcomeValue(withType: answer, at: IndexPath(item: 0, section: 0), completion: nil)
+    }
+}
+```
+
+Once you have defined this view controller, you can add it into your app as you would any other CareKit view controller!
+
+```swift
+let todaysSurveyCard = SurveyViewController(
+    taskID: "survey",
+    eventQuery: OCKEventQuery(for: Date()),
+    storeManager: storeManager)
+
+present(surveyCard, animated: true, completion: nil)
+```
+
+You may also decide that you want the view to update to display the result of your survey instead of the default values used by the superclass. To change that, you can implement your own view synchronizer.
+
+```swift
+class SurveyViewSynchronizer: OCKInstructionsTaskViewSynchronizer {
+
+    // Customize the initial state of the view
+    override func makeView() -> OCKInstructionsTaskView {
+        let instructionsView = super.makeView()
+        instructionsView.completionButton.label.text = "Start Survey"
+        return instructionsView
+    }
+
+    // Customize how the view updates
+    override func updateView(_ view: OCKInstructionsTaskView,
+                             context: OCKSynchronizationContext<OCKTaskEvents?>) {
+        super.updateView(view, context: context)
+
+        // Check if an answer exists or not and set the detail label accordingly
+        if let answer = context.viewModel?.firstEvent?.outcome?.values.first?.integerValue {
+            view.headerView.detailLabel.text = "Pain Rating: \(answer)"
+        } else {
+            view.headerView.detailLabel.text = "Rate your pain on a scale of 1 to 10"
+        }
+    }
+}
+```
+
+Now, when you create an instance of your `SurveyViewController`, you can pass in your custom view synchronizer to change how the view updates.
+
+```swift
+let surveyCard = SurveyViewController(
+    viewSynchronizer: SurveyViewSynchronizer(),
+    taskID: "survey",                                             
+    eventQuery: OCKEventQuery(date: Date()),
+    storeManager: storeManager)
+
+present(surveyCard, animated: true, completion: nil)
+```
+
 # Getting Help <a name="getting-help"></a>
 
 GitHub is our primary forum for CareKit. Feel free to open up issues about questions, problems, or ideas.
 
 # License <a name="license"></a>
 
 This project is made available under the terms of a BSD license. See the [LICENSE](LICENSE) file.
+