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:

  1. Set Allowed Origins in Developer panel
  2. Retrieve access token
  3. Retrieve javascript url
  4. 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
    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 // =================================== // 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

  • 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 // =================================== // 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.

    1 2 3 4 5 6 7 8 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

    1 2 3 4 5 6 { "access_token": "{ACCESS_TOKEN}", "expires_in": 3600, "token_type": "bearer", "scope": null }

    Error responses

    Invalid client_id or client_secret

    1 2 3 4 5 { "code": 0, "message": "invalid_client", "http_code": 400 }

    Invalid client_credentials

    1 2 3 4 5 { "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

    1 2 3 4 5 6 7 8 9 10 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

    1 2 3 4 5 { "url": "{WEB_COMPONENT_ONE_TIME_URL}", "created_at": 1566306425, "expires_in": 1800 }

    Error responses

    400 Bad Requestuser_reference, ip, user_agent, origin is invalid or missing.
    401 Unauthorizedaccess_token is invalid or expired.

    Embed WebComponent

    Follow the two simple steps to embed WebComponent:

    1. Create an HTML element with id fs-component to control the location where the component will be displayed
    2. 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.

    1 2 3 4 5 6 7 8 9 10 11 12 <!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:

    startFsComponentProcessWebComponent loads the first view of the flow process.
    endFsComponentProcessWebComponent loads the last view of the flow process.
    FsOpenBankingBankConnectedUser 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)