Embedding a micro-frontend

How to embed a Wealth Wizards micro-frontend tool inside your web application.

Wealth Wizards' playground tools - currently Pension Guidance, Retirement Options Guidance and Retirement Triage, are delivered as micro-frontends. A micro-frontend is an application hosted by Wealth Wizards, which can be embedded in another site with a few lines of JavaScript. We call a site which embeds a micro-frontend a "shell".

A shell can be a very simple static web page, or it can be a sophisticated dynamic Web application.

As a customer of Wealth Wizards, you have two options when implementing a playground tool:

Wealth Wizards supplies the shell
- Wealth Wizards creates and manages a shell on your behalf. With your authorisation, Wealth Wizards will set up a DNS subdomain of your choice to host the shell and make it accessible through your subdomain.
You supply the shell
- By adding a snippet of JavaScript to your own site, and an HTML <div> element as a mount point, you make your own site into a shell. The playground tool then appears within your own site.

This guide shows you how to achieve option 2.

Getting started - Set up your sample website

Your shell can be any website; we won’t make any assumptions about it here. For demonstration purposes, though, we’ll set up a sample website and run it on your local machine.

Your server may vary

We’re using Node.js and NPM to get a simple local web server. The instructions assume that you have NPM installed, and that you have a Unix-like command shell. If you’re used to a different way of getting a local web server, feel free to use it instead.

Create a new directory for your sample site, and create the site’s files:

$ mkdir samplesite
$ cd samplesite
$ touch index.html shell-styles.css

Add the following content to your new files:

<!-- index.html -->
<html>
  <head>
    <link rel="stylesheet" href="shell-styles.css" />
  </head>
  <body>
    <h1>Sample Site</h1>
    <p>Paragraph one</p>
    <p>Paragraph two</p>
  </body>
</html>

/* shell-styles.css */
body {
  background-color: aquamarine;
  font-family: Impact, Haettenschweiler, 'Arial Narrow Bold', sans-serif;
}

Launch a web server to serve this content:

$ npx http-server
Starting up http-server, serving ./

http-server version: 14.1.1

http-server settings:
CORS: disabled
Cache: 3600 seconds
Connection Timeout: 120 seconds
Directory Listings: visible
AutoIndex: visible
Serve GZIP Files: false
Serve Brotli Files: false
Default File Extension: none

Available on:
  http://127.0.0.1:8081
  http://192.168.86.190:8081
Hit CTRL-C to stop the server

The first time you do this, npx might prompt you to install packages.

In your web browser, visit http://localhost:8081, or the port reported by the server’s output.

CORS beware

Later, it will be important that you’re using localhost rather than 127.0.0.1 or your network IP address. The micro-frontends include localhost in their CORS whitelist.

Verify that you can see the expected web content:

Site showing text "Sample Site", "Paragraph one" and "Paragraph two"

This is the sample site into which we’ll embed our micro-frontend. We have styled in a garish and arbitrary way, so that we can see how the micro-frontend interacts with the styling. Feel free to modify the content or styling.

Embedding the Wealth Wizards micro-frontend

In this guide we’ll embed the micro-frontend at https://turo-green.wealthwizards.io/retirement-options-guidance/main.js. This is an instance of the Retirement Options Guidance tool, configured for Wealth Wizards' demo system, “Turo”.

You'll get, or may currently have your own URL

An instance of a micro-frontend has its own URL, and is configured for its intended consumer with visual styles, custom text content, parameters and policies.

Your Wealth Wizards account director will provide you with the URL for your instance of each micro-frontend.

In index.html make two additions:

A <div id="{app-name}"> where the micro-frontend should appear
A <script src="{micro-frontend's URL}"></script> as the last element of the <body>

<html>
  <head>
    <link rel="stylesheet" href="shell-styles.css" />
  </head>
  <body>
    <h1>Sample Site</h1>
    <p>Paragraph one</p>
    <div id="retirement-options-guidance"></div>
    <p>Paragraph two</p>
    <script src="https://turo-green.wealthwizards.io/retirement-options-guidance/main.js"></script>
  </body>
</html>

IDs are what our micro-frontends look for

The id attribute of the <div> is what the micro-frontend uses to find the mount point. It varies by tool.

Your Wealth Wizards account director will advise what ID to use for other tools.

Reload your site in the browser. Validate that the embedded content appears.

Site showing text "Sample Site", "Paragraph one" and the Retirement Options Guidance Tool micro-frontend

If you try interacting with the tool, you will notice that the address in browser’s address bar changes, for example to localhost:8081/form. This path tells the micro-frontend which of its pages to display. If you then reload the browser, you’ll get a 404 “Not found” error.

To fix this we need a “catch-all redirect”, serving index.html for these URLs. In the server used by this guide, we can achieve that by adding a command line option:

$ npx http-server --proxy http://localhost:8081?

(the trailing ? is significant)

Single page apps and catch-alls

The micro-frontends are single page applications (SPAs), and it’s typical to need a catch-all redirect to facilitate a SPA.

In a production service, you would configure rules to match appropriate paths, according to the layout of your site.

Advice on your specific production web server is beyond the scope of this guide.

Handling deeper paths

You might want to embed the micro-frontend in a deeper path. Let’s try that by moving our files to a subdirectory:

$ mkdir -p wealth/wizards
$ mv index.html shell-styles.css wealth/wizards/

… and visit http://localhost:8081/wealth/wizards/

This works, but if you use the tool, the address in the browser address bar changes to http://localhost:8081/form – our deeper path has been lost.

