Migration Guide [v1 -> v2]

Search…

Trust1Connector Javascript migration guide: from v1 to v2

Introduction
This document is meant to help you migrate a T1C Core v1 application to T1C Core v2.
It provides a number of steps to be completed to correctly migrate.
Migration Steps
Step 0: Preparation
In order to be able to communicate with the distribution server, and download containers, you must have a valid and active contract with the T1C-DS v2 API in the marketplace for your environment (ACC/PROD).
When that is ok, use the DS Dashboard to configure the required containers and whitelisting settings for your application.
The DS Dashboard v2 provides an admin interface in order to keep track of devices used for your applications. The DS Dashboards provides you with demographic data and an admin interface in order to enable/disable containers in your projects. 
An important step for the T1C v2 release is that you add all domains where you use the Trust1Connector. The T1C allows only requests coming from known domains and thus domains can be added later on easily by using the DS Dashboard.
Step 1: Update the dependency
First of all, update the T1C-JS dependency. Usually this is pulled in via NPM, so either update package.json's trust1connector entry to the latest version, or remove it and run npm install trust1connector to automatically get the latest version.
Make sure the new version is loaded into your web application. How this is done varies on the actual implementation:
Angular 1.x applications usually load the library via a <script> tag in index.html, make sure this script tag is still correct
Angular2+ applications have an import defined in the scripts section of .angular-cli.json, make sure this is correct
You can test if the library is loaded correctly by starting a development server, opening the browser console and typing GCLClient + enter. If this returns a log of the GCLClient, everything is working.
Don't hesitate to have a look at our example repositories (implementing most of the functionality) on Github:
​Angular 1.x example​
​Angular 2.x example​
​Plain html example​
Step 2: Update the GCLConfig creation
The creation of the GCLConfig was changed in v2, some parameters have changed name, etc..
It is now also possible to initialize the library with a JWT instead of an API key. This is especially the case for Single Page applications or when you want you back-end to exchange the API key for a temporary signed JWT.
All configuration options are documented in the Trust1Connector v2 Gitbook documentation. Adapt your current config as necessary.
Step 3: Make sure the initialize method is called
Older applications may still be using the constructor based creation method for setting up a new client. This is no longer supported and should be avoided at all costs. The library now provides and initialisation method that should be called instead. This method will handle synchronisation and container downloading; the constructor-based creation will not, leaving you with an unusable client.
You must use the initialize() method. See the documentation for details.
Step 4: Catch "incompatible version" → code 301/302
During the initialisation of the library, T1C-JS will check if there is a compatible version of the GCL installed. This can have three outcomes:
1.GCL v2+ is installed and all is well → initialisation will continue
2.GCL v1 is installed → an error will be thrown with status code 301
3.No GCL is found → an error will be thrown with status code 302
If one of these two errors occurs (301 - incompatible version or 302 - no installation found), the error thrown will have a minimal client attached to it.
This client can be used to download a core v2 installer.
It is up to the application to catch these errors and react accordingly!
Step 5: Catch possible container download errors → code 903
When initialising the library, the GCL checks the list of containers it has available against the list required by the application, and downloads missing containers if necessary. This download process will automatically retry a failed container download once, but if it fails again will report an error code 903 (container download error) to the application.
This means that one of the containers required by the application is not available and therefore the application cannot offer full functionality. 
The correct way to deal with this is left up to the application.
Step 6: Check for possible interface changes (should be minimal)
Once initialised, the interface changes are very minor. Only the PKCS11 container was changed slightly, all other container calls remained the same. 
Check the functionality of all calls to the JS-Lib to make sure everything is working as expected
Step 7: If initialised with JWT, catch JWT expiration errors and make sure refresh works
When T1C-JS is initialised with a JWT token and this token expires, the library has no way to obtain a new token and will therefore report an error with code 205 (JWT token expired).
When the application receives this error, it must obtain a new token and reinitialise the library with the new token, then re-execute the request.
When T1C-JS is initialised with an API key, it will handle JWT refresh autonomously so no action is necessary here.

Last modified 4yr ago

Copy link

Contents

Introduction

Migration Steps

Step 0: Preparation

Step 1: Update the dependency

Step 2: Update the GCLConfig creation

Step 3: Make sure the initialize method is called

Step 4: Catch "incompatible version" → code 301/302

Step 5: Catch possible container download errors → code 903

Step 6: Check for possible interface changes (should be minimal)

Step 7: If initialised with JWT, catch JWT expiration errors and make sure refresh works