# Getting started

# Introduction

eideasy-widget is a custom HTML element (opens new window) that you can embed into your website or web application to identify users or create electronic signatures through eID Easy (opens new window) API.

You can see a demo implementation here: https://demo.eideasy.com/login-widget (opens new window)

eideasy-widget also works with Vue.js

# Installation

# NPM

  1. Install with npm or Yarn:
npm install @eid-easy/eideasy-widget

or

yarn add @eid-easy/eideasy-widget
  1. Import
import '@eid-easy/eideasy-widget';

# CDN

  <script src="https://cdn.jsdelivr.net/npm/@eid-easy/eideasy-widget@2.59.1/dist/full/eideasy-widget.umd.min.js" integrity="sha256-42rw5apyNwneGgu5eUyPIEgDhnKDzTfIm+kO1x3ecnQ=" 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 (opens 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-1 (opens new window) language code.
sandbox boolean false Whether to use the sandbox (opens 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-2 (opens 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.

# 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:

  1. Prepare the files for signing by sending a server side request to the /prepare-files-for-signing (opens new window) endpoint.
  2. /prepare-files-for-signing endpoint returns a docId.
  3. Initialize the eideasy-widget using the docId as described in the sections below.
  4. End-user selects their desired signing method in the widget and the signing process is started.
  5. 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 (opens new window) country code
language string undefined Two letter ISO 639-1 (opens new window) language code.
sandbox boolean false Whether to use the sandbox (opens 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-2 (opens 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

# 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>