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
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.100.0/dist/full/eideasy-widget.umd.min.js" integrity="sha256-iq10cWY4pt6+4DpGyIqhuB+J4kEfZIG6z7QKi8VoObc=" 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. |
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 |
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