GuidesAPI ResourcesValidicSupportStatusChangelog
Guides

Cordova Migration Guide

Cordova Inform SDK Wrapper

Suggest Edits

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 APIs before implementing the new Inform SDK modules/frameworks.
  • You must use the Inform version of the session module if you plan to use any other Inform module. The @validic-mobile/cordova-inform-core module replaces validic-cordova-session. All references to ValidicSession must be replaced with InformCore. For example, InformCore.startSession() becomes InformCore.startSession().
    • For example, if you are going to update to the Inform ValidicBluetooth module, you must also update to the Inform ValidicCore module 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 modules in your mobile 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 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. You will not receive session events for v1 anymore, but you will still be able to submit records from v1 modules.

Session (cordova-inform-core)

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 now InformCore.getCurrentUser().
  • The method to submit a record to the Validic backend has been renamed from ValidicSession.submitRecord() to InformCore.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 call submit() 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 and validic:inform:core:recordsubmitfailed.
    • In the validic:inform:core:usersessionended notification, unsubmitted Inform records are available in the event's informRecords key.
  • Starting a session is done by passing a User object instead of individual properties InformCore.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 from InformCore.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's Diabetes, Biometrics, and Weight.
  • InformNutrition: provides a summary of your daily nutritional intake. It replaces v1's Nutrition.
  • InformSleep: provides a record of your sweet, sweet dreams. It replaces v1's Sleep.
  • InformSummary: provides a summary of your daily activity, like steps, calories and heart rate. It replaces v1's Routine.
  • InformWorkout: provides a list of all workout events. It replaces v1's Fitness.
  • 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 called log_id in the Inform SDK.
  • v1 records had lots of properties to hold individual measurements, e.g. Biometrics 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 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 now validic:inform:bluetooth:passivedidread
  • validicOnBluetoothPassiveDidFail is now validic:inform:bluetooth:passivedidfail
  • validicOnBluetoothPassiveIsReadyToRead is now validic: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 now Summary
  • HistoricalSetFitness is now Workout

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 5 days ago