embedded-example

Sample (and extremely simple) Flask app that can be used to test the Preset Embedding experience! Note that this app is solely intended to demonstrate the embedded implementation, and shouldn't be used in a Production environment.

How to use it

This project uses Python to run a Flask app. We strongly encourage using a Python Virtual environment to install it (this tutorial won't cover this part).

Implementation actions

Start by cloning the repository to your local environment. Then, duplicate the .env-example file, and save it as .env in the root folder (the file is automatically git-ignored). This file is responsible for providing the app with your credentials, team and dashboard information. Replace template values in there accordingly (you might need to add quotes if the values have special characters).

Let's take a look on how to fill it:

Authentication details (optional)

DISCLAIMER: Your API token and secret are only stored in this local file — this information is not processed or synced anywhere else. It's also possible to run this app without providing your credentials, however you would have to generate the Guest Token on your end (for example, using Postman), and then provide the Guest Token to the SDK. Additionally, the Guest Token is only valid for 5 minutes, so after that you might start facing errors when interacting with the embedded dashboard.

If you would like to avoid adding your credentials to this file, feel free to just skip this step, and provide the guest token directly OR authenticate using a PEM key.

• Replace your_api_token_here with a token created (and enabled) from Manager (line 3).
• Replace your_api_secret_here with its corresponding secret (line 4).

Refer to this page to check how to create your Preset API key/token.

Team, Workspace and Dashboard information

Make sure you have already enabled the Embedded mode for the dashboard you would like to use with this app. Refer to this page for further instructions. Replace these values with the information retrieved from the Embedded modal (from Preset):

• Replace your_dashboard_id_here with your Embedded Dashboard ID (line 8).
• Replace your_superset_domain_here with your Superset Domain (line 9).
• Replace your_preset_team_here with your Team ID (line 10).
• Replace your_workspace_slug_here with your Workspace ID (line 11).

Installing dependencies

1. Create a new virtual environment for this project.
2. Activate it.
3. Run pip install --upgrade pip to update pip.
4. Run pip install -r requirements/requirements.txt to install all dependencies for this project.

Running the application

1. Run flask --app app run --port=8080 --debug in the terminal (inside the root folder). This would start the Flask app. Feel free to change the --port value, but make sure you also update it in the frontend code. The --debug flag ensures the server automatically reloads when changes are saved to the app.py file.
2. Access http://127.0.0.1:8080/ on the browser. You should see an iframe in the full browser size, which would load the dashboard in embedded mode.

Stopping the app

1. Once testing is done, press control + C in the terminal to stop the Flask app.
2. Deactivate the virtual environment.

Changing the app configurations

Authentication

Since the Guest Token is only valid for 5 minutes, the SDK automatically refreshes it (when a function to generate a Guest Token is provided). This is configured with the fetchGuestToken parameter. By default, this test app is configured pointing to the fetchGuestTokenFromBackend() function.

const myLightDashboard = presetSdk.embedDashboard({
  id: dashboardId,
  supersetDomain: supersetDomain,
  mountPoint: document.getElementById("dashboard-container"), // any html element that can contain an iframe
  fetchGuestToken: async () => fetchGuestTokenFromBackend(), // `fetchGuestTokenFromBackend()` is a function that returns a Guest Token
  dashboardUiConfig: {},
});

Providing the SDK with a Guest Token directly

If you don't want to add your API credentials to this example app, you can instead provide a Guest Token directly to the fetchGuestToken parameter:

const myLightDashboard = presetSdk.embedDashboard({
  id: dashboardId,
  supersetDomain: supersetDomain,
  mountPoint: document.getElementById("dashboard-container"), // any html element that can contain an iframe
  fetchGuestToken: () => "{{myGuestToken}}", // Replace `{{myGuestToken}}` with the generated token
  dashboardUiConfig: {},
});

Refer to this API endpoint documentation to check how to generate a guest token.

Note that the token is only valid for 5 minutes, so since the SDK won't be able to refresh it, you'll start facing errors when trying to interact with the dashboard after that time.

PEM Key authentication

Note: You must have OpenSSL installed to be able to generate the keys.

To authenticate the guest user, two API calls are needed:

• One to authenticate your API credentials and retrieve a JWT token.
• Another one that uses this JWT to generate a guest_token.

It's possible to use a set of public and private PEM keys to generate the guest_token locally and avoid these two calls. Refer to this section if you want to generate the PEM keys on your end, or alternatively run below command to automatically create a key pair:

flask generate-keys

Then, use below command to copy the public key:

pbcopy < keys/embedded-example-public-key.pem

Access Preset Manager, click on the three ellipses for your Workspace and select Edit Workspace Settings. Then navigate to the Embedded tab, and paste the public key content. Finally, copy the Key Id visible in the UI, and add it to your .env file.

Then access http://localhost:8081/?auth_type=pem in the browser to load the embedded dashboard using a guest token that's encoded locally.

dashboardUiConfig parameters

The Preset SDK has configurations that can be modified to change the embedding experience. These can be configured using the dashboardUiConfig parameter. In this test app, this configuration is currently implemented in the templates/index.html file (line 44):

const myLightDashboard = presetSdk.embedDashboard({
  id: dashboardId,
  supersetDomain: supersetDomain,
  mountPoint: document.getElementById("dashboard-container"), // any html element that can contain an iframe
  fetchGuestToken: async () => fetchGuestTokenFromBackend(),
  dashboardUiConfig: {
    // dashboard UI config: hideTitle, hideChartControls (optional)
    hideTitle: false, // change it to `true` to hide the dashboard title
    hideChartControls: false, // change it to `true` to hide the chart controls (ellipses menu)
    filters: {
      expanded: true, // change it to `false` so that dashboard filters are collapsed (for vertical filter bar)
    },
    urlParams: { // URL parameters to be used with the ``{{url_param()}}`` Jinja macro
      param_name: "value",
      other_param: "value",
    }
  },
});

Customizing the Guest Token permissions

By default, the Guest Token is generated with no RLS applied, and access is only granted to the Dashboard ID specified previously. You can customize the Guest Token configuration in the app.py file (line 104):

payload = json.dumps({
    "user": {
        "username": "test_user",
        "first_name": "test",
        "last_name": "user"
    },
    "resources": [{
        "type": "dashboard",
        "id": dashboard_id,
    }],
    "rls": [
        //Add RLS rules here
    ]
})