Getting started
Introduction
eideasy-widget is a custom HTML element that you can embed into your website or web application to identify users or create electronic signatures through eID Easy API.
You can see a demo implementation here: https://demo.eideasy.com/login-widget
eideasy-widget also works with Vue.js
Installation
NOTE
We are constantly improving our widget and releasing new versions. Make sure to use the latest version of the widget to get access to the latest signing and authentication methods.
NPM
- Install with npm or Yarn:
npm install @eid-easy/eideasy-widget
or
yarn add @eid-easy/eideasy-widget
- Import
import '@eid-easy/eideasy-widget';
CDN
<script src="https://cdn.jsdelivr.net/npm/@eid-easy/eideasy-widget@2.128.2/dist/full/eideasy-widget.umd.min.js" integrity="sha256-EWm8/9f6oS/xN4W6cKsdXcjDcpJpkGCHWVweCf6l0uI=" crossorigin="anonymous"></script>
Identification Examples
Minimal
<div id="widgetHolder" class="widgetHolder"></div>
const widgetHolder = document.getElementById('widgetHolder');
const eidEasyWidget = document.createElement('eideasy-widget');
const settings = {
clientId: '2IaeiZXbcKzlP1KvjZH9ghty2IJKM8Lg', // Required
countryCode: 'EE', // Required, ISO 3166 two letter country code
redirectUri: 'http://localhost:8080/', // Required
apiEndpoints: {
identityStart: () => 'http://eid-sample-app.test/api/identity/start', // Required
identityFinish: () => 'http://eid-sample-app.test/api/identity/finish', // Requried
},
language: 'et', // ISO 639-1 two letter language code,
sandbox: true,
enabledMethods: {
identification: 'all',
// if you want to enable specific methods, then use
// identification: ['ee-id-login', 'lv-id-login'],
},
onSuccess: function (data) {
console.log(data);
},
onFail: function (error) {
console.log(error);
},
// additional settings for more specific use cases
enabledCountries: ['NO', 'BE', 'EE'],
inputValues: {
idcode: '123456789',
phone: '+37212345678',
},
selectedMethod: 'mid-login',
oauthParamState: 'custom-state-value',
}
Object.keys(settings).forEach(key => {
eidEasyWidget[key] = settings[key];
});
widgetHolder.appendChild(eidEasyWidget);
Settings
Option | Type | Default | Description |
---|---|---|---|
clientId | string | undefined | Required. Get from id.eideasy.com after signing up. |
countryCode | string | undefined | Required. ISO 3166-1 alpha-2 country code |
redirectUri | string | undefined | Required. This gets used for redirects back to your application e.g. when using eParaksts mobile. The value of redirectUri has to match with the "Oauth redirect_uri(s)" setting you provided in your eID Easy admin page. |
apiEndpoints.identityStart | function | undefined | Required. This should return your server endpoint for the identity start request. |
apiEndpoints.identityFinish | function | undefined | Required. This should return your server endpoint for the identity finish request. |
language | string | undefined | Two letter ISO 639-1 language code. |
sandbox | boolean | false | Whether to use the sandbox mode. |
enabledMethods.identification | boolean | string | array | undefined | true or 'all' will enable all methods. If you want to enable specific methods, then provide an array with the methods e.g: ['ee-id-login', 'lv-id-login'] . You can find the available methods (actionType) here /guide/available-methods |
onSuccess | function | undefined | This function gets called when signing or identification succeeds. |
onFail | function | undefined | This function gets called when signing or identification fails. |
enabledCountries | array | undefined | Countries that are shown in the country select. Array of ISO 3166-1 alpha-2 country codes. For example, if you provide ['NO', 'BE'] then only Norway and Belgium will be available in the country select. |
inputValues.idcode | string | '' | Initial value of the idcode input field |
inputValues.phone | string | '' | Initial value of the phone input field |
selectedMethod | string | undefined | Use this to preselect a method for the user. You can find the available methods (actionType) here /guide/available-methods |
oauthParamState | string | undefined | Value of the OAuth state param. |
uiTheme | Object | undefined | Custom UI theme for the widget. See Customizing the widget UI for more information. |
Changing the language after initialization
eidEasyWidget.language = 'lt';
Vue.js (v2)
<template>
<div class="container">
<eideasy-widget
country-code="EE"
language="en"
:sandbox="true"
client-id="2IaeiZXbcKzlP1KvjZH9ghty2IJKM8Lg"
redirect-uri="http://localhost:8080/"
:api-endpoints.prop="apiEndpoints"
:enabled-methods.prop="enabledMethods"
:on-success.prop="(data) => console.log(data)"
:on-fail.prop="(error) => console.log(error)"
/>
</div>
</template>
<script>
import '@eid-easy/eideasy-widget';
export default {
name: 'App',
data() {
return {
apiEndpoints: {
identityStart: () => 'http://eid-sample-app.test/api/identity/start',
identityFinish: () => 'http://eid-sample-app.test/api/identity/finish',
},
enabledMethods: {
identification: 'all',
}
}
},
}
</script>
Signing Examples
A typical signing implementation using the eID Easy API and the eideasy-widget would look like this:
- Prepare the files for signing by sending a server side request to the /prepare-files-for-signing endpoint.
- /prepare-files-for-signing endpoint returns a docId.
- Initialize the eideasy-widget using the docId as described in the sections below.
- End-user selects their desired signing method in the widget and the signing process is started.
- eID Easy server sends a POST request containing doc_id and signer_id to your configured "Signature notification URL" when the user has finished signing the document.
Minimal
<div id="widgetHolder" class="widgetHolder"></div>
const widgetHolder = document.getElementById('widgetHolder');
const eidEasyWidget = document.createElement('eideasy-widget');
const settings = {
countryCode: 'EE', // ISO 3166 two letter country code
language: 'et', // ISO 639-1 two letter language code,
sandbox: true,
clientId: 'SNcycaJFfibUABHrbx6c51YRqSiV76Nz',
docId: 'nQoR4Ypaa3AGaHFmWvGX5PeNEoXMJ2Xx1QVWzPxt',
enabledMethods: {
signature: 'all',
// if you want to enable specific methods, then use
// signature: ['ee-id-login', 'lv-id-login'],
},
selectedMethod: null,
enabledCountries: 'all',
// use these to prefill the input values
inputValues: {
idcode: '',
phone: '00000766',
},
onSuccess: function (data) {
console.log(data);
},
onFail: function (error) {
console.log(error);
},
}
Object.keys(settings).forEach(key => {
eidEasyWidget[key] = settings[key];
});
widgetHolder.appendChild(eidEasyWidget);
Settings
Option | Type | Default | Description |
---|---|---|---|
clientId | string | undefined | Required. Get from id.eideasy.com after signing up. |
countryCode | string | undefined | Required. ISO 3166-1 alpha-2 country code |
language | string | undefined | Two letter ISO 639-1 language code. |
sandbox | boolean | false | Whether to use the sandbox mode. |
enabledMethods.signature | boolean | string | array | undefined | true or 'all' will enable all methods. If you want to enable specific methods, then provide an array with the methods e.g: ['ee-id-login', 'lv-id-login'] . You can find the available methods (actionType) here /guide/available-methods |
onSuccess | function | undefined | This function gets called when signing or identification succeeds. |
onFail | function | undefined | This function gets called when signing or identification fails. |
enabledCountries | array | undefined | Countries that are shown in the country select. Array of ISO 3166-1 alpha-2 country codes. For example, if you provide ['NO', 'BE'] then only Norway and Belgium will be available in the country select. |
inputValues.idcode | string | '' | Initial value of the idcode input field |
inputValues.phone | string | '' | Initial value of the phone input field |
uiTheme | Object | undefined | Custom UI theme for the widget. See Customizing the widget UI for more information. |
Changing the language after initialization
eidEasyWidget.language = 'lt';
Vue.js (v2)
<template>
<div class="container">
<eideasy-widget
country-code="EE"
language="en"
:sandbox="true"
doc-id="nQoR4Ypaa3AGaHFmWvGX5PeNEoXMJ2Xx1QVWzPxt"
client-id="SNcycaJFfibUABHrbx6c51YRqSiV76Nz"
:enabled-methods.prop="enabledMethods"
:on-success.prop="(data) => console.log(data)"
:on-fail.prop="(error) => console.log(error)"
/>
</div>
</template>
<script>
import '@eid-easy/eideasy-widget';
export default {
name: 'App',
data() {
return {
enabledMethods: {
signature: 'all',
}
}
},
}
</script>
Vue.js (v3)
See the following demo project: https://github.com/eideasy/widget-usage-in-vue-3
React
See the following demo project: https://github.com/eideasy/widget-usage-in-react
Customizing the Widget UI
You can customize the widget UI by providing a custom theme object to the widget. The theme object can contain the following properties on uiTheme
object. Pass the uiTheme
object to the widget settings when initializing the widget.
const settings = {
countryCode: 'EE', // ISO 3166 two letter country code
language: 'et',
// Other settings...
uiTheme: {
// Primary color of the widget
colorPrimary: '#d51111',
// Secondary color of the widget
colorSecondary: '#00ff00',
// Text color
textColor: '#0000ff',
// Submit button text color
buttonTextColor: 'rgb(6,192,164)',
// Submit button background color
buttonColor: '#000000',
// Submit button background color on hover
buttonColorHover: '#252323',
// Input label color
inputLabelColor: '#04048d',
// Font family used for the widget
fontFamily: '"Gill Sans", sans-serif',
// Font size used for the widget
fontSize: '16px',
// Font weight used for the widget
fontWeight: 'bold',
},
}
Object.keys(settings).forEach(key => {
eidEasyWidget[key] = settings[key];
});
widgetHolder.appendChild(eidEasyWidget);
The values on each of the uiTheme
above are for example purposes and can be changed to your liking.