CMHealth 0.6.0

CMHealth 0.6.0

测试已测试
语言语言 Obj-CObjective C
许可证 MIT
发布上次发布2017年8月
SwiftSwift 版本3.0

CloudMine EngineeringCloudMine Engineering 维护。



 
依赖项
ResearchKit~> 1.3
CareKit~> 1.2
CloudMine~> 1.7.16
 

CMHealth 0.6.0

  • CloudMine

CMHealth

CMHealth 是向您的 ResearchKitCareKit iOS 应用添加安全、符合 HIPAA 的新型云数据存储和管理方式的最简单方法。由 CloudMine 和 CloudMine Connected Health Cloud 构建和支持。

安装

CMHealth 可通过 CocoaPods 1.0.0 或更高版本安装。要安装它,只需将以下行添加到您的 Podfile 中

platform :ios, '9.0'

target 'MyHealthApp' do
  use_frameworks!
  
pod 'CMHealth', :git => '[email protected]:cloudmine/CMHealthSDK-iOS.git'
pod 'CareKit', :git => '[email protected]:cloudmine/CareKit.git', :branch => 'cm-patched'

end

安装完成后,必须在您的 AppDelegate 类中导入并配置 SDK。有关更多信息,请参阅配置部分。

注意:CMHealth 依赖于 Apple CareKit 的 master 分支。当 Apple 将 CareKit 1.2 发布到 CocoaPods 时,将从 GitHub 安装的要求中移除。如有任何问题,请联系 [email protected]

注册用户

SDK 提供了一种管理参与者账户的用户抽象,并提供了简单的方法进行用户认证。

#import <CMHealth/CMHealth.h>

[[CMHUser currentUser] signUpWithEmail:email password:password andCompletion:^(NSError *error) {
    if (nil != error) {
        // handle error
        return;
    }

    // The user is now signed up
}];

如果您的应用使用标准的 ResearchKit ORKRegistrationStep,SDK 还提供了一种方便的用户注册方法。只需将 ORKTaskResult 传递给 signupWithRegistration:andCompletion: 方法,SDK 就会确保注册结果存在于结果层次结构中,并在注册用户账户之前提取相关参与者数据。

#import <CMHealth/CMHealth.h>

#pragma mark ORKTaskViewControllerDelegate

- (void)taskViewController:(ORKTaskViewController *)taskViewController didFinishWithReason:(ORKTaskViewControllerFinishReason)reason error:(NSError *)error
{
    if (nil != error) {
        // Handle Error
        return;
    }

    if (reason == ORKTaskViewControllerFinishReasonCompleted) {
        [CMHUser.currentUser signUpWithRegistration:taskViewController.result andCompletion:^(NSError * _Nullable signupError) {
            if (nil == signupError) {
                // Handle Error
                return;
            }

            // The user is now signed up
        }];
    }

    [self dismissViewControllerAnimated:YES completion:nil];
}

SDK 包含一个预配置的 ResearchKit ORKLoginStepViewController 子类,用于处理现有用户的登录和密码重置。视图控制器可以简单地实例化并展示;结果将通过委托回调返回。

#import <CMHealth/CMHealth.h>

- (IBAction)loginButtonDidPress:(UIButton *)sender
{
    CMHLoginViewController *loginVC = [[CMHLoginViewController alloc] initWithTitle:NSLocalizedString(@"Log In", nil)
                                                                               text:NSLocalizedString(@"Please log in to you account to store and access your research data.", nil)
                                                                           delegate:self];
    loginVC.view.tintColor = [UIColor greenColor];

    [self presentViewController:loginVC animated:YES completion:nil];
}

#pragma mark CMHLoginViewControllerDelegate

- (void)loginViewControllerCancelled:(CMHLoginViewController *)viewController
{
    // User cancelled login process
}

- (void)loginViewController:(CMHLoginViewController *)viewController didLogin:(BOOL)success error:(NSError *)error
{
    if (!success) {
        // Handle Error
        return;
    }

    // The user is now logged in
}

维持同意

SDK 提供了专门的方法用于归档和检索参与者的同意。在 ResearchKit 中,用户同意在包含特殊同意和签名步骤的任何 ORKTask 中收集。CMHealth 允许您归档包含用户同意的 ORKTaskResult 对象。SDK 会确保结果层次结构中存在同意步骤并且已收集签名。它可无缝处理签名图像的上传。

