WebComponent

Introduction

This page contains instructions on how to use WebComponent, a javascript library that builds open banking connectivity within your website. To implement the WebComponent, follow four simple steps:

Set Allowed Origins in Developer panel
Retrieve access token
Retrieve javascript url
Embed WebComponent to your website

Once the steps are completed the customer journey will look as follows:

Try it yourself!

Click on the button below to try out a demo of the customer journey that Planky will present to your customers.

Code Playground

Below you can find code that integrates Planky's Web Component on your website. Both front and back end code is provided. To begin, simply select the language you wish to work in (on the left) then hit "Edit". This will open a new window in codesandbox.io where you can live test the code and view its output.

Back-end

Edit

// ===================================
// NODE.js Snippet
// ===================================

const express = require("express");
const cors = require("cors");
const { getToken, getWebComponentUrl } = require("./utils");

const app = express();

app.use(cors());
app.use(express.static("dist"));
app.use(express.json());

// Expose endpoint, something like: "/api/get-web-component" 
app.get("/api/get-web-component", async (req, res) => {

  // Get TOKEN
  const token = await getToken(); // check utils file
  
  // Replace TOKEN and USER_REFERENCE for webComponentUrl
  const webComponentUrl = await getWebComponentUrl(token); // check utils file

  // Return Web Component Url
  return res.send({ url: webComponentUrl });
});

app.listen(process.env.PORT || 8000, () =>
  console.log(`Listening on port 8000!`)
);

// ===================================
// utils.js - example of how to make "get token" request and use credentials
// ===================================
// Full example can be found at our live example 
// at CodeSandbox platform - click "edit" button

// Use on of the HTTP API client (for example axios)
const axios = require("axios");

// Protect your secrets and store them as env variables
const clientId = process.env.CLIENT_ID;
const clientSecret = process.env.CLIENT_SECRET;
const origin = process.env.ORIGIN;
const userReference = process.env.USER_REFERENCE;

// Request body
const authData = JSON.stringify({
  client_id: clientId,
  client_secret: clientSecret,
  grant_type: "client_credentials"
});

// Request config
const authConfig = {
  method: "post",
  url: "https://api.friendlyscore.com/oauth/v3/token",
  headers: {
    "Content-Type": "application/json"
  },
  data: authData
};

// Request method (async/await, try/catch)
const getToken = async () => {
  try {
    return await axios(authConfig)
      .then((res) => {
        // console.log(JSON.stringify(res.data));
        return res.data.access_token;
      })
      .catch((err) => {
        // if (clientId) console.log(err);
        return null;
      });
  } catch (err) {
    return null;
  }
};

Front-end

Edit

// ===================================
// VanillaJS Snippet
// ===================================

// Create script element
var script = document.createElement("script");

// Add script content
s.src = "{WEB_COMPONENT_ONE_TIME_URL}";

// Make is async, to not block other resources
script.async = true;

// Append to Head
document.head.appendChild(script);

// Or Body
document.body.appendChild(script);

Full Integration

In the following, we provide a detailed step-by-step guide to integrating the WebComponent software into your website

Set Allowed Origins

By default, WebComponent origin is set to localhost on port 3000. If you want to run WebComponent on a different host and port you must set a new origin in the Developer Console.

Retrieve access token

To use the Planky API you need to authorise yourself. You can do that by retrieving access token by using your client_id and client_secret. The example below shows you how to make a request to obtain an access token. The token is needed to make authorised requests to the server. The API requests example will be perform using cURL.

Example Token request

Obtain your client_id and client_secret from Planky API keys.

curl -X POST \
     https://api.friendlyscore.com/oauth/v3/token \
     -H 'Content-Type: application/json' \
     -d '{
     "client_id": {client_id},
     "client_secret": {client_secret},
     "grant_type": "client_credentials"
}'

Successful response

{
    "access_token": "{ACCESS_TOKEN}",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": null
}

Error responses

Invalid client_id or client_secret

{
    "code": 0,
    "message": "invalid_client",
    "http_code": 400
}

Invalid client_credentials

{
    "code": 0,
    "message": "invalid_request",
    "http_code": 400
}

Retrieve javascript url

A one-time url is used to render the Planky WebComponent inside HTML.

Example request

curl -X POST \
    https://api.friendlyscore.com/public/v3/component_auth/init \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{
    "user_reference": "{USER_REFERENCE}",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36",
    "ip": "10.10.10.10",
    "origin": "https://yourdomain.com"
}

Successful response

{
  "url": "{WEB_COMPONENT_ONE_TIME_URL}",
  "created_at": 1566306425,
  "expires_in": 1800
}

Error responses

400 Bad Request	user_reference, ip, user_agent, origin is invalid or missing.
401 Unauthorized	access_token is invalid or expired.

Embed WebComponent

Follow the two simple steps to embed WebComponent:

Create an HTML element with id fs-component to control the location where the component will be displayed
Create a script tag with src pointing to the one time javascript url

For security reasons, javascript url is one time. You need to regenerate the url everytime you want to display WebComponent.

You can copy the template below and paste into your html page.

<!doctype html>
  <html>
  <head>
      ...
  </head>
  <body>
      <!-- START COPYING FROM HERE -->
      <div id="fs-component"></div>
      <script src="{WEB_COMPONENT_ONE_TIME_URL}"></script>
      <!-- END COPYING -->
  </body>
</html>

Events

Events are triggered in the following situations:

startFsComponentProcess	WebComponent loads the first view of the flow process.
endFsComponentProcess	WebComponent loads the last view of the flow process.
FsOpenBankingBankConnected	User successfully connects with the bank.

Event listener example

1
2
3

document.addEventListener('startFsComponentProcess', function () {
  console.log('startFsComponentProcess');
});

Was this article helpful?

Friendly Score UK Ltd.

84 Brook Street

London W1K 5EH

Call us on +44 20 3709 6726

Company registered in England

Company number 09168668, ICO ZA111687

VAT registration number 206 9758 80

Authorised and Regulated by the Financial Conduct Authority. (FRN: 821100, 781963)