Native iOS Migration Guide

Overview

The Inform version (2.0.0 and newer) of the Validic Mobile Library is designed to improve interoperability with the rest of the Validic ecosystem. It includes improved Record models that closely match the models used in the rest of the Validic Inform system, but offers a clear production upgrade path by maintaining backward-compatibility with the v1 models.

Each module contains a README with usage information for v1 and Inform. You can also find all of the Inform README documentation on this site by starting here and reviewing the appropriate child pages for your use case.

Important Notes

"Inform SDK" refers to the Validic Mobile SDK release versions that are 2.0.0 and newer. "v1 SDK" refers to all 1.x.x versions of the Validic Mobile SDK.
The Inform SDK is available in a new Artifactory mobile portal. If you are currently using the mobile portal located at https://mobileportal.validic.com/, you will need to be granted access to the new mobile portal. Please contact Validic support to be placed on our waitlist for access to the new mobile portal and Inform SDK.
The Inform SDK only supports Inform organizations. If you are still using Validic's v1 (legacy API) system, please contact support to migrate to Inform before implementing the new Inform SDK modules/frameworks.
You must use the Inform version of the ValidicCore framework if you plan to use any other Inform framework.
- For example, if you are going to update to the Inform ValidicBluetooth framework, you must also update to the Inform ValidicCore framework at the same time.
- The Inform Session supports both v1 and Inform data models for backwards compatibility, so replace the v1 Session with the Inform Session when you start to use Inform frameworks in your mobile project.

Installation

For the Inform SDK, only .xcframeworks are provided - .framework installation is not supported. The Inform .xcframework bundles are named the same as their v1 counterparts, so you can just replace the v1 .xcframeworks with the Inform .xcframeworks.

If you were previously using the Validic .frameworks:

Completely delete the Validic .framework bundles from your Xcode project
Remove the copy-validicmobile.rb Run Script phase from your target's Build Phases
Add the .xcframework bundles to the "Frameworks, Libraries, and Embedded Content" list in your target's General settings.
Make sure the new Validic .xcframeworks are listed in both the "Link Binary With Library" and "Embed Frameworks" Build Phases of your target.

In order to use any Inform SDK, the Validic Core SDK in your project must be updated to Inform as well. The Inform Core SDK is backwards-compatible with v1 SDKs (Bluetooth, HealthKit, OCR, and LifeScan), so you can upgrade the feature SDKs one at a time if you prefer.

For example, if your project implements Core, Bluetooth, and HealthKit; you can upgrade Core and HealthKit to their Inform versions, but leave Bluetooth at v1. Or you can update Core and Bluetooth to Inform and leave HealthKit on v1. Or you can upgrade all 3 at once.

Session (ValidicCore)

Logging

Validic debug logging has not changed in the Inform SDKs. You can find more details in Logging.

User Session

User session behavior remains almost identical to the behavior in v1, with a few notable exceptions:

Only v2 org users are supported. If an existing session is loaded with a user from a v1 org, the session will fail its first attempted record upload and be ended.
There is no "Default user" provided in the Inform SDK. You must use a valid user to initialize the session. If an existing session is loaded with a v1 Default user, the session will fail validation and be ended.
Some methods and notifications are named differently to distinguish ones meant for the new Inform-based records:
- When submitting an Inform record, use submitInformRecord instead of submitRecord.
- When listening for Inform record submission success/failure notifications, use kVLDInformRecordSubmittedNotification and kVLDInformRecordSubmissionFailedNotification.
- In the kVLDSessionEndedNotification notification, unsubmitted Inform records are available in the userInfo dictionary's informRecords key.

Inform Records

Records have received a big overhaul in the Inform SDK. We've addressed a lot of the weaknesses in the v1 model, as well as brought the models into alignment with what the rest of the Validic Inform system uses. This will make interacting with the native record models much simpler, as they will look almost exactly like the models you receive from the Inform APIs.

The main Validic Record class in the Inform SDK is VLDInformRecord - all record classes inherit from this class. The subclasses are:

VLDInformMeasurement: provides point in time measurements, like height, weight, blood pressure, glucose, etc. It replaces v1's VLDDiabetes, VLDBiometrics, and VLDWeight.
VLDInformNutrition: provides a summary of your daily nutritional intake. It replaces v1's VLDNutrition.
VLDInformSleep: provides a record of your sweet, sweet dreams. It replaces v1's VLDSleep.
VLDInformSummary: provides a summary of your daily activity, like steps, calories and heart rate. It replaces v1's VLDRoutine.
VLDInformWorkout: provides a list of all workout events. It replaces v1's VLDFitness.
VLDInformIntraday: coming soon provides a list of time series activity data for a given user. It replaces v1's VLDIntraday.

Summary of differences between v1 and Inform records

