Create a session
There are four steps to follow to integrate the Identity verification SDK:
- Install the SDK
- Create the session
- Launch the user view
- Retrieve the results
This section will explain how to install the SDK and create a session.
Installing the SDK
Please use our Yoti SDKs to automatically build the relevant session. You will need the following information about your application from the Yoti Hub:
- Yoti SDK ID
- Your application key pair
The Yoti SDKs are available via popular dependency management systems.
npm install -S -E yotiCreate a session
Once you have added the Yoti SDK dependency to your project, you can use it to build and create your session as shown in the code snippet below:
const path = require('path');const fs = require("fs");const { IDVClient, SessionSpecificationBuilder, SdkConfigBuilder, NotificationConfigBuilder,} = require('yoti');const CLIENT_SDK_ID = 'YOTI_CLIENT_SDK_ID'const PEM_PATH = 'YOTI_KEY_FILE_PATH'const PEM_KEY = fs.readFileSync(path.join(__dirname, PEM_PATH));const idvClient = new IDVClient( CLIENT_SDK_ID, PEM_KEY ); idvClient .createSession(sessionSpec) .then((session) => { const sessionId = session.getSessionId(); const clientSessionToken = session.getClientSessionToken(); const clientSessionTokenTtl = session.getClientSessionTokenTtl(); console.log(sessionId); }) .catch((err) => { console.log(err) });Your session can be configured with the following:
- Preferences
- Scheme
- Notifications
Client Preferences
To create a session, please start by setting your preferences. For this purpose, the method sdkConfig builder is explained below. If parameters are not defined the default below will be set:
.withSdkConfig( new SdkConfigBuilder() .withAllowsCamera() .withPrimaryColour('#2d9fff') .withSecondaryColour('#FFFFFF') .withFontColour('#FFFFFF') .withPresetIssuingCountry('GBR') .withSuccessUrl(`${process.env.YOTI_APP_BASE_URL}/index`) .withErrorUrl(`${process.env.YOTI_APP_BASE_URL}/profile`) .withAllowHandoff(true) .build() )| Type | Parameter (examples) | Description |
|---|---|---|
| withPrimaryColour | #2d9fff(default), #ff0000 | Colours of the button provided in the frontend client as a hexadecimal RGB value. |
| withPresetIssuingCountry | USA, GBR | The user must select the issuing country of the document they are uploading. This setting determines which issuing country is selected by default. NOTE: Must be a 3 letter ISO 3166 code. |
| withSuccessUrl | https://yourdomain.com/success | If the upload/photo is successfully captured redirect your users here. Yoti will then begin to carry out the requested checks and tasks. If undefined, the page will not redirect and you can listen to Yoti's post messages on the same page. |
| withErrorUrl | https://yourdomain.com/error | If the upload/photo is unsuccessfully captured redirect your users here. If undefined, the user view will display an error screen, with the error code as a query parameter and won't redirect. (Details on the error codes can be found in [Client side user view](Client side user view)) |
| withAllowHandoff | true, false | if enabled will offer the user to transfer flow from desktop to a mobile device by scanning a QR code. |
Session Requirements
After that, specify the desired scheme in the identity profile requirements.
const advancedIdentityProfileSchemeAM1 = new AdvancedIdentityProfileSchemeBuilder() .withType('IDENTITY') .withObjective('AL_M1') .withLabel('label-for-IDENTITY-AL-M1') .build();const advancedIdentityProfileYotiGlobal = new AdvancedIdentityProfileBuilder() .withTrustFramework('YOTI_GLOBAL') .withScheme(advancedIdentityProfileSchemeAM1) .build();const advancedIdentityProfileRequirements = new AdvancedIdentityProfileRequirementsBuilder() .withProfile(advancedIdentityProfileYotiGlobal) .build();const subject = { subject_id: 'subject_id_string',};Identity Profile Requirements Explained
| Field | Value | Description | Mandatory |
|---|---|---|---|
| trust_framework | String | Defines under which trust framework this identity profile should be verified. Enum: YOTI_GLOBAL | Yes |
| 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. | Yes |
| type | String | Defines which scheme this identity profile should satisfy. Enum: "IDENTITY", "IDENTITY_PLUS_ADDRESS" | Yes |
| 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: ”AL_L1”, “AL_M1”. | Yes (in case of DBS) |
| label | String | Defines a label given to a specific scheme, allowing integrators to identify the results of a specific scheme. | Yes |
System Preferences
Then, specify the subject id and set the system preferences for your session.
const subject = { subject_id: 'subject_id_string',};const sessionSpec = new SessionSpecificationBuilder() .withClientSessionTokenTtl(600) .withResourcesTtl(90000) .withUserTrackingId('some-user-tracking-id') .withSubject(subject) .withAdvancedIdentityProfileRequirements(advancedIdentityProfileRequirements) .withSdkConfig(sdkConfig) .withNotifications(notificationConfig) .build();The table below explains the optional parameters for the session and data retention configuration.
| Parameters | Description | Optional |
|---|---|---|
| withClientSessionTokenTtl | This is how long the full Identity verification session is open for in seconds. This must be longer than 300s (5 minutes). | ✅ |
| withResourcesTtl | Retention period ("time to live") for uploaded documents/images in number of seconds. Default is one week ( Note: This config may result in additional charges. Please get in touch with support if considering a TTL longer than three months. | ✅ |
| withUserTrackingId | Allows the relying business backend to track the same user across multiple sessions. Note: This should not contain any personal identifiable information. | ✅ |
| WithSubject | Allows to track the same user across multiple sessions. Should not contain any personal identifiable information. | ✅ |
Document Filter
If you wish to exclude documents or only allow specific documents to be used, you can do this by adding a document filter to your configuration.
const documentFilter = const advancedIdentityConfig = new AdvancedIdentityProfileSchemeConfigBuilder() .withFilter(documentFilter)const advancedIdentityProfileSchemeAM1 = new AdvancedIdentityProfileSchemeBuilder() .withType('IDENTITY') .withObjective('AL_M1') .withLabel('label-for-IDENTITY-AL-M1') .withConfig(advancedIdentityConfig) .build();