Integration guide
Welcome to the free Digital ID sandbox! The sandbox is an isolated test environment, intended to easily create test cases using dummy data where it's not feasible to test your integration with live data.
The sandbox environment will allow you to:
- Mimic our production services in test
- Use test data bypassing using the Yoti app to share attributes.
- Double checking data formats and behaviours.
- Testing edge cases
The main difference between our Yoti production services and sandbox is the Yoti share token is completed using a production QR code whereas sandbox generates the token for you.
Supported Languages
Just like the normal Yoti Client, the Yoti Sandbox Client SDK is available in seven languages:
Creating a Sandbox Request
Installation
Once you have generated your keys, you can continue with installing the Sandbox SDK into your backend.
Just like our production integration, the Yoti Sandbox Client SDK is available in seven languages and installing is easy through popular package managers.
// Yoti Client (skip if already installed)npm install -S -E yoti// Sandboxnpm install -S -E -D @getyoti/sdk-sandboxThe sandbox client is packaged separately to the production Yoti client enabling it to be used as a development dependency.
Initialising the Sandbox Client
You will need your Sandbox Client SDK ID and PEM file created from the Yoti Hub to initialise the sandbox client.
Please do not open the pem file as this might corrupt the key and you will need to create a new sandbox key.
const fs = require('fs');const { SandboxProfileClientBuilder, SandboxAgeVerificationBuilder, TokenRequestBuilder,} = require('@getyoti/sdk-sandbox');const yoti = require('yoti');const SANDBOX_CLIENT_SDK_ID = 'SANDBOX_CLIENT_SDK_ID';const PEM = fs.readFileSync('/path/to/your-pem-file.pem');const sandboxProfileClient = new SandboxProfileClientBuilder() .withClientSdkId(SANDBOX_CLIENT_SDK_ID) .withPemString(PEM) .build();Generating a Token
To create a sandbox request, you must specify how you want your response to be provided. Below is an example of a simple sandbox request.
const tokenRequest = new TokenRequestBuilder() .withRememberMeId('some remember me ID') .withGivenNames('some given names') .withFamilyName('some family name') .withFullName('some full name') .withDateOfBirthString('1980-01-01') .withGender('some gender') .withPhoneNumber('some phone number') .withNationality('some nationality') .withBase64Selfie('some base64 encoded selfie') .withEmailAddress('some@email') .withDocumentDetails('PASSPORT USA 1234abc') .build();Familiarise yourself with the Attributes explained. For advanced attribute generation please see below.
Reading the Request
Once you have generated a sandbox token, this can be used in the same way as the standard Web Integration.
sandboxProfileClient.setupSharingProfile(tokenRequest) .then((response) => { const token = response.getToken(); // Use token to get activity details. const yotiClient = new yoti.Client(SANDBOX_CLIENT_SDK_ID, PEM, { apiUrl: 'https://api.yoti.com/sandbox/v1' // Set client to Sandbox }); yotiClient.getActivityDetails(token) .then((activityDetails) => { // Handle response here. }); }) .catch((err) => { // Handle unhappy path. });This concludes the basic Sandbox Integration for the Digital ID.
Advanced Test cases
Now that you're familiar with creating a simple sandbox request it's important to know that there are some additional features in the SDK which can be utilised to create powerful tests. In this section we'll cover:
- Source and verifiers
- Address
- Age verification
Source and verifiers
If you're familiar with a Yoti app share, you'll recognise that an attribute contains additional data, such as the Source of the Attribute and the Verifier. These are known as Anchors. Please see below for an example of attaching Anchors to your sandbox attributes.
const { YotiDate, } = require('yoti');const { SandboxAnchorBuilder, TokenRequestBuilder,} = require('@getyoti/sdk-sandbox');const anchors = [ new SandboxAnchorBuilder() .withType('SOURCE') .withSubType('') .withTimestamp(YotiDate.fromDateString('2020-01-01T00:00:00Z')) .withValue('PASSPORT') .build(), new SandboxAnchorBuilder() .withType('VERIFIER') .withSubType('') .withTimestamp(YotiDate.fromDateString('2020-01-01T00:00:00Z')) .withValue('YOTI_ADMIN') .build(),];const tokenRequest = new TokenRequestBuilder() .withDocumentDetails('PASSPORT USA 1234abc', anchors) .build();Address
Yoti use a set format depending on the Address region. In order to create tests for the structured postal address, we recommended referring to the Yoti formats below.
An example of building a structured postal address is shown below:
const tokenRequest = new TokenRequestBuilder() .withStructuredPostalAddress( JSON.stringify({ building_number: 46, building_name: 'Shelley Court', sub_building: 'Flat 2', address_line1: 'Flat 2', address_line2: 'Shelley Court', address_line3: '46 Nowhere', locality: 'Nowhere Town', administrative_area_l1: 'Nowhere', postal_code: 'RG1 5DG', country: 'GBR', formatted_address: 'Flat 2 Shelley Court 46 Nowhere Town Nowhere RG1 5DG GBR', }), ) .build();Age Verification
A common use case with the Yoti app is using the Age Over attribute. Testing this with the Sandbox involves creating an Age Verification sandbox attribute.
const { SandboxAgeVerificationBuilder, TokenRequestBuilder,} = require('@getyoti/sdk-sandbox');const ageVerification = new SandboxAgeVerificationBuilder() .withDateOfBirthString('1980-01-01') .withAgeOver(18) .build();const tokenRequest = new TokenRequestBuilder() .withAgeVerification(ageVerification) .build();Go Live
Once you have tested our sandbox please return to our integration guide.
If you have any other questions please do not hesitate to contact clientsupport@yoti.com.
Once we have answered your question we may contact you again to discuss Yoti products and services. If you’d prefer us not to do this, please let us know when you e-mail.