What are Trevor embedded dashboards?

The "Embedded dashboards" feature in Trevor enables you to build beautiful interactive dashboards for your customers with no code! 

You can build, deploy and iterate fast on your dashboards with minimal engineering effort:

• Your team can build and iterate on a dashboard using our no-code query builder (or use SQL if they prefer).
• Your customers will access the dashboard via your web application or platform (they login to your application, not Trevor).
• Importantly: your customers will only have access to the dashboards that they should be allowed to access, and those dashboards will be filtered to show only the data relevant to that customer.
• An engineer just needs to perform an easy one-off integration (described below in How it works) and then any Trevor user in your team can do the rest using Trevor’s powerful no-code query builder.  This integration usually takes less than two hours.

How it works

• You embed the Trevor dashboards in your application either as an iframe or simply as a link that opens the dashboard, and as soon as a user's browser tries to access your dashboard in either of these ways we use a browser redirect to send them through your authorization flow.
• The flow is OAuth-like, in that a dashboard is effectively a resource that your customer wants access to, and your service is the authorization service that controls who can access what, and how that dashboard should be filtered for the user.
• This OAuth-like flow has certain advantages:
  1. You implement authorization once (as described below) and then you can confidently embed the dashboards anywhere in your application, knowing that the security step will automatically be dealt with.
  2. Your users can share links to dashboards with other members of their team, and they will automatically be pushed through your login flow to ensure that everyone only sees what they are allowed to see.

Integrating Trevor dashboards in your application

If you open any of your dashboards in Trevor and click Share -> Embed dashboard -> Configure dashboard embed you will see your API Key, as well as a box for you to provide us with a Redirect URL(note: you need to be a Trevor admin on your datasource to see this).

• The API Key is for you to store securely on your backend (do not use this from your front-end code).  This will be used to give your customers access to dashboards.
• The Redirect URL is a URL for your own application, e.g. https://<your-domain>/login/trevor/auth (and during testing you can use, for example: http://localhost:<port>/login/trevor/auth).  

You now just need to implement the /login/trevor/auth endpoint on your side:

• When user tries to access a dashboard (via a link in your platform on via an embedded iframe) Trevor will redirect the browser to the provided Redirect URL, together with a resource_type and resource_id as parameters (e.g. https://<your-domain>/login/trevor/auth?resource_type=dashboard&resource_id=3359b5a6-7b87-4bb1-8961-2f9448f3e738&state=state)
• Your/login/trevor/auth endpoint should now check your user session to confirm that logged-in user is authorized to access the given dashboard, and if so, request access for them like so:

//
// *important*: for security reasons, this POST request should be called from your *server-side*, not client side
//
fetch('https://app.trevor.io/embedded/auth', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
	'Authorization': `Bearer ${apiKey}` // API Key provided by Trevor
    },
    body: JSON.stringify({
	resourceType: resourceType, // resource_type passed to you as a request parameter
	resourceId: resourceId, // resource_id passed to you as a request parameter
	expiresInSeconds: 60*60*24, //how long to give user access to the dashboard for (before sending them back to your Redirect URL for re-authorization)
        filters: [{ // any filters whose value you want to override (doesn't need to be all of them and can be an empty array)
		name: 'customer',// the name of the dashboard filter to override (click "Configure" on any dashboard filter in Trevor to see "Filter name")
		value: [customerId], // value to apply to the filter (can also be a single value if using a different operator below)
		operator: 'ONE_OF', // can be one of ONE_OF, NOT_ONE_OF, EQ, NOT, LT, LTE, GT, GTE, CONTAINS, NOT_CONTAINS, etc.
		required: true, // fail auth if filter is missing on the dashboard (recommended)
		hidden: true, // will hide this filter on the dashboard (set to true if you don't want users to be able to change the value)
	}]
    })
});

• Request will respond with a URL like so:

{
	'success': true,
	'nextUrl': 'https://trevor.io/embedded/dashboard/3359b5a6-7b87-4bb1-8961-2f9448f3e738?access_code=1e01c46f-a09c-45d5-8c56-2b5f5d9508ba&state='
}

• You should now redirect the user’s request to this URL, and they will see the dashboard.
  • The access_code parameter on the nextUrl URL is a short-lived, single-use token that gives them access to the dashboard for expiresInSeconds seconds.
  • Once their session expires they will be redirected back to your Redirect URL again.
  • You can optionally pass a state parameter to the dashboard URL, which will get passed along to Redirect URLwhen their access expires.
• If a visitor arrives at Redirect URL who is not logged into your platform, send them through your login flow, before sending them back to Redirect URL(like you would anyway for any non-public page on your website).
• If they are logged in, but should not have access to the dashboard, show them an appropriate message.

An implementation in Node might look like this:

app.get('/login/trevor/auth', auth.isLoggedIn, async (req, res) => {
    const resourceType = req.query.resource_type
    const resourceId = req.query.resource_id
    const countries = countries.list(req.user);
    try {
        const { data: authResponse } = await axios.post(`https://app.trevor.io/embedded/auth`, {
            resourceType,
            resourceId,
            expiresInSeconds: 60 * 60 * 24,
            filters: [{
                name: 'country',
                value: countries,
                hidden: true,
                operator: 'ONE_OF',
                required: true
            }],
        }, {
            headers: {
                Authorization: `Bearer ${process.env.API_KEY}`
            }
        });

        if (authResponse.success) {
            res.redirect(authResponse.nextUrl)
        } else {
            res.render('error', { errors: authResponse.errors})
        }
    } catch (e) {
        handleError(e)
    }
})

Troubleshooting

If you run into any issues, please don't hesitate to contact us via our live chat, at the bottom right of the Trevor platform. We're here to help.

Example application

A basic example of embedding a dashboard in a Node app can be found here.