Web integration
Once you've set up your organisation account on the Yoti Hub, you’re ready to start integrating with Yoti. This section explains how to complete a basic web integration.
QR Code type
You will need to create a button to allow your users to authenticate with Yoti. See Button design guide before you start the integration.
This contains a QR code for users to scan with their Yoti app. Mobile web users will skip the QR code scanning step, as they use the Yoti mobile app directly to authenticate. For more information on our modal go to our Integration guide.
Yoti has three options to display the QR code.
1) Modal
2) Instant
3) Inline
Modal
The modal QR code option has a button which when clicked opens a modal pop out window with the QR code present. There are three tabs, describing how to scan the QR code, The QR code and attributes to be shared and about Yoti - Please give it a click to see it working:
Inline
The inline QR code option has a button which when clicked opens just the QR code. You will need to provide more context as to what Yoti is for this. See scenario example section for more detail.
Instant
The instant QR code option is just the QR code with no button. You will need to provide more context as to what Yoti is for this. See scenario example section for more detail. Example below:
Generate a Yoti button
Yoti provides a button generator for you to include in your HTML file. In the example below, the button generator script has been added to the head of the HTML document.
To generate the Yoti button use the code snippet below:
Modal
<!-- Simple Button Generation --><head> <script src="https://www.yoti.com/share/client/"></script></head><body> <!-- Yoti element will be rendered inside this DOM node --> <div id="xxx"></div> <!-- This script snippet will also be required in your HTML body --> <script> window.Yoti.Share.init({ elements: [ { domId: "xxx", scenarioId: "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", clientSdkId: "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ] }); </script></body>Inline
<!-- Simple Button Generation --><head> <script src="https://www.yoti.com/share/client/"></script></head><body> <!-- Yoti element will be rendered inside this DOM node --> <div id="xxx"></div> <!-- This script snippet will also be required in your HTML body --> <script> window.Yoti.Share.init({ elements: [ { domId: "xxx", scenarioId: "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", clientSdkId: "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", type: "inline", button: { label: " Use Yoti", title: " Scan with the Yoti app" } } ] }); </script></body>Instant
<!-- Simple Button Generation --><head> <script src="https://www.yoti.com/share/client/"></script></head><body> <!-- Yoti element will be rendered inside this DOM node --> <div id="xxx"></div> <!-- This script snippet will also be required in your HTML body --> <script> window.Yoti.Share.init({ elements: [ { domId: "xxx", scenarioId: "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", clientSdkId: "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", type: "inline", qr: { title: " Scan with the Yoti app" } } ] }); </script></body>This JavaScript library currently needs to be invoked – do this by calling Yoti.Share.init() in the body of your HTML document. For the config, you will need to specify a ‘domId’ so we know where we need to add the Yoti button on your page and the ‘scenarioId’ that is being provided by Yoti Hub after creating an application.
The Yoti button requires the hosting page to be accessed via HTTPS, so please make sure that your web application has HTTPS enabled.
Finally, the domain port pair where the button is deployed (i.e. https://localhost:8000) must match the one that you have configured in Yoti Hub. This prevents other web sites from embedding your Yoti button.
| Name | Purpose | Required |
|---|---|---|
| domID | Specifies the ID of the DOM node where Yoti webshare wants to be rendered. | Yes |
| clientSdkId | Identifies your Yoti Hub application. This value can be found in the Hub, within your application section, in the keys tab. | Yes |
| scenarioId | Identifies the attributes associated with your Yoti application. This value can be found on your application page in Yoti Hub (navigate to Scenarios tab) | Yes |
| Button | Config for the button styling. | No |
| Button - Label | Text on the button. Should be relevant for your use case. | No |
| Button - align | Alignment of the button in the parent div - "center", "left", "right" | No |
| Button - width | Width of the button - "auto" will set to fit the label. "full" - will fill the width of the parent div. | No |
| Modal - zIndex | Sets the z-index of the modal. This is defaulted to 9999. | No |
| shareComplete | Allows token handling to be performed without redirecting the webpage. | No |
| shareComplete - closeDelay | How long the modal will stay open before handling the token or redirecting. Default to 4000ms with a min of 500ms and a max of 1000ms | No |
| shareComplete - tokenHandler | Allows you to run your own function to handle the token without a redirect. Calling done() will close the modal; overwriting any closeDelay you have. | No |
| label | This is the text on the button and is customisable | Yes |
| title | This is the text around the QR code and is customisable | No |
Install SDK
Once you have a working 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
This is generated by Yoti when you publish your Yoti application in Yoti Hub. You can find it labelled as Yoti Client SDK ID under the Keys tab within your application. The SDK ID is necessary to initialise the Yoti SDK and it is passed in each call to our system.
Your application key pair
This is the private key (in .pem format) associated with the Yoti application you created in Yoti Hub.
There are three purposes for this PEM file:
- Decrypting the one-time-use token.
- Signing your requests to our system.
- Decrypting the fetched user profile so that the profile data can be consumed by your application.
If you lose or corrupt your PEM file you will be able to generate a new one. Regenerating your key pair will break your current application by invalidating your current PEM file and generated keys. This means you will be unable to decrypt new tokens until these are replaced by the newly-generated ones.
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 using NPM:
npm install -S -E yotiOnce 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.
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)// For SDK version < 3const yotiClient = new yoti(CLIENT_SDK_ID, PEM)// For SDK version >= 3const yotiClient = new yoti.Client(CLIENT_SDK_ID, PEM_KEY)Retrieve a profile
Retrieving a profile involves receiving a one-time-use token, and decrypting it to get a user profile.
When a user scans a Yoti QR code, Yoti makes a GET request to your callback URL, passing a token as a query string parameter.
For a URL set as https://your-callback-url in Yoti Hub, the returned callback URL would look like the following: https://your-callback-url?token=
You can set and edit the callback URL within your Yoti application under the Integration tab. Yoti will automatically prefix the URL with your domain.
When your web application receives a token via the exposed endpoint as a query string parameter, you can easily retrieve the user profile. The user profile object provides a set of attributes corresponding to the user attributes you specified during the creation of your Yoti application on Hub.
SDK process
When you pass the token to the Yoti Client object, the SDK does the following:
- Decrypts the wrapped receipt key attribute, using the application private key.
- Uses the decrypted key to decrypt the other party profile content attribute.
- Decodes the decrypted profile and returns it to your application.
The profile attributes are central to the SDK and allow you to see and work with the information that your users share with you.
yotiClient.getActivityDetails(oneTimeUseToken) .then((activityDetails) => { const rememberMeId = activityDetails.getRememberMeId(); const parentRememberMeId = activityDetails.getParentRememberMeId(); const receiptId = activityDetails.getReceiptId(); const timestamp = activityDetails.getTimestamp(); const base64SelfieUri = activityDetails.getBase64SelfieUri(); const userProfile = activityDetails.getUserProfile(); // deprecated, use getProfile() instead const profile = activityDetails.getProfile(); const applicationProfile = activityDetails.getApplicationProfile(); const selfieImageData = profile.getSelfie().getValue(); const fullName = profile.getFullName().getValue(); const familyName = profile.getFamilyName().getValue(); const givenNames = profile.getGivenNames().getValue(); const phoneNumber = profile.getPhoneNumber().getValue(); const emailAddress = profile.getEmailAddress().getValue(); const dateOfBirth = profile.getDateOfBirth().getValue(); const postalAddress = profile.getPostalAddress().getValue(); const structuredPostalAddress = profile.getStructuredPostalAddress().getValue(); const gender = profile.getGender().getValue(); const nationality = profile.getNationality().getValue(); const ageVerified = profile.getAgeVerified().getValue(); const documentDetails = profile.getDocumentDetails().getValue(); const applicationName = applicationProfile.getName().getValue(); const applicationUrl = applicationProfile.getUrl().getValue(); const applicationLogo = applicationProfile.getLogo().getValue(); const applicationReceiptBgColor = applicationProfile.getReceiptBgColor().getValue(); // You can retrieve the sources and verifiers for each attribute as follows const givenNamesObj = profile.getGivenNames() const givenNamesSources = givenNamesObj.getSources(); // list/array of anchors const givenNamesVerifiers = givenNamesObj.getVerifiers(); // list/array of anchor // You can also retrieve further properties from these respective anchors in the following way: // Retrieving properties of the first anchor const value = givenNamesSources[0].getValue(); // string const subtype = givenNamesSources[0].getSubType(); // string const timestamp = givenNamesSources[0].getSignedTimeStamp().getTimestamp(); // Date object const originServerCerts = givenNamesSources[0].getOriginServerCerts(); // list of X509 certificates })