Live embedding PowerMetrics visualizations

With live embedding, you can display dynamic versions of PowerMetrics visualizations externally, for example, in a website or custom data app. Security is enabled and ensured using a Klipfolio API Key and embedded client secret (as defined on your internal server). Embed code is generated in PowerMetrics based on the visualization you choose in Explorer. This code is then copied to your HTML page for end-user consumption as an interactive or read-only display.

End-users interact with embedded visualizations based on a set of parameters you configure – ranging from read-only to full-personalization access. When given full access, their experience is almost identical to that of a typical PowerMetrics user investigating their data in Explorer.

Notes:

• When you sign up for a free PowerMetrics trial, you’ll get access to live embedding for 30 days. To continue using this feature when your trial ends, make sure you choose a plan that includes “live embedding”.
• After creating a live embed, if changes are made to the associated visualization in Explorer and you want to update the embed, you must copy the updated embed code in Explorer and replace the previous code in your HTML page.
• iOS/Safari is currently not supported. Visualizations will not display due to third-party cookies being blocked by Safari.

This article includes:

• Client configuration: Setting up authentication and creating an embed client secret
• Server configuration and JWT requirements
  • JWT requirements
  • NodeJS Express server configuration example
• Creating the visualization in PowerMetrics Explorer
• Retrieving the embed code and customizing display and interactivity settings
• Adding the embedded visualization to your website or app
• Troubleshooting

Client configuration: Setting up authentication and creating an embed client secret

About Klipfolio API Keys and users: API keys in Klipfolio are unique to each user. Users in PowerMetrics are each assigned to a set of permissions that controls their access to internal assets. Authenticating with a user’s API key provides the permission base for your client, giving live embed access to the same metrics as the associated user/API key.

We recommend you add a single user to Klipfolio that will be used to enable/add live embeds.

To set up authentication with Klipfolio and create an embed client secret:

1. Generate and copy your Klipfolio API Key.
   In Klipfolio PowerMetrics, click the button located in the left navigation sidebar and select My Profile. Click the Edit button beside General Information. At API Key, click Generate New API Key > Generate. Copy the API Key for use in the next step.
2. Use your Klipfolio API Key to call the create client endpoint.
   POST URL:
   '/gateway/pm-embed/api/v1/client?name=<Enter an identifying name for the client>'
   cURLcommand:
   curl --location --request POST
'https://app.klipfolio.com/gateway/pm-embed/api/v1/client?name=<name>' \
--header 'kf-api-key: <api-key>'
   This creates an “embed client secret”, which is composed of 2 variables: the Client Secret and the Client ID.
   Example of a response in JSON format:
   {
  "name": "test",
  "sharedSecret": "<secret>",
  "id": "<id>"
}
3. Save the Client Secret (<secret>) and the Client ID (<id>) securely in your system.
   You’ll need to enter this information when configuring your server.

Server configuration and JWT requirements

Set up a server on your system that will be used to sign JWT tokens on your server network. You’ll need to copy the URL endpoint to communicate with this server.

Note: The server must return a signed JWT with the client ID and Secret as plain text.

Enter the Client Secret and the Client ID you created above into the appropriate place in the code, for example:

...

.env file

SECRET="<Secret>"

ID="<Id>"

...

JWT requirements

• Client Secret and ID as plain text
• Registered claims and header, as described in the following table

The following items are in the JWT header:

The following items are in the JWT payload:

NodeJS Express server configuration example:

require('dotenv').config();
const express = require('express');
const jwt = require('jsonwebtoken');
const cors = require("cors")

const app = express();

const secretKey = process.env.SECRET;
const kid = process.env.ID
const corsOptions = {

  origin: 'http://127.0.0.1:5500'
};

app.use(cors(corsOptions));

app.post('/sign', (req, res) => {

    jwt.sign({

        resources: []

    }, secretKey, {keyid: kid, audience: "powermetrics"}, (err, token)
=> {

        if (err) {

            return res.status(500).send({ error: 'Failed to sign token' });

        }

        res.status(200).send(token);

    });

});

const PORT = process.env.PORT || 3002;

app.listen(PORT, () => {

    console.log(`Server is running on port ${PORT}`);

});

Creating the visualization in PowerMetrics Explorer

Metric visualizations are created in Explorer and composed of single metrics or multiple metrics combined as a single multi-metric. When you’re finished building the visualization for your live embed, a single click provides you with the code to copy and paste into your HTML. Learn how to create metrics in Explorer.

Retrieving the embed code and customizing display and interactivity settings

After creating the metric visualization you want to embed, you’ll view, customize, and copy its embed code.

1. In Explorer, click the 3-dot menu in the top nav bar and select View embed code. The embed code displays as a pop-up. (See example below.)
   
2. Choose display and interactivity settings.
   • Theme - Choose the desired theme (system settings, light, or dark) for the live embed. You can optionally configure this setting in the HTML code as, for example, theme=”dark”.
   • Filters - Select View to prevent end users from making changes to the date range and filter settings in the live embed. Select Edit to allow interactive access. Note: Read only is the default setting. You can optionally make the live embed interactive by entering readOnly=”false” into the HTML code.
   • Properties panel - Select Hide to prevent the right-side properties panel from displaying in the live embed. Select Show to display the properties panel and allow end users to personalize the visualization’s properties, for example, changing the chart type. Note: The properties panel is hidden by default. You can optionally configure it to display by entering showPropsPanel=”true” into the HTML code.
3. Click the Copy embed code button.

Adding the embedded visualization to your website or app

1. To add the embed to your website or app, enter the embed client script, for example,
   <script
src=”https://app.klipfolio.com/gateway/pm-embed/js/embed-client.js” type=”module”></script> into the <head> of your website.
2. Load in script module from the PowerMetrics CDN in <head> or before the <embed-client> code execution.
3. Paste the embed code you copied from PowerMetrics into your HTML page.
4. Replace the two placeholder values in the copied embed code, as follows:
   • At the token attribute, replace the <url> placeholder text with the url endpoint of the backend service you created earlier. You can authenticate this request using http-only cookies.
   • At id, replace the <id> placeholder text with an alphanumeric identifier that represents the current embed client and is unique to the webpage it’s live on.

Troubleshooting

If end users see the error “No data found” this means you’ve entered code to intentionally block them from seeing the visualization. You might want to ensure the access is correctly configured and, if not, make changes to it. Otherwise, no action is required.

If end users see the error “Can’t load live embed” there may be an issue with connectivity or the back end server is or was down. The suggested solution is to refresh the page and try again. We recommend you inspect the developer console for additional error information to ensure it’s not related to the server setup, for example, there may be a communication issue.