Integration guide

There are four steps to follow for the integration:

Install the SDK
Create the share session
Retrieve the profile

This section will explain how to install the SDK and create a session.

Install the SDK

Once you have added the Yoti SDK dependency to your project, it’s time to initialise a Yoti client as shown in the code snippet below.

Once you have a working Yoti QR/button, you can move on to installing the SDK.

To successfully integrate you will need the following information about your application from Yoti Hub:

SDK ID
Your application key pair

The Yoti SDKs are available via popular dependency management systems. Further details can be found on the pages of the specific projects.

To install the Yoti SDK:

// Get the Yoti Node SDK library via the NPM registry

npm install -S -E yoti

// If you are using Maven, add the following dependency:

</dependency>

// If you are using Gradle, add the following dependency:

compile group: 'com.yoti', name: 'yoti-sdk-api', version: '3.8.0'

// Get the Yoti PHP SDK library via a Composer package

composer require yoti/yoti-php-sdk

// To install the Yoti NuGet package you will need to install NuGet.

// To import the latest Yoti SDK into your project, enter the following

// command from NuGet Package Manager Console in Visual Studio:

Install-Package Yoti

// For other installation methods, see https://www.nuget.org/packages/Yoti

// Simply add this as an import:

import "github.com/getyoti/yoti-go-sdk/v3"

// Or add the following line to your go.mod file

require github.com/getyoti/yoti-go-sdk/v3 v3.12.0

Once you have added the Yoti SDK dependency to your project, you can initialise the Yoti Digital Identity Client as shown below:

const Yoti = require('yoti')

const CLIENT_SDK_ID = 'YOTI_CLIENT_SDK_ID'

const PEM_PATH = 'YOTI_KEY_FILE_PATH'

const PEM_KEY = fs.readFileSync(PEM_PATH)

const yotiClient = new Yoti.DigitalIdentityClient(CLIENT_SDK_ID, PEM_KEY)

import java.io.File;

import com.yoti.api.client.FileKeyPairSource;

import com.yoti.api.client.DigitalIdentityClient;

DigitalIdentityClient client = DigitalIdentityClient.builder()

.withClientSdkId("<YOTI_CLIENT_SDK_ID>")

.withKeyPairSource(FileKeyPairSource.fromFile(new File("<YOTI_KEY_FILE_PATH>")))

.build();

}

<?php

require_once './vendor/autoload.php';

$client = new \Yoti\DigitalIdentityClient('YOTI_CLIENT_SDK_ID', 'YOTI_KEY_FILE_PATH');

const string SDK_ID = "YOTI_CLIENT_SDK_ID";

const string PEM_PATH = "YOTI_KEY_FILE_PATH";

var privateKeyStream = System.IO.File.OpenText(PEM_PATH);

var yotiClient = new YotiDigitalIdentityClient(SDK_ID, privateKeyStream);

sdkID := "YOTI_CLIENT_SDK_ID";

pemKey, _ := ioutil.ReadFile("YOTI_KEY_FILE_PATH")

client, err := yoti.NewDigitalIdentityClient(sdkId, pemKey)

if err != nil {

return nil, err

}

Using Yoti SDK

The description on how to use the SDK can be found here:

Please read the above for a full description and understanding, below, we’ll provide examples on how those requests will expose the new functionality.

const identityProfileRequirements = {

trust_framework: 'UK_TFIDA',

scheme: {

type: 'DBS',

objective: 'STANDARD',

}

};

const subject = {

subject_id: 'subject_id_string',

};

const policy = new Yoti.PolicyBuilder()

.withIdentityProfileRequirements(identityProfileRequirements)

.build();

const notification = new Yoti.ShareSessionNotificationBuilder()

.withUrl("notification-webhook")

.withMethod("POST")

.build();

const shareSessionConfig = new Yoti.ShareSessionConfigurationBuilder()

.withRedirectUri("/your-callback-url")

.withSubject(subject)

.withPolicy(policy)

.withNotification(notification)

.build();