To solve this, you can supply the micro-frontend with the path by adding a context-root attribute to the mount point <div>:

<div id="retirement-options-guidance" context-root="wealth/wizards"></div>

Of course, you will also need to make your catch-all redirect go to the new location.

Calls To Action

If you navigate through the Retirement Options Guidance forms, you will reach the .../outlook page. Notice the cards at the bottom of the page:

Three call to action cards for booking appointments, calling the team, and online chat

These are “calls to action”. Wealth Wizards can configure the content and behaviour of your calls-to-action. There are three options, and we see an example of each. All calls-to-action contain a title and some paragraph text, and one of:

A button which links to an external URL (optionally opening in a new browser tab)
Phone info - a number and hours
A button which triggers a DOM CustomEvent. We will discuss this option in more detail.

Handling call to action events

Your shell may respond to events triggered by a call-to-action in any way you like. For example:

Navigate within your own application
Launch a chat overlay
Launch a popup or modal dialogue

Retirement Options Guidance calls-to-action publish events with a type of "retirement-options-guidance:action". Let’s add code to our sample shell to respond to those events.

Add a <script> within the <head> of index.html:

...
<head>
  <link rel="stylesheet" href="shell-styles.css" />
  <script>
    window.addEventListener('retirement-options-guidance:action', (event) =>
      alert(JSON.stringify(event.detail))
    )
  </script>
</head>
...

Reload your site in the browser, find “Chat online” and click it.

Browser alert from localhost:8081 with a JSON payload containing an action name of chat-online-now

You should use actionName to choose an appropriate response. For example:

window.addEventListener('retirement-options-guidance:action', ({ detail } => {
    switch(detail.actionName) {
       case 'chat-online-now':
          launchChat();
          break;
       case 'navigate-home': {
          navigateHome();
          break;
       }
       default:
          console.log(`Ignoring action: ${detail.actionName}`);
    }
});

Some actions are included, some would be bespoke

The possible values of actionName are specific to your bespoke calls-to-action configuration.

You will negotiate this configuration with your Wealth Wizards account director.

Wealth Wizards Analytics

It is a condition of your use of the micro-frontends, that you integrate Heap Analytics, which allows Wealth Wizards to analyse the application’s usage.

Wealth Wizards will provide you with a JavaScript snippet similar to this, which causes Heap to load.

<script type="text/javascript">
  // EXAMPLE
  ;(window.heap = window.heap || []),
    (heap.load = function (e, t) {
      ;(window.heap.appid = e), (window.heap.config = t = t || {})
      var r = document.createElement('script')
      ;(r.type = 'text/javascript'),
        (r.async = !0),
        (r.src = 'https://cdn.heapanalytics.com/js/heap-' + e + '.js')
      var a = document.getElementsByTagName('script')[0]
      a.parentNode.insertBefore(r, a)
      for (
        var n = function (e) {
            return function () {
              heap.push([e].concat(Array.prototype.slice.call(arguments, 0)))
            }
          },
          p = [
            'addEventProperties',
            'addUserProperties',
            'clearEventProperties',
            'identify',
            'resetIdentity',
            'removeEventProperty',
            'setEventProperties',
            'track',
            'unsetEventProperty',
          ],
          o = 0;
        o < p.length;
        o++
      )
        heap[p[o]] = n(p[o])
    })
  heap.load('00000000') // Wealth Wizards will supply this number
</script>

Wealth Wizards requires you to trigger this snippet when the user consents to performance cookies (also known as analytics cookies).

You may want to add this to your tag manager

It’s likely that you will achieve this using a tag manager, such as Google Tag Manager, Tealium or Adobe Launch.

It is your responsibility to ensure that Heap is loaded in compliance with cookie consent law.

You are of course welcome to load your own analytics tags, as long as you retain the Wealth Wizards Heap tag.

Legacy browsers

The micro-frontend loading mechanism requires a browser with a modern DOM. All mainstream browsers in their support period will work.

A sufficient check for a compliant browser, is to check that document.head.append exists.

You may wish to reveal a browser warning if this test fails:

<script>
  if (!document.head.append) {
    document.getElementById('browser-warning').style.display = 'block'
  }
</script>
<div id="browser-warning" style="display:none">
  <p>Sorry, this page requires a modern web browser.</p>
</div>

CORS

Your micro-frontend instance is protected by Cross Origin Resource Sharing headers. In brief, the responses from Wealth Wizards' servers contains a header indicating what it expects as the origin of the request. The browser will refuse to load the resource if this header isn’t satisfactory.

localhost:* is permanently configured as a permissible origin, but when you deploy your shell to a server, it’s possible that your origin won’t match Wealth Wizards' whitelist.

Please ask your account director to whitelist any test and production URLs on which you expect to access the shell.

It is possible to test a shell deployed to a URL that is not on Wealth Wizards' CORS whitelist, using a browser plugin to suppress CORS checks. Wealth Wizards cannot recommend a particular product.

Next steps

This guide has shown you how to embed a Wealth Wizards micro-frontend into a sample website. The same steps can be used in your own website.

Your Wealth Wizards account director can arrange to deploy the micro-frontend instances you need, and will supply you with the URLs and IDs you need to embed them.

Wealth Wizards can start you off with a default configuration, which will allow you to start embedding in a test environment. To update this to a full implementation, Wealth Wizard needs:

Your choices of
- branding (a limit applies)
- copy
- modelling parameters
- calls-to-action
CORS origins you would like whitelisted

Need assistance? Reach out to Wealth Wizards through the standard technical support channels.

How-to Guides