#import <CMHealth/CMHealth.h>

// `consentResults` is an instance of `ORKTaskResult`
[[CMHUser currentUser] uploadUserConsent:consentResults forStudyWithDescriptor:@"MyClinicalStudy" andCompletion:^(NSError * consentError) {
    if (nil != error) {
        // handle error
        return;
    }

    // consent uploaded successfully
}];

为了确保您的参与者在使用研究活动之前有有效的同意书,您可以检索任何用户的同意对象。

#import <CMHealth/CMHealth.h>

[[CMHUser currentUser] fetchUserConsentForStudyWithDescriptor:@"MyClinicalStudy" andCompletion:^(CMHConsent *consent, NSError *error) {
    if (nil != error) {
        // Something went wrong
        return;
    }

    if (nil == consent) {
        // No consent on file
        return;
    }

    // User has valid consent on file
}];

ResearchKit

SDK 为标准 ResearchKit 类提供分类方法,允许您将 ORKTaskResult 对象保存到和从 CloudMine Connected Health Cloud

您可以在 CocoaPodsGitHub 上查看完整的文档和类引用。

配置您的 CloudMine 应用密钥

应通过 CocoaPods 安装 CMHealth SDK。应在您的 AppDelegate 类中配置 SDK,以便向 CloudMine 后端提供适当的凭证。

对于 ResearchKit 应用,需要一个 App 标识符和 App 密钥(API 密钥)。

#import <CMHealth/CMHealth.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [CMHealth setAppIdentifier:@"My-CloudMine-App-ID" appSecret:@"My-CloudMine-API-Key"];	
	return YES;
}

保存

#import <CMHealth/CMHealth.h>

// surveyResult is an instance of ORKTaskResult, or any ORKResult subclass
[surveyResult cmh_saveToStudyWithDescriptor:@"MyClinicalStudy" withCompletion:^(NSString *uploadStatus, NSError *error) {
        if (nil == uploadStatus) {
            // handle error
            return;
        }
        if ([uploadStatus isEqualToString:@"created"]) {
            // A new research kit result was saved
        } else if ([uploadStatus isEqualToString:@"updated"]) {
            // An existing research kit result was updated
        }
    }];

检索

#import <CMHealth/CMHealth.h>

[ORKTaskResult cmh_fetchUserResultsForStudyWithDescriptor:@"MyClinicalStudy" withCompletion:^(NSArray *results, NSError *error) {
        if (nil == results) {
            // handle error
            return;
        }

        for (ORKTaskResult *result in results) {
            // use your result
        }
    }];

CareKit

CMHealth SDK 提供了将您的 CareKit 应用本地的设备存储和 CloudMine Connected Health Cloud 之间同步数据的能力。

概述

CloudMine 的平台提供了强大的 代码片段ACL 框架,当使用 CareKit 时,这些是 CMHealth 框架的依赖项。CareKit SDK 会将 OCKCarePlanActivityOCKCarePlanEvent 对象自动存储在登录用户的级别数据存储中。为了授予 CareProvider 访问这些数据,需要 ACL 框架和一个服务器端的 逻辑引擎代码片段 来正确地附加适当的 acl_id

配置

以下步骤是使用 CloudMine 框架之前必须的先决条件。如需帮助配置 CloudMine 平台上的这个一次性配置,请联系 [email protected]

启用自动时间戳

必须为您的 app_id 启用自动时间戳(auto_ts)功能。可以通过运行以下 cURL 请求启用此功能。

启用 auto_ts 后,所有应用程序和用户级对象都将包括自动维护的 __updated____created__ 键值对,这些将由 CloudMine 平台自动维护。

注意:auto_ts 是一个缓存配置值,设置生效可能需要15分钟。

请求

curl -X POST \
  https://api.cloudmine.io/admin/app/:app_id/prefs \
  -H 'content-type: application/json' \
  -H 'x-cloudmine-apikey: :master_api_key' \
  -d '{
	"auto_ts":true
}'
  1. app_id:必需。来自 Compass 控制台的 App 标识符。
  2. master_api_key:必需。在 Compass 控制台可用。

响应

HTTP/1.1 200 OK

如果观察到 4xx 错误代码,请确保正在使用 Master API Key 执行请求。

准备管理员用户

