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 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 all 1.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 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 months ago