async function getShareSession() {

JSONObject scheme = new JSONObject()

.put("type", "DBS")

.put("objective", "STANDARD");

JSONObject identityProfileRequirements = new JSONObject()

.put("trust_framework", "UK_TFIDA")

.put("scheme", scheme);

JSONObject subject = new JSONObject()

.put("subject_id", "subject_id_string");

Policy policy = Policy.builder()

.withIdentityProfileRequirements(identityProfileRequirements)

.build();

ShareSessionNotification notification = ShareSessionNotification.builder("notification-webhook")

.withMethod("POST")

.build();

ShareSessionRequest shareSessionConfig = ShareSessionRequest.builder()

.withRedirectUri("/your-callback-url")

.withSubject(subject)

.withPolicy(policy)

$identityProfileRequirements = (object)[

'trust_framework' => 'UK_TFIDA',

'scheme' => [

'type' => 'DBS',

'objective' => 'STANDARD'

]

];

$subject = (object)[

'subject_id' => 'subject_id_string'

];

$policy = (new PolicyBuilder())

->withIdentityProfileRequirements($identityProfileRequirements)

->build();

$notification = (new ShareSessionNotificationBuilder())

->withUrl("notification-webhook")

->withMethod("POST")

->build();

$shareSessionConfig = (new ShareSessionRequestBuilder())

->withRedirectUri("your-callback-url")

->withSubject($subject)

->withPolicy($policy)

->withNotification($notification)

->build();

var identityProfileRequirements = new {

trust_framework = "UK_TFIDA",

scheme = new

{

type = "DBS",

objective = "STANDARD"

}

};

var subject = new {

subject_id = "subject_id_string"

};

YotiPolicy policy = new YotiPolicyBuilder()

.WithIdentityProfileRequirements(identityProfileRequirements)

.Build();

var notification = new Notification

{

Headers = { },

Url = "notification-webhook",

Method = "POST",

VerifyTls = true

};

ShareSessionConfiguration shareSessionConfig = new ShareSessionConfigurationBuilder()

.WithRedirectUri("/your-callback-url")

.WithSubject(subject)

.WithPolicy(policy)

.WithNotification(notification)

identityProfile := []byte(`{

"trust_framework": "UK_TFIDA",

"scheme": {

"type": "DBS",

"objective": "STANDARD"

}

}`)

subject := []byte(`{

"subject_id": "subject_id_string"

}`)

policy := (&digitalidentity.PolicyBuilder{})

.WithIdentityProfileRequirements(identityProfile)

.Build()

notification := (&digitalidentity.ShareSessionNotification{})

.WithUrl("notification-webhook")

.WithMethod("POST")

.Build()

shareSessionConfig := (&digitalidentity.ShareSessionBuilder{})

.WithRedirectUri("/your-callback-url")

.WithSubject(subject)

.WithPolicy(policy)

.WithNotification(notification)

.Build()

shareSession, err := client.CreateShareSession(shareSessionConfig)

Identity Profile Requirements Explained

Field	Value	Description
trust_framework	String	Defines under which trust framework this identity profile should be verified. Enum: UK_TFIDA
scheme	Object	Defines which scheme this identity profile should satisfy. The scheme must be supported by the specified trust framework otherwise the request is considered invalid.
type	String	Defines which scheme this identity profile should satisfy. Enum: DBS, RTW, RTR, DBS_RTW
objective	String	Defines the objective to be achieved for the particular scheme. It must be provided for those schemes where it is mandatory. Example, this is mandatory for DBS and the possible values are: ”BASIC”, “STANDARD”, “ENHANCED”.

Subject ID Explained

Field	Description
subject_id	allows the RP to track a subject across session creation and session retrieval

The dynamicScenario can be used to get a shareURL which will be used by the Yoti scripts to generate a Yoti QR code.

Client side view

Once you have the Share session, you can use it on the frontend for it to render a Yoti QR code. Please see example below using the modal QR code.

<head>

</head>

<body>

async function onSessionIdResolver() {

// Make a call to your backend, and return a 'sessionId'

const response = await fetch('http://localhost:3000/sessions', { method: 'POST' });

const data = await response.json();

return data.sessionId;

}

function onErrorListener(...data) {

console.warn('onErrorListener:', ...data);

}

const loadYoti = async () => {

const { Yoti } = window;

if (Yoti) {

Query parameters

You can append query params to the landing page URL that displays the Yoti QR/button. These will be added to the redirect URI.

For example if you load the landing page containing the Yoti button as follows:

https://example.com/?iso=test&user_id=6667

The query parameters (iso=test&user_id=6667) will be returned in the callback URL.

Response

Further details on how to use the SDK to get shared attributes can be found here:

Retrieve the profile

In case of a successful transaction, once the profile is retrieved, the identity profile report can be accessed.

yotiClient.getShareReceipt(receiptId)

.then((shareReceipt) => {

const sessionId = shareReceipt.getSessionId();

const rememberMeId = shareReceipt.getRememberMeId();

const parentRememberMeId = shareReceipt.getParentRememberMeId();

const profile = shareReceipt.getProfile();

const selfieImageData = profile.getSelfie().getValue();

const base64SelfieUri = selfieImageData.getBase64Content();

const documentDetails = profile.getDocumentDetails().getValue();

const hasIdentityProfile = Boolean(profile.getIdentityProfileReport());

if (hasIdentityProfile) {

const identityProfileReport = profile.getIdentityProfileReport().getValue();

}

})

try {

Receipt shareReceipt = client.fetchShareReceipt(receiptId);

String sessionId = shareReceipt.getSessionId();

String rememberMeId = shareReceipt.getRememberMeId();

String parentRememberMeId = shareReceipt.getParentRememberMeId();

HumanProfile profile = shareReceipt.getProfile();

Image selfieImageData = profile.getSelfie().getValue();

String selfieBase64Content = selfieImageData.getBase64Content();

DocumentDetails documentDetails = profile.getDocumentDetails().getValue();

Attribute<Map<String, Object>> identityProfileReport = profile.getIdentityProfileReport();

Map<String, Object> valueRepresentation = identityProfileReport.getValue();

} catch (DigitalIdentityException e) {

LOG.error(e.getMessage());

}

$shareReceipt = $client->fetchShareReceipt($receiptId);

$sessionId = $shareReceipt->getSessionId();

$rememberMeId = $shareReceipt->getRememberMeId();

$parentRememberMeId = $shareReceipt->getParentRememberMeId();

$profile = $shareReceipt->getProfile();

$selfieImageObj = $profile->getSelfie()->getValue();

$selfieImageBase64Content = $selfieImageObj->getBase64Content();

$documentDetails = $profile->getDocumentDetails()->getValue();

$identityProfileReport = $profile->getIdentityProfileReport()->getValue();

ShareReceipt shareReceipt = yotiClient.GetShareReceipt(receiptId);

string sessionId = shareReceipt.SessionId;

string rememberMeId = shareReceipt.RememberMeId;

string parentRememberMeId = shareReceipt.ParentRememberMeId;

YotiProfile profile = shareReceipt.Profile;

Image selfie = profile.Selfie?.GetValue();

string selfieURI = profile.Selfie?.GetValue().GetBase64URI();

var documentDetails = profile.DocumentDetails.GetValue();

bool hasIdentityProfile = profile.IdentityProfileReport != null ? true : false;

if (hasIdentityProfile) {

var identityProfileReport = profile.IdentityProfileReport.GetValue();

}

shareReceipt, err := client.GetShareReceipt(receiptId)

sessionId := shareReceipt.SessionID

rememberMeID := shareReceipt.RememberMeID

parentRememberMeID := shareReceipt.ParentRememberMeID

profile := shareReceipt.UserContent.UserProfile

selfie := userProfile.Selfie()

selfieBase64URL := selfie.Value().Base64URL()

documentDetails = profile.DocumentDetails().Value();

identityProfileReport := userProfile.IdentityProfileReport().Value()

The identity profile report contains the verified identity details and the verification report that certifies how the identity was verified and how the verification level was achieved.

There will be instances where we have exhausted all available ‘routes’ to help a user achieve compliance with the requested scheme and not been successful. In these cases the user will not be able to complete the ‘share’, and will be shown a screen which informs them that they cannot continue with the journey in our app. This will trigger a failure sharing scenario, responding back with an associated error code.

Last updated on

Was this page helpful?