This package has been deprecated

Author message:

This package has been deprecated

GetID WEB SDK

Table of contents

• Overview
• Getting started
  • Requirements
  • Camera usage description
• Installation
  • Obtaining JWT
  • HTML markup
• Initializing
• Customization
  • Callbacks
  • Flow
  • Fields
  • Verification Types
  • Supported countries and types of documents
  • Form grid
• Localization
  • Dictionary
• External libraries

Overview

The SDK provides functionality to upload user personal data to GetID server. Also, this SDK provides a possibility to add a customisable form component for users to enter text information about themselves or/and upload (capture) ids and face photos.

Getting started

Requirements

• node 12.15.0
• browsers and features we support:

OS	Browser	Version	Photos
iOS	Safari	13 or higher	✔️
iOS	Chrome	84 or higher	―
iOS	Firefox	27 or higher	―
Android	Chrome	83 or higher	✔️
Android	Samsung Internet	12 or higher	✔️
Android	Firefox	68 or higher	✔️
Android	Native	12 or higher	―
Android	UC	13 or higher	―
Android	Opera	58 or higher	✔️
Android	Web browser	3 or higher	―
Desktop mac	Safari	13 or higher	✔️
Desktop mac	Chrome	83 or higher	✔️
Desktop mac	Firefox	78 or higher	✔️
Desktop mac	Opera	69 or higher	✔️
Desktop mac	Edge	83 or higher	✔️
Windows	Edge	83 or higher	✔️
Windows	Chrome	83 or higher	✔️
Windows	Opera	69 or higher	✔️
Windows	Firefox	78 or higher	✔️

Obtaining an API key

In order to start using GetID SDK, you will need an API key and API url. In your GetID Dashboard, you can get and set API key and SDK key. API key - grants you access to public API calls and SDK API calls. SDK key - grants you access to only SDK API calls. For security reasons, strongly recommended use "SDK key" in your SDK.

Camera usage description

The SDK uses the camera for capturing photos during verification. The app is responsible for describing the reason for using the camera. For better verification try to hold the document exactly within the frame while capturing photo. Do not place document in inverted alignment or at an angle. Please avoid too dark or bright lightning. In process of capturing selfie be sure that there is no more than one face in a photo.

Installation

• NPM style import

npm install --save getid-web-sdk

// ES6 module import
import {init} from 'getid-web-sdk'

// commonjs style require
const getId = require('getid-web-sdk')

• CDN include sdk as regular script tag. (please contact technical support for CDN link)

<script src='getid-web-sdk-vx.x.x.min.js'></script>

In case you want to automatically keep up with latest version of sdk cdn script, we advice to use our launcher.js Just include the script in your html page, it will insert the latest script into the tag of your page. Example:

<script src='launcher.min.js'></script>

it will handle versioning and sdk script loading and init. Load it the same way you would load with sdk init

window.getidWebSdk.init(config, token);

Obtaining JWT

For security reasons, you will need to generate and include a short-lived JSON Web Token (JWT) every time you initialise the SDK. To generate JWT make a post request with api key in header on your designated api url: Make sure to pass the whole response object on init function as token param

Customer Id (optional)

In case you don't want your clients to complete verification more than once you can pass customerId param when generating jwt token.

import { init } from 'getid-web-sdk'
const config = {_your_config_here_}
 
const token = post YOUR_SDK_SERVER_BACKEND_URL/sdk/token
headers: {
    apiKey: YOUR_API_KEY
},
body: {
    customerId: YOUR_CUSTOMER_ID
}
init(config, token);

In case you are using our launcher script, initialize sdk like you would with simple sdk script

window.getidWebSdk.init(config, token);

---

Also, you can use SDK built-in function createPublicTokenProvider that you can import along with init. In this scenario, apiKey must be passed to init method along with SDK config and API url.

import { init, createPublicTokenProvider } from 'getid-web-sdk'
const config = {_your_config_here_}
const token = createPublicTokenProvider(config.apiUrl, config.apiKey, customerId)
init(config, token);

In case you are using our launcher script, createPublicTokenProvider will be accessible via window.getidWebSdk object.

