This page sets out step-by-step instructions for setting up the Web SDK.

Embedding manual

To embed your Web SDK, follow these steps:

1. Import the JavaScript files

Import the following scripts. You can put them in the head or inline in the 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>

Notes

• 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.

2. 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.

<!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>

3. 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 code:

<fl-flow-onboarding
  locale="nl"
  formality="formal"
></fl-flow-onboarding>

Fallback flow

If you don't 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 code:

const elem = document.getElementsByTagName("fl-flow-onboarding")[0];
elem.setLocale("fr"); // Setting French
elem.setLocale("fr", "formal"); // Setting French (formal)

Caution

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 via HTML before loading the SDK.

4. 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:

<!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 token="{validationCode}"></fl-flow-onboarding>
  </div>

</body>
</html>

Or, set the token in JavaScript:

const flow = document.getElementById('onboarding-flow');

flow.setToken('TOKEN_OF_THE_VERIFICATION');

Note

The validationCode is single use. If you use server-side rendering, you must ensure the code is consumed after it reaches the client.

5. 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 to mobile device screen with a Continue button.

When the client taps Continue, the SDK emits an flContinueMobileRequest event.

Caution

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 doesn't 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 page and Failure page, the SDK redirects the client there. If you don't provide them, we display a message telling the client 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.

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.

Caution

Starting the workflow in the same browser tab overwrites the state of that page, which you may want to handle first.

Example code:

document.addEventListener('flContinueMobileRequest', (e) => {
  const redirectHandler = e.detail;
  redirectHandler({
    redirect: 'https://yoursuccesspage.com/onboarding?done=true',
    redirectFailure: 'https://yourfailurepage.com/onboarding?done=false',
  });
});

Tip

To increase security, consider using the URL API. See Mozilla Developer – URL API.

6. 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 you receive Loaded status, you could 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 behavior on your side.

Example code:

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
  }
});

7. 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.

Example code:

document.addEventListener('flOnboardingRestartRequest', () => {
  const onboardingTag = document.getElementBy('fl-onboarding');
  
  // Generate a new validation and validation code
  
  onboardingTag.setToken(newValidationCode);
});

Success

You have configured and set up your Web SDK!
To integrate your solutions, see the Integration Guides section.

Top of page