In v1 records, activityID was used as a unique identifier for each record. That property is called logID in the Inform SDK.
v1 records had lots of properties to hold individual measurements, e.g. VLDBiometrics had dozens of fields including systolic, diastolic, temperature, and spo2. In the Inform records, each individual measurement is represented as a "metric", which has its own value, unit, and origin. See the Metrics section below for more info.
The v1 record field validated is now represented in each metric's origin.
The data in the v1 field sourcePeripheral is now available in source.device.model.
The data in the v1 field originalSource is now available in source.device.manufacturer.
The data in the v1 field intermediarySource is not directly available anywhere, but source.type contains something analogous.

Metrics

Each record metric stores an individual measurement value, along with its unit and origin. Value is an NSNumber and unit is a VLDInformUnit constant. Note that not all units supported in the Validic Inform system are available in the Inform SDK at this time - we will be working to add more as time goes on. Please review the list of constants in VLDInformConstants.h for an up-to-date list of supported metrics and units.

Origin represents the source of the value, and replaces the v1 record field validated:

VLDInformMetricOriginDevice is for metrics that were measured by a device (such as a smart watch, glucometer, etc).
VLDInformMetricOriginManual is for metrics that were manually entered by the end user. These might be less trustworthy, as the user could have entered a value incorrectly.
VLDInformMetricOriginUnknown is for metrics where the origin cannot be reliably determined.

Here's how to get a metric of a specific type from a record:

let bodyWeightMetric = record.metric(with: .bodyWeight);

Bluetooth (ValidicBluetooth)

Model changes

The Inform version of the ValidicBluetooth framework exclusively creates VLDInformRecord-based records. All callback methods and notifications that pass a VLDRecord subclass in v1 will pass a VLDInformMeasurement. See Inform Records for the list of subclasses.

Removal of deprecated methods

New delegate callback methods were recently introduced in VLDBluetoothPeripheralControllerDelegate; these methods include a new metadata property. The old methods have been removed and are not available in the Inform SDK.

Additionally, the deprecated bluetoothPeripheralController:didCancelReadingForPeripheral:metadata: method was removed. Instead, when a read operation is cancelled, VLDBluetoothErrorCodeOperationCancelled is passed as the error code to bluetoothPeripheralController:readingFailedForPeripheral:metadata:error:.

Aside from the removal of deprecated methods and the switch to the new VLDInformRecord-based classes, there are no behavior changes in the delegate methods.

Background Reading Notifications

The passive reading and error notifications (kVLDBluetoothPassiveIsReadyToReadNotification, kVLDBluetoothPassiveDidReadNotification, kVLDBluetoothPassiveDidFailNotification) behave the same, except that all records included in the kVLDBluetoothPassiveDidReadNotification notification are now VLDInformRecord subclasses.

Out-of-bounds glucose readings

In v1, readings that indicated a high or low glucose value were transformed into FLT_MAX and -FLT_MAX, respectively. In Inform, high and low glucose readings are transformed into INT_MAX and INT_MIN.

VitalSnap (ValidicOCR)

Model changes

The Inform version of the ValidicOCR framework exclusively creates VLDInformRecord-based records. All callback methods and notifications that pass a VLDRecord subclass in v1 will pass a VLDInformRecord subclass. See Inform Records for more information about the Measurement type.

Delegate Methods

Other than the model changes, the OCR delegate callbacks behave the same as they did in v1.

Initializer changes

The VLDOCRViewController initializer methods take an NSInteger peripheralID argument in v1; in Inform, the initializers take a VLDOCRPeripheral peripheral argument.

LifeScan (ValidicOneTouch)

In v1, the helper method is an initializer on VLDDiabetes; in Inform, the helper method is an initializer on VLDInformMeasurement and the parameter names have changed. Aside from that, functionality is the same.

Apple Health (ValidicHealthKit)

Note that the list of supported HealthKit Sample Types has changed between v1 and Inform. Please review the list returned by the call VLDHealthKitSubscription.supportedObjectTypes().

The VLDHealthKitSubscriptionSet enum, provided in v1, is not included in the Inform SDK. When subscribing to HealthKit sample types you should specifically enumerate all types you want to subscribe to. For example:

// To subscribe to specific sample types (e.g. steps, body mass, and sleep analysis):
let sampleTypes = [HKQuantityType(.stepCount), HKQuantityType(.bodyMass), HKCategoryType(.sleepAnalysis)]
// OR, to subscribe to all supported sample types (not recommended):
let sampleTypes = VLDHealthKitSubscription.supportedObjectTypes() as! Set<HKSampleType>

VLDHealthKitManager.sharedInstance().setSubscriptions(Array(sampleTypes), completion: nil)

Historical Fetch

The members of the VLDHealthKitHistoricalSet enum have been renamed:

VLDHealthKitHistoricalSetRoutine is now VLDHealthKitHistoricalSetSummary
VLDHealthKitHistoricalSetFitness is now VLDHealthKitHistoricalSetWorkout

Notification

The kVLDHealthKitRecordsProcessedNotification will still contain recordType and count keys, but the recordType value will be an Inform record type (NSString) instead of a v1 record type enum.