const config = {_your_config_here_}
const token = window.getidWebSdk.createPublicTokenProvider(config.apiUrl, config.apiKey, customerId)
window.getidWebSdk.init(config, token);

Our team strongly encourages making a JWT call using server-side code and first option of obtaining a .

• Tokens expire 90 minutes after creation. (length of a token's life is a matter of configuration)

HTML markup

In case you are planning to use getId form, place an empty element for the interface to mount itself on:

<div id='getid-component'></div>

Place the snippet in the bottom of your index file.

Initializing

In order to initialize an SDK instance, simply call:

import { init } from 'getid-web-sdk'
const config = {
  apiUrl: 'YOUR_URL',
  containerId: 'getid-component',
  [{ component: ['ThankYou'] }],
}; 
 
const token = _your_jwt_here_;
init(config, token);

For more sophisticated initialization with more customization check this example below:

import { init } from 'getid-web-sdk'
const config = {
  apiUrl: 'YOUR_URL',
  flow: [ { component: ['Form'] },
          { component: ['ThankYou'] } ],
  containerId: 'getid-component',
  fields: [
      {
        type: 'text',
        label: 'First Name',
        name: 'First Name',
        value: 'John',
        required: false
      },
      { 
        type: 'text',
        label: 'Last Name',
        name: 'Last Name',
        value: 'Doe',
        required: false
      },
      { 
        type: 'text',
        label: 'Email',
        name: 'Email',
        required: false
      },
  ],
  onComplete: function(data) {
    console.log("everything is complete" + data)
  },
  onFail: function(error) {
   console.log("something went wrong" + error)
  }
}; 
 
const token = _your_jwt_here_;
init(config, token);

Customization

Flow

Flow is required parameter. You can customize which steps that will be present in your getId widget. Available:

• Consent - Client gives their consent to their Personal data processing.
• Form - Form with basic personal data fields (first name, last name, email, gender etc)
• CountryAndDocument - country of document and document type selection view
• IdCapture - web camera view. can consist of up to 2 views, depending on the type of document. i.e in case of id card, there are two views: frond and back side.
• IdSelfie - web camera view. user will have to take a selfie.
• ThankYou - Thank you page, informs client about successful state of the validation.

Example:

import { init } from 'getid-web-sdk'
const config = {
  apiUrl: 'YOUR_URL',
  containerId: 'getid-component',
  flow: [ { component: ['Form'] },
          { component: ['CountryAndDocument'] },
          { component: ['ThankYou'] } ],
}; 
 
const token = _your_jwt_here_;
init(config, token);

Fields

Fields are required in case Form step is active. On form view, you can choose which fields to show to client.

Currently, we support 4 input types:

• text: plain string
• date: Date represented as a string in ISO 8601 format
• file: any format max 6MB
• select: string in ISO 3166-1 alpha-2 format (Wiki)
• checkbox: boolean

Important note:

If you want to add custom file fields on the form step, please refrain from using reserved field names such as:

• front
• back
• selfie
• selfie-video

These can only be used to send out document photos (front and back), selfie (selfie) and liveness recording (selfie video). Unless you want to use those file inputs to do just that, please opt for some other naming.

Optionally, you can pre-populate some fields by known values. Pass the values according to formats listed in the table above. You can set field's required option. All fields are set as required: true by default.

Also you can set already prefilled invisible fields by adding hidden flag to each field you want ot hide. Those fields will be not accessible for client, but included in total form result

Example:

import { init } from 'getid-web-sdk'
const config = {
  apiUrl: 'YOUR_URL',
  containerId: 'getid-component',
  flow: [ { component: ['Form'] },
          { component: ['CountryAndDocument'] },
          { component: ['ThankYou'] } ],
  fields: [
     // pre-populated and not visible
      {
        type: 'text',
        title: 'First Name',
        value: 'John',
        hidden: true,
        required: false
      },
      // this one client will have to fill in
      {
        type: 'select',
        title: 'Country',
        required: true
      },
  ],
}; 
 
const token = _your_jwt_here_;
init(config, token);

Callbacks

All callbacks are optional, you can specify yours on init call. getId web SDK allows several callbacks:

• onComplete function - callback executed on Success event (client has been successfully verified)
• onError function - callback executed on fail event (client has not been successfully verified) - we will tell you why in error.message - now it's up to you to handle this accordingly
• OnExists function - callback executed when we detect existing application with id that was passed on init
• onSortDocuments function - callback executing for sorting or filtering supported documents list. Function takes two parameters: country - string in ALPHA-2 format(lowercase) and documents: array of supported document types for current country. You should return an array of desired document types(in desired order) for every country if you don't want to display some countries just return empty array.

Example:

import { init } from 'getid-web-sdk'
const config = {
  apiUrl: 'YOUR_URL',
  containerId: 'getid-component',
  onComplete: function(data) {
    console.log("everything is complete" + data)
  },
   onFail: function(error) {
   console.log("something went wrong" + error)
  },
  onSortDocuments: function(coutry, documents) {
   const desiredCountries = ['cz', 'dk', 'es', 'hr', 'pl', 'at', 'be', 'bg', 'de', 'ee'];
   const desiredDocuments = ['id-card', 'passport', 'driving-licence', 'residence-permit'];
 
   if (desiredCountries.includes(country) return desiredDocuments;
   
   return [];
  }
}; 
 
const token = _your_jwt_here_;
init(config, token);

Verification types

You may also configure desirable types of verification by simple passing a verificationTypes (array of strings) property in config.

Example:

import { init } from 'getid-web-sdk'
const config = {
  apiUrl: 'YOUR_URL',
  containerId: 'getid-component',
  verificationTypes: ['F', 'E', 'W'],
}; 
 
const token = _your_jwt_here_;
init(config, token);

Where 'F' stands for 'face matching', 'E' stands for 'extraction' and 'W' stands for watchlists.

Supported countries and types of documents

In process of passing flow you have to choose one of the offered document types. Depending on country user is allowed to select one or other document type. You can pass user's document data via sdk init method. This will pre-fill document and country view fields with passed params. In case passed values do not match getId supported list of countries and/or documents, sdk will proceed with empty values, and client will be able to try to select other options.

Console will show error This country is not supported or This document type is not supported.

For now we mostly support these documents:

• passport,
• id-card,
• visa,
• driving-licence,
• residence-permit,
• internal-passport.

Example:

import { init } from 'getid-web-sdk'
const config = {
  apiUrl: 'YOUR_URL',
  containerId: 'getid-component',
  flow: [ { component: ['Form'] },
          { component: ['CountryAndDocument'] },
          { component: ['ThankYou'] } ],
  documentData: [
   {
     name: 'Country',
     value: 'ee',
   },
   {
     name: 'DocumentType',
     value: 'passport',
   },
 ],
}; 
 
const token = _your_jwt_here_;
init(config, token);

For some documents (internal-passport) you will have to capture photo from both sides (front and back).

Form grid

You can also specify form width within the config

Types are: narrow or wide

Example:

 import { init } from 'getid-web-sdk'
 const config = {
   apiUrl: 'YOUR_URL',
   containerId: 'getid-component',
   flow: [ { component: ['Form'] },
           { component: ['CountryAndDocument'] },
           { component: ['ThankYou'] } ],
   formType: 'narrow',
 }; 
 
 const token = _your_jwt_here_;
 init(config, token);

Localization

Sdk can be localised. Please contact technical support for more details.

Dictionary

Example of using dictionary key.

 import { init } from 'getid-web-sdk'
 const config = {
   apiUrl: 'YOUR_URL',
   dictionary: '_lang_key_',
   flow: [ { component: ['Form'] },
           { component: ['CountryAndDocument'] },
           { component: ['ThankYou'] } ],
 }; 
 
 const token = _your_jwt_here_;
 init(config, token);

External libraries

Current software is using external libraries, which are released under MIT license:

 Copyright (c) 2020 GetID

 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:

 The above copyright notice and this permission notice shall be included in
 all copies or substantial portions of the Software.

 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.