Embedding

To unlock the full potential of your data and analytic dashboards you will want to share them securely with your users. This is where embedding comes in. You can embed any dashboard in your application using the JavaScript Embedding API. No Iframes needed.

IFrames

If you need to use an IFrame or have other requirements for embedding, please reach out on Github.

If you are looking to share dashboards publicly, you can do so by creating a public link instead:

Share Dashboards Publicly

The general embedding workflow is as follows:

1. Get an API key
2. Generate a JWT token in your backend to give a user access to the specific dashboard
3. Use the JWT token to authenticate the user in your frontend

You can use the Embedding JS API directly or use the shaper-react library to embed Shaper into a React application.

Other Frameworks

If you like see deeper integration into other frameworks, please reach out on Github.

Example Applications

The fastest way to understand how to embed Shaper is to look at a complete example application:

Node.js Backend + JS API

React-Router + shaper-react

Step by Step

1. Create an API key

   1. In Shaper, click on “Admin” in the bottom-left.
   2. Then click on “API Keys” and then on “New”.
   3. Give the key a name and click “Create Key”.
   4. Copy the key and save it somewhere safe before closing the dialog.

2. Get a dashboard ID

   1. Open the dashboard you want to embed.
   2. Copy the ID from the URL

3. Include Shaper in your application:

   Standalone

   <script src="http://localhost:5454/embed/shaper.js"></script>

   React

   npm install shaper-react

4. Embed a dashboard into your frontend:

   Standalone

   <div id="dashboard-container"></div>
   <script>
       const dashboard = shaper.dashboard({
       container: document.getElementById("dashboard-container"),
       dashboardId: "<your-dashboard-id>",
       async getJwt({ baseUrl }) {
           // Call your backend, then return a valid JWT
       },
       });
   </script>

   React

   import { ShaperDashboard } from "shaper-react";
   // ...
   <ShaperDashboard
     baseUrl={"http://localhost:5454"}
     id={"<your-dashboard-id>"}
     jwt={jwt}
     refreshJwt={() => {
       // Call your backend, then set the `jwt` variable to a valid JWT
     }}
   />

5. Call the Shaper API from your backend to generate a JWT.

   Standalone

   Endpoint:

   POST http://localhost:5454/api/auth/token

   Request:

   {
       "token": "<your-api-key>",
       "dashboardId": "<your-dashboard-id>"
   }

   Response:

   {
       "jwt": "<generated-jwt>"
   }

   React

   const { jwt } = await fetch(`http://localhost:5454/api/auth/token`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       token: "<your-api-key>",
       dashboardId: "<your-dashboard-id>",
     }),
   })

   By default, the JWT is valid for 10 minutes. Make sure your application logic allows for generating a new JWT when the old one expires.

   Make sure to authenticate the user in your backend before generating the JWT and only allow access to the dashboard if the user is allowed to see it.

   Keep your API key safe

   Never show the API key to a user. Never send your API key to the frontend.

JWT Variables

Optional: Use variables to customize the dashboard to the user’s context and restrict what they are able to see.

You can pass an optional variables property to /api/auth/token to bind the generated JWT to specific variables.

Pass an object where each key is the name of the variable and the values are either strings or array of strings.

For example, your response body could look like this:

{
    "token": "<your-api-key>",
    "dashboardId": "<your-dashboard-id>",
    "variables": {
        "user_id": "123",
        "project_id": ["456", "789"]
    }
}

In SQL you can then use the variables like this:

SELECT count() FROM events WHERE user_id = getvariable('user_id');
SELECT * FROM projects WHERE project_id IN getvariable('project_id');

JWT variables override dashboard variables

Variables defined on the dashboard itself through dropdowns or other filters are overridden by JWT variables if they are using the same name.

How might have noticed the “Variables” section in the dashboard editor in the sidebar on the left. You can use this to emulate setting a JSON object as “variables” attribute in the JWT token.

In the above example apps you could try passing something like this:

{ "user_id": "user_1" }