Getting started

Introduction

eideasy-widget is a custom HTML elementopen in new window that you can embed into your website or web application to identify users or create electronic signatures through eID Easyopen in new window API.

You can see a demo implementation here: https://demo.eideasy.com/login-widgetopen in new window

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

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.153.0/dist/full/eideasy-widget.umd.min.js" integrity="sha256-o73UycVJ2nt50aoj+JIdd0xYkTu5rPcjzZbC4lveVpk=" crossorigin="anonymous"></script>

Set up

eID Easy widget uses iframes to communicate with some of the browser extensions and OS level components. To ensure that the widget works correctly, you need to whitelist the domain where you plan to embed the widget as follows:

In the self-service portal, navigate to My Webpagesopen in new window, scroll to the website you wish to use the widget for and click "Edit".
Scroll to the section "Allowed iframe parent hostnames"
Enter the hostname of the website where you plan to embed the widget. For example, if you plan to embed the widget on https://example.com/subpage, then enter https://example.com.
Done! You can now embed the widget on the specified website.

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-2open in new window 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-1open in new window language code.
sandbox	boolean	false	Whether to use the sandboxopen in new window 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-2open in new window 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-signingopen in new window 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-2open in new window country code
language	string	undefined	Two letter ISO 639-1open in new window language code.
sandbox	boolean	false	Whether to use the sandboxopen in new window 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-2open in new window 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-3open in new window

React

See the following demo project: https://github.com/eideasy/widget-usage-in-reactopen in new window

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.

# Getting started

# Introduction

# Installation

# NPM

# CDN

# Set up

# Identification Examples

# Minimal

# Settings

# Changing the language after initialization

# Vue.js (v2)

# Signing Examples

# Minimal

# Settings

# Changing the language after initialization

# Vue.js (v2)

# Vue.js (v3)

# React

# Customizing the Widget UI

Getting started

Introduction

Installation

NPM

CDN

Set up

Identification Examples

Minimal

Settings

Changing the language after initialization

Vue.js (v2)

Signing Examples

Minimal

Settings

Changing the language after initialization

Vue.js (v2)

Vue.js (v3)

React

Customizing the Widget UI