Biometric login

Use this integration for allowing your user to login to the app using biometric login (Touch / Face ID).

Introduction

This module enables users to save their credentials on their device and unlock it using biometric authentication (such as Touch ID or Face ID).

Where to find: startiapp.Biometrics

Methods

scan 

scan(title?: string, reason?: string): Promise<boolean>

Start scanning for biometrics.

The title and reason are displayed to the user on some devices. It’s recommended to always provide descriptive text, even though it may not be displayed on all devices.

The method returns true if the user is successfully recognized, otherwise it returns false.

getAuthenticationType 

getAuthenticationType(): Promise<string>

Get the type of biometrics used. Possible return values are: None, Fingerprint and Face.

setSecuredContent 

setSecuredContent(content: string | object): void

Set the content to be secured.

‘content’ refers to items that can be secured on the device, such as passwords or full objects.

getSecuredContent 

getSecuredContent(title?: string, reason?: string): Promise<object>

Get the secured content if the user is successfully recognized.

The title and reason are displayed to the user on some devices. It’s recommended to always provide descriptive text, even though it may not be displayed on all devices.

hasSecureContent 

hasSecureContent(): Promise<boolean>

Check if there is any secured content on the device.

removeSecuredContent 

removeSecuredContent(): void

Remove any secured content on the device.

getUsernameAndPassword 

getUsernameAndPassword(title?: string, reason?: string): Promise<{ username: string?, password: string? }>

Get the stored username and password.

The title and reason are displayed to the user on some devices. It’s recommended to always provide descriptive text, even though it may not be displayed on all devices.

setUsernameAndPassword 

setUsernameAndPassword(username: string, password: string): void

Set the username and password to be stored on the device.

removeUsernameAndPassword 

removeUsernameAndPassword(): void

Remove the stored username and password.

hasUsernameAndPassword 

hasUsernameAndPassword(): Promise<boolean>

Check if there is any stored username and password on the device.

addEventListener 

addEventListener(type: BiometricsEvents, callback: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void

Listen for biometrics events.

removeEventListener 

removeEventListener(type: BiometricsEvents, callback: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void

Remove a biometrics event listener.

Examples

Save login information

Save login information upon submitting login form. This function does not check if login is successfull, thus you should create a method to remove login information from storage if login fails.

//Submit button click event
document.getElementById("submit").addEventListener('click', async function(e) {
  //Prevent form from submitting
  e.preventDefault();

  let hasContent = await startiapp.Biometrics.hasUsernameAndPassword();
  let useBiometrics = false;
  const loginForm = document.getElementById("login-form");
  const usernameField = document.getElementById("userLogin_email");
  const passwordField = document.getElementById("userLogin_password");
  const username = usernameField.value;
  const password = passwordField.value;

  //Validation of data, here we check if the form fields is empty
  //if so we submit the form without saving the login information.
  //You can implement your own error handling.
  if(username.length == 0 || password.length == 0) {
    loginForm.submit();
    return;
  }

  //Prompt user if they want to use biometrics, only if no login is saved
  if (!hasContent) {
    useBiometrics = confirm("Use biometrics?");
  }

  //Save information if none exists and user confirmed or
  //update if previous login is already saved
  if ((useBiometrics && !hasContent) || hasContent) {
      await startiapp.Biometrics.setUsernameAndPassword(username, password);
  }

  loginForm.submit();
})

HTML form example code:

<form id="login-form" method="post" action="/login">
	<input type="email" id="userLogin_email" name="email_address">
	<input type="password" id="userLogin_password" name="password">
	<button id="submit" name="userLogin" type="submit"ยจ>
</form>

Login with biometrics

Function to log in with biometrics using stored credentials. Function could be called upon app start or any different event.

async function checkAndLogInWithBiometrics() {
  const loginForm = document.getElementById("login-form");
  const usernameField = document.getElementById("userLogin_email");
  const passwordField = document.getElementById("userLogin_password");

  hasContent = await startiapp.Biometrics.hasUsernameAndPassword();

  //Return if already logged in or no login information is stored.
  //loggedIn variable should be globally set outside this function.
  if (!hasContent || loggedIn) {
    return;
  }

  //Get the login information
  try {
    const loginData = await startiapp.Biometrics.getUsernameAndPassword(
      "Use biometrics.",
      "Access needed to log in.",
    );
  } catch(e) {
    alert("Could not login with biometrics.");
    return
  }

  //Fill login form fields and submit form
  usernameField.value = loginData.username;
  passwordField.value = loginData.password;
  loginForm.submit();
}

Events

How to listen for events.

This module does not currently offer any events.

← App
Calendar →