Migration Guide [v1 -> v2]
Trust1Connector Javascript migration guide: from v1 to v2
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.
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.
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
scriptssection 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:
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.
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.
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!
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.
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
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 5yr ago