Fourthline's Web SDK smoothly redirects clients from your website using a QR code or SMS to a new browser window on their mobile device. The product workflow on the device is hosted by Fourthline on a secure, private subdomain. Alternatively, you can embed the SDK in your mobile site.
The SDK takes care of the user journey and orchestrates modules with a streamlined API flow. You can also easily level up from single products to multi-product solutions with no additional API requests.
All required images and data are captured in our best-practices UI and automatically uploaded to Fourthline for processing. You don't have to handle sensitive personal data yourself.
Web SDK Setup
The following sections explain how to set up the Web SDK and the input needed to configure the SDK to your requirements.
SDK Configuration
Provide your implementation manager with the following configuration specifications:
| Configuration | Description |
|---|---|
| Required URLs | For the redirect flow hosted by you, provide the URL for both sandbox and production. |
| For the product workflow hosted by Fourthline, provide one of the following for both sandbox and production: • Custom domain • Custom Fourthline domain | |
| Redirect options | Specify which redirect option you want to use: • QR code • SMS |
| For SMS redirect: • Specify the languages you want to support. • Specify a default language. • Provide the SMS message copy per language. • Provide the SMS originator (indicates to the client who the SMS is from) as a string of 3–11 characters. | |
| UI customization | Provide the styles file to customize the UI and your logo. |
Required URLs
The redirect flow is typically embedded in your website and hosted by you, so you must provide us the URL for both sandbox and production, e.g. www.mysite.com.
The product flow is hosted by Fourthline and can be served using either:
| Domain | Sandbox | Production |
|---|---|---|
| Custom domain | Provide URL, e.g.: www.verify.mydomain.com | Provide URL, e.g.: www.verify.mydomain.com |
| Custom Fourthline domain | https://{yourstring}.app.sandbox.fourthline.com | https://{yourstring}.app.fourthline.com |
If you opt for a custom domain, you are responsible for the DNS configuration.
Redirect options
Specify which redirect option you want to use: QR code and/or SMS.
For SMS redirect:
- Specify the languages you want to support.
- Specify a default language.
- Provide the SMS message copy per language.
- Provide the SMS originator (indicates to the client who the SMS is from) as a string of 3-11 characters.
Web SDK Integration
You can set up your Web SDK by embedding in the browser.
To embed the Web SDK:
Import the JavaScript files
Import the following scripts. You can put them in the header or inline in the HTML:
Example (HTML)
<!DOCTYPE html>
<html lang="en">
<head>
...
<script type="module" src="https://sandbox.v.fourthline.com/v1/build/web-sdk-v2.esm.js"></script>
<script nomodule src="https://sandbox.v.fourthline.com/v1/build/web-sdk-v2.js"></script>
</head>- If using a custom domain or customized Fourthline domain for the workflow, replace sandbox.v.fourthline.com with the URL of your test or live environment, as agreed with your implementation manager.
- The sandbox environment is for implementation only. When you migrate to the production environment, remove sandbox from the URL.
Add the flow tag
Add the custom flow tag to the HTML or in the template of the relevant component.
The tag is only rendered after the source for it is loaded.
Example (HTML)
<!DOCTYPE html>
<html lang="en">
<head>
...
<script type="module" src="https://sandbox.v.fourthline.com/{version, e.g.v1}/build/web-sdk-v2.esm.js"></script>
<script nomodule src="https://sandbox.v.fourthline.com/{version, e.g. v1}/build/web-sdk-v2.js"></script>
</head>
<body>
/* Somewhere in the page */
<div class="container">
<fl-flow-onboarding></fl-flow-onboarding>
</div>
</body>
</html>Localize the UI
To configure the UI language and level of formality, pass the following attributes to the fl-flow-onboarding component.
| Attribute | Description |
|---|---|
| locale | The language for the UI. Format: ISO 3166-1 alpha-2 country code Example: nl |
| formality | The level of formality. Enum: • formal, e.g. "u" in Dutch, "tu" in French • informal, e.g. "jij" in Dutch, "vous" in French |
Supported languages and formality:
| Language | Locale | Formality |
|---|---|---|
| English (default) | en | informal |
| Czech | cs | informal |
| Dutch | nl | formal, informal |
| Flemish | vl | informal |
| Finnish | fi | informal |
| French | fr | formal |
| German | de | formal |
| Italian | it | informal |
| Polish | pl | informal |
| Slovak | sk | informal |
| Spanish | es | informal |
Example (HTML)
<fl-flow-onboarding
locale="nl"
formality="formal"
></fl-flow-onboarding>Fallback flow
If you choose not to set the locale attribute, we check if the browser settings locale is:
- Supported: We set the browser settings as the SDK locale.
- Not supported: We check the lang attribute in the html tag.
If the lang attribute is:
- Supported: We set it as the SDK locale.
- Not supported: The SDK locale defaults to en (English).
Dynamic localization
You can set the locale and formality dynamically.
The fl-flow-onboarding component exposes a setLocale JavaScript method, which accepts new supported locale and formality as arguments.
If not supported, the fallback flow is triggered.
Example (JavaScript)
const elem = document.getElementsByTagName("fl-flow-onboarding")[0];
elem.setLocale("fr"); // Setting French
elem.setLocale("fr", "formal"); // Setting French (formal)The mobile device flow locale is set when the redirect flow (fl-flow-onboarding) is rendered for the first time. If you set the locale dynamically afterwards, it isn't updated for the mobile device flow. This can create a less optimal user experience, so we recommend setting the redirect flow locale using HTML before loading the SDK.
Link to the workflow
To link the redirect flow (fl-flow-onboarding) to the workflow, pass the validationCode returned in the Create SDK session response to the component.
Either set the validationCode as an HTML attribute:
Example (HTML)
const elem = document.getElementsByTagName("fl-flow-onboarding")[0];
elem.setLocale("fr"); // Setting French
elem.setLocale("fr", "formal"); // Setting French (formal)Or, set the token in JavaScript:
const flow = document.getElementById('onboarding-flow');
flow.setToken('TOKEN_OF_THE_VERIFICATION');The validationCode is single use. If you use server-side rendering, you must ensure the code is consumed after it reaches the client.
Handle continue to mobile event
When redirecting the client to the workflow from their mobile browser, the SDK emits an fl-flow-onboarding event (mobile/desktop).
If we detect the client's mobile device, we display a Continue button on mobile device screen.
When the client taps Continue, the SDK emits an flContinueMobileRequest event.
For the client to start the workflow, you must handle the flContinueMobileRequest event in your backend. If you don't handle it, the flow doesn't start and it appears to the client that the Continue button does not work.
The flContinueMobileRequest event contains a redirectHandler function in the event.detail payload. This function specifies what the SDK should do when the client completes the workflow.
If you provide URLs to your Success and Failure page, the SDK redirects the client there. If you don't provide them, we display a message telling the client that they have completed the flow and should return to your website.
New browser tab
To start the workflow in a new browser tab, call the redirectHandler function without providing success or failure page URLs.
Example (JavaScript)
document.addEventListener('flContinueMobileRequest', (e) => {
const redirectHandler = e.detail;
redirectHandler();
});Same browser tab
To start the workflow in the same browser tab, call the redirectHandler function and provide the URLs to your:
- Success page by setting the redirect property
- Failure page by setting the redirectFailure property
The URLs must be valid and include the schema.
Starting the workflow in the same browser tab overwrites the state of that page, which should be considered/handled first.
Example (JavaScript)
document.addEventListener('flContinueMobileRequest', (e) => {
const redirectHandler = e.detail;
redirectHandler({
redirect: 'https://yoursuccesspage.com/onboarding?done=true',
redirectFailure: 'https://yourfailurepage.com/onboarding?done=false',
});
});Handle status events
At each step of the workflow, the SDK emits an flOnboardingStatus event (desktop) that you can subscribe to.
You can use the status to trigger any required actions on your side, e.g. when you receive OnboardingStarted status and before receiving Loaded status, you can choose to display a ghost placeholder image.
The flOnboardingStatus event emits the following statuses:
| Event status | Description |
|---|---|
| OnboardingStarted | The validation code has been used. |
| Loaded | The SDK is loaded and the redirect options are displayed to the client. |
| OnboardingContinuing | The client has been successfully redirected and has started the workflow. |
| OnboardingCompleted | The client has successfully completed the workflow. Suggested action: Redirect the client to your Success page or email them about next steps. |
| OnboardingCompletedError | The client has completed the workflow with one or more errors and we have displayed the Failure screen. Suggested action: Redirect the client to your Failure page or email them about next steps. |
To listen to this event, add the following JavaScript snippet to your website HTML. For each event status, define and implement the required behaviour on your side.
Example (JavaScript)
document.addEventListener('flOnboardingStatus', (event) => {
const { detail: status } = event;
if (status === 'Loaded') {
// Put your code here
}
if (status === 'OnboardingCompleted') {
// Put your code here
// e.g. Remove the fl-flow-onboarding element from the DOM and render your success page
}
if (status === 'OnboardingCompletedError') {
// Put your code here
}
});Handle restart event
If the client requests to restart the redirect flow, the SDK emits an flOnboardingRestartRequest event (desktop) that you can subscribe to and handle. It is triggered from the error screen when the client taps Try again and the flow has encountered a non-recoverable error.
This event doesn't emit any values.
To handle this event:
- Listen to it.
- Create a new workflow.
- Create a new SDK session.
- To set the new validation code, either:
- Invoke the setToken(newValidationCode) method, or
- Replace the existing HTML tag with a new tag containing the updated <fl-onboarding token="newValidationCode"></fl-onboarding> token.
- Invoke the setToken(newValidationCode) method, or
Example (JavaScript)
document.addEventListener('flOnboardingRestartRequest', () => {
const onboardingTag = document.getElementBy('fl-onboarding');
// Generate a new validation and validation code
onboardingTag.setToken(newValidationCode);
});