使用 CloudMine 的 ACL 框架检索患者级别数据时需要一个初始的管理员用户。要创建管理员用户,可以使用以下的 cURL

请求

curl -X POST \
  https://api.cloudmine.io/v1/app/:app_id/account/create \
  -H 'content-type: application/json' \
  -H 'x-cloudmine-apikey: :api_key' \
  -d '
{
    "credentials": {
        "email": "[email protected]",
        "password": "the-password"
    },
    "profile": {
        "name": "Admin User",
        "email":"[email protected]"
    }
}'
  1. app_id:必需。来自 Compass 控制台的 App 标识符。
  2. api_key:必需。在 Compass 控制台可用。
  3. credentials.email:必需。指行政管理员的电子邮件地址。
  4. credentials.password:必需。设置初始的管理员密码。
  5. profile.email:必需。指行政管理员的电子邮件地址。

响应

HTTP/1.1 201 OK
{
	"name": "Admin User",
	"email": "[email protected]",
	"__type__": "user",
	"__id__": "54e952dd255e42ada66f04bd1d938325"
}

请注意返回的用户 __id__ 值,在将来创建管理员 ACL 时将需要它。

创建管理员配置文件

在某些情况下,管理员配置文件可能包含敏感信息。因此,应将其作为用户级对象创建,并通过公共配置文件上的 __id__ 进行引用。

请求

curl -X POST \
  'https://api.cloudmine.io/v1/app/:app_id/user/text?userid=:admin_user_id' \
  -H 'content-type: application/json' \
  -H 'x-cloudmine-apikey: :master_api_key' \
  -d '{
    "generate-unique-profile-key": {
      "__id__": "unique-object-key",
      "cmh_owner": ":admin_user_id",
      "__access__": [
        null
      ],
      "gender": null,
      "isAdmin": true,
      "dateOfBirth": null,
      "__class__": "CMHInternalProfile",
      "email": ":admin_email",
      "familyName": null,
      "givenName": null,
      "userInfo": {
        "__class__": "map"
      },
      "__created__": "2017-06-01T15:33:46Z",
      "__updated__": "2017-06-01T15:57:43Z"
    }
  }'
  1. app_id:必需。来自 Compass 控制台的 App 标识符。
  2. admin_user_id:必需。指管理员的 __id__
  3. master_api_key:必需。在 Compass 控制台可用。

响应

HTTP/1.1 200 OK
{
  "success": {
    "036f5dfc5a7fdb4819c80d86429ed126": "created"
  },
  "errors": {}
}

请注意用于 generate-unique-profile-key 的值,因为将在下一步中需要它。

引用管理员配置文件

一旦创建了个人的配置文件,CareKit 框架将期望在公共配置文件上找到一个对该配置文件的引用。我们需要更新公共配置文件,以确保用户登录时配置文件数据加载正确。

请求

curl -X POST \
  'https://api.cloudmine.io/v1/app/:app_id/account/?userid=:admin_user_id' \
  -H 'content-type: application/json' \
  -H 'x-cloudmine-apikey: :master_api_key' \
  -d '{ 
  "profileId":"generate-unique-profile-key"
}'
  1. app_id:必需。来自 Compass 控制台的 App 标识符。
  2. admin_user_id:必需。指管理员的 __id__
  3. master_api_key:必需。在 Compass 控制台可用。
  4. generate-unique-profile-key:必需。指用于创建私人管理员配置文件的对象密钥。

响应

HTTP/1.1 200 OK

恭喜!第一个管理员用户已经成功准备就绪。

创建管理员 ACL

管理员 ACL 将用于确保可以通过管理员用户召回患者数据。使用 [members] 数组来跟踪所有管理员用户 __id__ 值,这些值可以随意添加。一旦登录,患者数据将自动对他们可用。

请求

curl -X POST \
  'https://api.cloudmine.io/v1/app/:app_id/user/access?userid=:admin_user_id' \
  -H 'content-type: application/json' \
  -H 'x-cloudmine-apikey: :master_api_key' \
  -d '{
    "members": [":admin_user_id"],
    "permissions": ["r", "c", "u", "d"],
    "my_extra_info": "for CK admins"
}'
  1. app_id:必需。来自 Compass 控制台的 App 标识符。
  2. master_api_key:必需。在 Compass 控制台可用。
  3. admin_user_id:必需。指管理员的 __id__

