Embeddable integrations

Learn about how you can build embeddable integrations in Plannr, blurring the lines between your product and Plannr.

Embeddable integrations allow users to smoothly blend their products with Plannr's interface, eliminating the hassle of forcing users to switch between different products.

By building an embeddable integration you get to build your product in one place, and then distribute it to multiple solutions without the need to rebuild. You also get to retain control of releasing your own updates and improvements, too.

An example of an embedded integration (Be-IQ) in Plannr.

Where can you embed?

The short answer is anywhere! You can build an embeddable integration for the adviser portal, or the client portal, or both! There are various pages in both the client and adviser-facing portals where an integrator might want their product to appear but to give you some examples, here are some pages that might appeal to you:

• The main dashboard of a contact (client) in the adviser-facing portal

• On a new page, in the client portal

• On the main adviser dashboard for Plannr

• At the top of the page when viewing a client record.

You can either build in-page elements (or widgets) to appear on part of a user's screen or we can build you a page where your product appears as the primary content.

How do I build an embeddable integration?

Largely speaking you would need to use a Javascript Single-Page-App (SPA) framework for this. We've worked with both VueJS and React embedded solutions in Plannr but you need to create your front-end using an SPA, build and publish to a URL and then share that URL with us.

Some key things to bear in mind; you'll need to compile your SPA to use something other than a div with an id of "app" as that's what our product uses (sorry!).

Also, we would recommend that you embed your CSS into your SPA too, and namespace your classes to use what ever HTML ID you use when compiling. E.g. if you set your VueJS SPA to latch onto a div with an ID of cashflow, you'll need to set your CSS selectors to match, e.g.

#cashflow p
{
    color: red;
}

If your product makes API calls back to your API, you'll need to bear in mind adding Plannr as a CORS entry on your API too as most modern browsers will block the requests.

How do we handle security?

In short, tokens! We would recommend that you build some sort of token mechanism to validate that Plannr was the source of the embeddable integration's load event. A simple flow outlining this is listed below:

1. User navigates to a page that contains your embedded widget.

2. On page load, an API call is made from Plannr's API to you asking for a token. Your system returns the token that Plannr should use for the request.

3. Plannr's API returns that token to the front-end, and the token is passed in as a prop to your embedded integration (see examples below).

4. Your solution validates the legitimacy of the generated token (we recommend limiting the life-span of the token to something around 10 minutes).

5. On successful verification, you load your embedded widget.

6. You can then make API calls back to your API and Plannr's via your integration.

An example of how we would load your embedded integration (using vue as an example) is shown below

<cashflow-overview token="{api_generated_token_here"/>

How does our integration get context?

We'll give it you as a prop when your embedded widget loads. For example, if you're integrated widget is set to load in the adviser-facing portal, but when viewing a client, we'll pass in the client uuid via a prop, like so:

<cashflow-overview token={see_above} account={client_uuid_here}/>

There are a number of different properties we can pass you as props to your integration. Some of them are listed below:

Prop	Description	Content type
token	The security token generated by your API used for verifying the validity of the request	String
client_uuid	The UUID of an account in Plannr	UUID4 (String)
firm_uuid	The UUID of the firm the adviser or client belongs to	UUID4 (String)
firm_object	A javascript object containing key information about the firm (such as name, branding)	Object
current_user_uuid	The UUID of the current logged in user	UUID4 (String)

How do we add our widget / integration?

Right now, we'll need to work with you to add your code to Plannr through one of our engineering team so you're best popping an email to [e-mail] to get this process kicked off.