Cordova Migration Guide
Cordova Inform SDK Wrapper
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 so that existing user records are not lost.
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
This guide has been corrected
A prior version of this guide incorrectly stated that the Inform Session in the Cordova wrapper supports both v1 and Inform data models for backwards compatibility. This was incorrect -- it applies to the Inform SDK native SDKs, but not the wrappers. We're terribly sorry for any confusion this may have caused and if you have any questions please reach out to our Customer Support team.
When updating to the v2.x.x Inform SDK, all of the Validic Cordova modules in your project must be updated to v2.x.x at the same time.
- "Inform SDK" refers to the Validic Cordova SDK release versions that are
2.0.0
and newer. "v1 SDK" refers to all1.x.x
versions of the Validic Cordova SDK. - The Inform SDK only supports v2 (Inform) organizations. If you are still using Validic's v1 Legacy API system, please contact support to migrate to Inform before implementing the new frameworks.
- When updating to the v2.x Inform SDK, all Validic Cordova modules in your project must be updated to v2.x at the same time. You cannot mix and match v1.x and v2.x Cordova modules in your project.
Installation
The Inform Cordova SDK is available via Validic's Artifactory instance. The Validic Mobile Portal will eventually be phased out and does not host the Inform SDKs. Please contact Validic Support for instructions to get set up in Artifactory.
To install into an existing Cordova project using yarn:
yarn add @validic-mobile/cordova-inform-core --registry https://validic.jfrog.io/artifactory/api/npm/mobile-npm-release/
In order to use any Validic Inform SDK, all Validic SDKs in your project must be updated to Inform at the same time.
Session (cordova-inform-core)
Valid user session required
A valid session is required in order to use any of the modules in the Validic SDK.
A Validic user must first be provisioned using the Validic API. Then you can start a session in the SDK using their Inform user credentials.
All mobile operations will fail if a valid user session has not been started first.
The @validic-mobile/cordova-inform-core
replaces validic-cordova-session
. All references to ValidicSession
should be replaced with InformCore
. For example, ValidicSession.startSession()
becomes InformCore.startSession()
.
Method Changes
Some methods have been renamed from v1 SDK to Inform SDK.
- The method to get the current user has been renamed:
ValidicSession.getUser()
in v1 is nowInformCore.getCurrentUser()
. - The method to submit a record to the Validic backend has been renamed from
ValidicSession.submitRecord()
toInformCore.submit()
. - There is not currently an Inform replacement for the
ValidicSession.submitRecords()
method for submitting multiple records. To submit multiple records in Inform, loop over the array of records and callsubmit()
for each one. - There is no Inform replacement for the
version
property at this time. - All methods now return a Promise.
Logging
Validic debug logging has not changed in the Inform SDKs. You can find more details in Logging.
User Session
The User object properties have been changed from v1 for consistency with other properties and our other wrappers.
Old (v1 SDK):
export interface User {
orgId: string;
userId: string;
accessToken: string;
}
New (Inform SDK):
export interface User {
organizationID: string;
userID: string;
accessToken: string;
}
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.
- Some notifications are named differently in the Inform SDKs:
- When listening for Inform record submission success/failure notifications, use
validic:inform:core:recordsubmitted
andvalidic:inform:core:recordsubmitfailed
. - In the
validic:inform:core:usersessionended
notification, unsubmitted Inform records are available in the event'sinformRecords
key.
- When listening for Inform record submission success/failure notifications, use
- Starting a session is done by passing a
User
object instead of individual propertiesInformCore.startSession({organizationID: "", userID: "", accessToken: ""})
- Default User behavior was not migrated to Inform SDK. You must use a valid user session.
ValidicSession.isSessionActive()
was not ported. Client's should check if the User resolved fromInformCore.getCurrentUser()
is null
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 InformRecord
- all record classes inherit from this class. The subclasses are:
InformMeasurement
: provides point in time measurements, like height, weight, blood pressure, glucose, etc. It replaces v1'sDiabetes
,Biometrics
, andWeight
.InformNutrition
: provides a summary of your daily nutritional intake. It replaces v1'sNutrition
.InformSleep
: provides a record of your sweet, sweet dreams. It replaces v1'sSleep
.InformSummary
: provides a summary of your daily activity, like steps, calories and heart rate. It replaces v1'sRoutine
.InformWorkout
: provides a list of all workout events. It replaces v1'sFitness
.- Intraday is not supported in the Cordova wrapper. If you are interested in using intraday, please reach out to Validic Support.
Summary of differences between v1 and Inform records
- In v1 records,
activity_id
was used as a unique identifier for each record. That property is calledlog_id
in the Inform SDK. - v1 records had lots of properties to hold individual measurements, e.g.
Biometrics
had dozens of fields includingsystolic
,diastolic
,temperature
, andspo2
. 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 insource.device.model
. - The data in the v1 field
originalSource
is now available insource.device.manufacturer
. - The data in the v1 field
intermediarySource
is not directly available anywhere, butsource.type
contains something analogous.
Metrics
Each record metric stores an individual measurement value, along with its unit and origin. Value is a number
and unit
is a string. 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.
Origin
represents the source of the value, and replaces the v1 record field validated
:
device
is for metrics that were measured by a device (such as a smart watch, glucometer, etc).manual
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.unknown
is for metrics where the origin cannot be reliably determined.
Bluetooth (cordova-inform-ble)
The @validic-mobile/cordova-inform-ble
package replaces cordova-validic-ble
.
Model changes
The Inform version of the ValidicBluetooth framework exclusively creates objects compatible with the InformRecord
interface. All callback methods and notifications that pass a Record
-like interface in v1 will pass an InformMeasurement
.
Method changes
The peripheralID
parameter has been hoisted out of the pairPeripheral
and read
options parameter, into its own dedicated parameter. Instead of calling read({peripheralID: 1})
, use read(1, {/_ other options _/})
.
Foreground and background events
The event names for passive events have changed.
validicOnBluetoothPassiveDidRead
is nowvalidic:inform:bluetooth:passivedidread
validicOnBluetoothPassiveDidFail
is nowvalidic:inform:bluetooth:passivedidfail
validicOnBluetoothPassiveIsReadyToRead
is nowvalidic:inform:bluetooth:readytoread
Inform Records are stored in the informRecords
property.
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
.
Apple Health (cordova-inform-healthkit)
The @validic-mobile/cordova-inform-healthkit
package replaces validic-cordova-healthkit
.
Note that the list of supported HealthKit Sample Types has changed between v1 and Inform. Please review the SampleTypes
enum.
The records processed event name has changed from validicOnHealthKitRecordsProcessed
to validic:inform:healthkit:recordsprocessed
Historical Fetch
The members of the HistoricalSet
enum have been renamed:
HistoricalSetRoutine
is nowSummary
HistoricalSetFitness
is nowWorkout
Event
The validic:healthkit:onrecords
will still contain recordType
and count
keys, but the recordType
value will be an Inform record type (string) instead of a v1 record type enum (number).
Health Connect (cordova-inform-healthconnect)
The @validic-mobile/cordova-inform-healthconnect
package is new, but it effectively replaces both cordova-validic-aggregator-fit
and cordova-validic-aggregator-shealth
which do not have Inform equivalents.
The interface for the new package is different than the previous packages, so please review the documentation closely for information on how to implement it.
Updated about 16 hours ago