响应

HTTP/1.1 201 OK
{
  "454a72bf7ae54f73abd33d0d3690d822": {
    "__type__": "acl",
    "__id__": "454a72bf7ae54f73abd33d0d3690d822",
    "permissions": [
      "r",
      "c",
      "u",
      "d"
    ],
    "members": [
      "44629a07c9014d2eba92ae9dca1d813a"
    ],
    "segments": {}
  }
}

请注意新创建的ACL返回的__id__值。在下一步中需要使用该值。

开发和上传管理代码段

OCKCarePlanEventOCKCarePlanActivity对象被保存时,代码片段负责将该管理ACL id值添加到对象的[__access__]字段中,允许与任何CareKit管理用户共享。这里提供了一个示例代码片段:docs/AdministrativeSnippet/Example.js

完成后,确保通过Compass仪表板将代码段上传到CloudMine。请注意创建时使用的名称,因为它将在下一步配置您的CloudMine应用机密时需要。

配置您的CloudMine应用机密

最后,您的AppDelegate中的配置很简单。只需提供上一步的CloudMine app_idapi_keyshared_snippet_name即可。CK对象将立即开始同步。

#import <CMHealth/CMHealth.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [CMHealth setAppIdentifier:@"My-CloudMine-App-ID" appSecret:@"My-CloudMine-API-Key" sharedUpdateSnippetName:@"My-Deployed-Shared-Snippet-Name"];
	return YES;
}

祝贺!您现在可以使用CMHealth SDK和CloudMine开始构建您的应用了。

注意:需要Master API Key才能执行上述许多cURL操作。强烈建议在完成配置后更换主API密钥,或者确保客户端侧使用时妥善保管,以防止未经授权访问您应用的数据。

使用CareKit

您可以使用所有原生CareKit组件构建面向患者的应用,与标准CareKit应用的偏差很小。

创建CMHCarePlanStore

只需将OCKCarePlanStore替换为我们自定义的子类实例CMHCarePlanStore,您的用户数据将自动推送到CloudMine。

#import <CMHealth/CMHealth.>

// `self.carePlanStore` is assumed to be a @property of type CMHCarePlanStore
self.carePlanStore = [CMHCarePlanStore storeWithPersistenceDirectoryURL:BCMStoreUtils.persistenceDirectory];
self.carePlanStore.delegate = self;

只要您的患者用户处于登录状态,且您的CloudMine账户配置正确,您的CareKit应用现在将自动将本地存储中做出的更改推送到云端。

创建新活动

例如,向商店添加新活动会将该活动表示 pushing到CloudMine的后端,针对当前用户进行保存。

#import <CMHealth/CMHealth.h>

// Create a standard OCKCarePlanActivity instance somewhere in your app
OCKCarePlanActivity *activity = [self activityGenerator];

// Add this activity to the store as you would in a standard CareKit app
[self.carePlanStore addActivity:activity completion:^(BOOL success, NSError * _Nullable error) {
    if (!success) {
		NSLog(@"Failed to add activity to store: %@", error.localizedDescription);
		return;
    }
    
    NSLog(@"Activity added to store");
}];

请注意,上述代码与传统、仅本地运行的CareKit应用的代码没有区别。推送CMHCarePlanStore条目到CloudMine不需要额外考虑!

从服务器同步

从云中获取更新云端同样简单。一个方法即可允许您将本地存储与自上次成功调用以来已添加的所有远程数据同步。

#import <CMHealth/CMHealth.h>

[self.carePlanStore syncFromRemoteWithCompletion:^(BOOL success, NSArray<NSError *> * _Nonnull errors) {
    if (!success) {
        NSLog(@"Error(s) syncing remote data %@", errors);
        return;
    }
        
    NSLog(@"Successful sync of remote data");
 }];

这允许您的应用在设备和会话之间以最小的努力实现同步。

获取所有患者信息

为了帮助组织访问由患者生成的CareKit数据,CMHealth SDK允许根据我们在配置部分创建的ACL获取所有患者及其活动/事件数据的聚合视图。该方法要求管理员CareKit用户登录。

要获取OCKPatient实例的列表并在您的应用程序中使用,请调用CMHCarePlanStore的类方法fetchAllPatientsWithCompletion:

[CMHCarePlanStore fetchAllPatientsWithCompletion:^(BOOL success, NSArray<OCKPatient *> * _Nonnull patients, NSArray<NSError *> * _Nonnull errors) {
	if (!success) {
        NSLog(@"Errorse fetching patients: %@", errors);
        return;
	}
        
    self.patients = patients;
}];

后续调用此类方法将返回更新后的患者列表,但它将智能同步自上次调用以来新增或更新的数据。

添加新管理用户

添加新管理用户需要3个步骤

  1. 创建管理员用户
  2. 在对象的 CMHUserData 属性中将 isAdmin 字段切换为 true,
  3. 根据创建管理员 ACL部分所述,将管理员 user_id 添加到 acl_id 上的 [members] 字段。

创建管理员用户

CMUser 类包含以下方法,以便在您的 CareKit 实现中创建新用户

- (void)signUpWithEmail:(NSString *_Nonnull)email
               password:(NSString *_Nonnull)password
          andCompletion:(_Nullable CMHUserAuthCompletion)block;

用户成功创建后,您就可以进行下一步了。

创建管理员 CMHUserData 对象

CMHUserData 类表示关于管理用户的额外配置文件数据。除了表示关于用户的详细信息外,它还包含一个 BOOL 属性 (isAdmin),以指示用户是否确实是管理员。您创建 CMHUserData 实例后,可以使用以下 CMHUser 方法调用将其附加到目标 CMHUser

- (void)updateUserData:(CMHUserData *_Nonnull)userData
        withCompletion:(_Nullable CMHUpdateUserDataCompletion)block;

注意:在调用此方法之前,请确保将 isAdmin 布尔值设置为 true,否则底层框架可能无法正确识别此用户为管理员。

将管理员 user_id 添加到管理 ACL

在创建用户及其相应的配置文件数据后,需要将用户的 __id__ 值添加到管理员 acl。以下 cURL 请求可以是执行此操作的一个示例

请求
curl -X POST \
  'https://api.cloudmine.io/v1/app/:app_id/user/access/:admin_acl_id?userid=:admin_user_id' \
  -H 'content-type: application/json' \
  -H 'x-cloudmine-apikey: :master_api_key' \
  -d '{
    "members": [":new_admin_id",":existing_admin_ids"]
}'
  1. app_id:必需。来自 Compass 控制台的 App 标识符。
  2. admin_acl_id: 必需。在您的 App 中首次实施 CareKit 时生成。
  3. admin_user_id:必需。指管理员的 __id__
  4. master_api_key:必需。在 Compass 控制台可用。
  5. new_admin_id: 必需。启用的新管理员的 user_id
  6. existing_admin_ids: 必需。指现有管理员用户,以确保它们在为新的管理员插入过程中不会被覆盖。
响应
HTTP/1.1 200 OK

注意:强烈建议将此工作流程作为您更大的应用程序中的服务器端代码片段来实施。要更新 CareKit ACL,需要 Master API 密钥或根管理员用户的密码。如果客户端使用 Master API 密钥,请确保安全地处理或完成更新后的主 API 密钥,并将管理代码片段更新为新密钥。

在 CMHealth 与 CloudMine iOS SDK 一起使用

CMHealth 包含并扩展了 CloudMine iOS SDK,因此您可以免费获得所有核心 CloudMine 功能。要超越 CMHealth 的 ResearchKit 特定部分,请从CloudMine iOS 文档开始。

CMHealth 示例

为了了解 CMHealth 如何无缝地与 ResearchKit 协作,您可以查看 CloudMine 的 AsthmaHealth 演示应用程序。此 SDK 设计用来与 Swift 无缝协作。查看 AsthmaHealthSwift 演示应用程序,了解 CMHealth 如何使应用程序完全采用 Swift。

要查看 CMHealth 与 CareKit 协作的示例,您可以查看 CloudMine 的 BackTrack 演示应用程序。

支持

如果您需要一般的 CMHealth 支持,请通过电子邮件 [email protected] - 我们随时为您提供帮助!

对于寻求更多便利性的人员,我们鼓励通过标准的 GitHub 分支、问题跟踪器和拉取请求途径直接参与。请参阅 CONTRIBUTING 文档以开始。

许可证

CMHealth 在 MIT 许可证下可用。有关更多信息,请参阅 LICENSE 文件。