Skip to content
Snippets Groups Projects
Unverified Commit 3b4ecc7f authored by Natalie's avatar Natalie Committed by GitHub
Browse files

docs - embedding (#24996)

parent 4a717723
Branches
Tags
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 336 additions and 253 deletions
docs/README.md
+ 5
− 5
View file @ 3b4ecc7f
......@@ -60,6 +60,7 @@ redirect_from:
- [Sharing answers](./questions/sharing/answers.md)
- [Visualizing data](./questions/sharing/visualizing-results.md)
- [Setting and getting alerts](./questions/sharing/alerts.md)
- [Public links](./questions/sharing/public-links.md)
## Dashboards
......@@ -118,11 +119,9 @@ redirect_from:
## Embedding questions and dashboards
- [Overview](./embedding/start.md)
- [Embedding Metabase in other applications](./embedding/introduction.md)
- [Public links for dashboards and questions](./embedding/public-links.md)
- [Customizing the appearance of embedded items](./embedding/customize-embeds.md)
- [Embedding the entire Metabase app in your own web app](./embedding/full-app-embedding.md)
- [White labeling charts (branding)](./embedding/whitelabeling.md)
- [Embedding introduction](./embedding/introduction.md)
- [Signed embedding](./embedding/signed-embedding.md)
- [Full-app embedding](./embedding/full-app-embedding.md)
- [Embedding example apps](https://github.com/metabase/embedding-reference-apps)
## Databases
......@@ -144,6 +143,7 @@ redirect_from:
- [Configuring logging](./configuring-metabase/log-configuration.md)
- [Handling timezones](./configuring-metabase/timezones.md)
- [Localization](./configuring-metabase/localization.md)
- [Appearance](./configuring-metabase/appearance.md)
- [Caching query results](./configuring-metabase/caching.md)
- [Custom map settings](./configuring-metabase/custom-maps.md)
- [Customizing the Metabase Jetty Webserver](./configuring-metabase/customizing-jetty-webserver.md)
......
docs/embedding/whitelabeling.md → docs/configuring-metabase/appearance.md
+ 11
− 5
View file @ 3b4ecc7f
---
title: White labeling Metabase
title: Appearance
redirect_from:
- /docs/latest/administration-guide/whitelabeling
- /docs/latest/enterprise-guide/whitelabeling
- /docs/latest/enterprise-guide/customize-embeds
- /docs/latest/embedding/whitelabeling
- /docs/latest/embedding/fonts
- /docs/latest/embedding/customize-embeds
---
# White labeling Metabase
# Appearance
{% include plans-blockquote.html feature="White labeling" %}
{% include plans-blockquote.html feature="Custom appearance" %}
White labeling lets you customize Metabase's appearance so that it matches your company’s branding.
Appearance setttings give you the option to white label Metabase to match your company’s branding.
## Changing Metabase's appearance
......@@ -75,4 +79,6 @@ Show the Metabase lighthouse image on the home and login pages.
## Further reading
- [Brand your Metabase](https://www.metabase.com/learn/embedding/brand)
- [Customer-facing analytics](https://www.metabase.com/learn/embedding/).
- [Embedding introduction](../embedding/start.md).
- [Brand your Metabase](https://www.metabase.com/learn/embedding/brand).
docs/configuring-metabase/environment-variables.md
+ 2
− 2
View file @ 3b4ecc7f
......@@ -108,7 +108,7 @@ Type: string<br>
Default: `"Lato"`<br>
Since: v44.0
Change the font used in Metabase. See [fonts](../embedding/fonts.md).
Change the font used in Metabase. See [fonts](../configuring-metabase/fonts.md).
### `MB_APPLICATION_FONT_FILES`
......@@ -134,7 +134,7 @@ Tell Metabase which font files to use for different styles. Example value:
]
```
See [fonts](../embedding/fonts.md).
See [fonts](../configuring-metabase/fonts.md).
### `MB_APPLICATION_LOGO_URL`
......
docs/embedding/fonts.md → docs/configuring-metabase/fonts.md
+ 5
− 10
View file @ 3b4ecc7f
......@@ -2,6 +2,7 @@
title: Fonts
redirect_from:
- /docs/latest/enterprise-guide/fonts
- /docs/latest/embedding/fonts
---
# Fonts
......@@ -10,11 +11,6 @@ redirect_from:
On paid plans, you can customize the font Metabase uses (the default is [Lato](https://fonts.google.com/specimen/Lato)). You can choose from a curated set of Google Fonts that accommodate the regular, bold, and heavy font weights that Metabase relies on for its various UI elements.
You can set fonts for:
- [Your entire Metabase](./whitelabeling.md)
- [Individual embedded charts and dashboards](./customize-embeds.md#setting-fonts-for-embedded-items)
## Included fonts
To change your Metabase font, click on the **gear** icon in the upper right of the screen and select **Admin settings** > **Settings** > **Appearance**. Under **Font**, select from a list of included fonts.
......@@ -126,11 +122,10 @@ To support multiple character sets, for example both Latin and Cyrillic, you'll
## Customizing the font for individual embedded items
In addition to the [included fonts](#included-fonts), if you set a custom font for your Metabase, that font will be selectable as the "Use instance font" in menus. See [Customize embeds](./customize-embeds.md).
In addition to the [included fonts](#included-fonts), if you set a custom font for your Metabase, that font will be selectable from "Use instance font" in [signed embeds](../embedding/signed-embedding.md).
## Further reading
- [White labeling Metabase](./whitelabeling.md)
- [Customizing Metabase's appearance](./appearance.md)
- [Customer-facing analytics](https://www.metabase.com/learn/embedding/)
- [Embedding documentation](../embedding/start.md)
docs/configuring-metabase/start.md
+ 4
− 0
View file @ 3b4ecc7f
......@@ -24,6 +24,10 @@ Set up Slack for Alerts and Dashboard subscriptions.
Set language, datetime, and currency settings.
## [Appearance](./appearance.md)
Customize colors, fonts, and other visual elements.
## [Caching](./caching.md)
Cache query results for faster loading times.
......
docs/embedding/customize-embeds.md deleted 100644 → 0
+ 0
− 47
View file @ 4a717723
---
title: Customizing embedded charts
redirect_from:
- /docs/latest/enterprise-guide/customize-embeds
---
# Customizing embedded charts
{% include plans-blockquote.html feature="Advanced embedding features" %}
Some paid plans give you additional customization options for [embedded items](./introduction.md).
## Remove the "Powered by Metabase" banner
![Powered by Metabase](./images/powered-by-metabase.png)
Charts and dashboards won't show the branded Metabase label at the bottom.
## Setting fonts for embedded items
You can set the font for the embedded chart or dashboard. You can select from a list of [included fonts](./fonts.md).
If you've set a custom font for your Metabase, that font will be selectable as "Use instance font".
### Use instance font
If you select "Use instance font", the font for your embedded item will sync with whatever you've set your [Metabase font](./fonts.md) to. So if you change the font for your Metabase (your "instance"), the font used for the embedded item will change as well. There's no need to update the embedding code; the embedded item's font should update automatically (though you may need to refresh your browser).
If you want to use a font different from your current instance font, you can select one of the [included fonts](./fonts.md). You cannot have multiple custom fonts.
### Changing custom fonts
If you want to use a different custom font, and by custom here we mean a font other than one of the included fonts, you'll need to change the [custom font](./fonts.md#custom-fonts) for your Metabase instance. Changing the instance font will update all embedded items that have their font set to "Use instance font".
For now, you cannot have multiple custom fonts; you can only override your instance font with one of the included fonts.
## Disable data download
You can remove the export icon from charts. Note that removing the icon here doesn't totally prevent people from exporting the data; treat it as a deterrent, not a security option. Removing the icon just cleans up the embedded chart a bit, and makes downloading the data a bit of a hassle.
## Further reading
- [Embedding Metabase in other applications](./introduction.md)
- [White labeling Metabase](./whitelabeling.md)
- [Fonts](./fonts.md)
- [Learn embedding](https://www.metabase.com/learn/embedding)
docs/embedding/full-app-embedding.md
+ 4
− 4
View file @ 3b4ecc7f
......@@ -158,7 +158,7 @@ When signing JWTs for either SSO (i.e., in full-app embedding) or standalone que
## Further reading
- [White labeling](whitelabeling.md)
- [Deliver analytics to your customers](https://www.metabase.com/learn/building-analytics/dashboards/linking-filters.html)
- [Embed Metabase in your app to deliver multi-tenant, self-service analytics](https://www.metabase.com/learn/developing-applications/advanced-metabase/multi-tenant-self-service-analytics.html)
- [Create charts with explorable data](https://www.metabase.com/learn/developing-applications/advanced-metabase/multi-tenant-self-service-analytics.html)
- [Customizing Metabase's appearance](../configuring-metabase/appearance.md).
- [Strategies for delivering customer-facing analytics](https://www.metabase.com/learn/embedding/embedding-overview).
- [Publishing data visualizations to the web](https://www.metabase.com/learn/embedding/embedding-charts-and-dashboards).
- [Multi-tenant self-service analytics](https://www.metabase.com/learn/embedding/multi-tenant-self-service-analytics).
docs/embedding/introduction.md
+ 23
− 149
View file @ 3b4ecc7f
---
title: Embedding Metabase in other applications
title: Introduction to embedding
redirect_from:
- /docs/latest/administration-guide/13-embedding
- /docs/latest/administration-guide/12-public-links
---
# Embedding Metabase in other applications
# Introduction to embedding
Metabase includes a powerful application embedding feature that allows you to embed your saved questions or dashboards in your own web applications. You can even pass parameters to these embeds to customize them for different users.
You can embed Metabase tables, charts, and dashboards—even Metabase's query builder—in your website or application.
## Key Concepts
[Signed embedding](./signed-embedding.md) (also known as standalone embedding) and [full-app embedding](./full-app-embedding.md) are _secure_ ways to share your data with specific groups of people outside of your organization.
### Applications
If you'd like to share your data with the good people of the internet, you can create a [public link](../questions/sharing/public-links.md) and embed that directly on your website.
An important distinction to keep in mind is the difference between Metabase and the embedding application. The charts and dashboards you will be embedding live in the Metabase application, and will be embedded in your application (i.e. the embedding application).
## How embedding works
### Parameters
You'll need to put an iframe on your website to act as a window to your Metabase app. Different configurations of that embedded iframe will let you:
Some dashboards and questions have the ability to accept [parameters](../questions/native-editor/sql-parameters.md). In dashboards, these are synonymous with [dashboard filters](../dashboards/filters.md). For example, if you have a dashboard with a filter on `Publisher ID`, this can be specified as a parameter when embedding, so that you could insert the dashboard filtered down to a specific `Publisher ID`.
- [set up public access](../questions/sharing/public-links.md) to charts and dashboards,
- [require sign-in](./signed-embedding.md) to view personalized versions of those charts and dashboards, or
- [integrate with SSO and data permissions](./full-app-embedding.md) to enable self-service access to the underlying data.
SQL-based questions with template variables can also accept parameters for each variable. So for a query like:
## Comparison of embedding types
```
SELECT count(*)
FROM orders
WHERE product_id = {% raw %}{{productID}}{% endraw %}
```
you could specify a specific `productID` when embedding the question.
### Signed parameters
In general, when embedding a chart or dashboard, the server of your embedding application will need to sign a request for that resource.
If you choose to sign a specific parameter value, that means the user can't modify that value, nor is a filter widget displayed for that parameter. For example, if the `Publisher ID` is assigned a value and the request signed, that means the front-end client that renders that dashboard on behalf of a given logged-in user can only see information for that publisher ID.
## Enabling embedding
To enable embedding, go to the **Admin Panel** and select **Embedding in other Applications** from the left sidebar. When you click **Enable**, you'll see an **Embedding secret key** you can use later to sign requests. If you ever need to invalidate that key and generate a new one, just click on **Regenerate key**.
![Enabling Embedding](./images/01-enabling.png)
You can also see all questions and dashboards that have been marked as embedded here, as well as revoke any questions or dashboards that should no longer be embeddable in other applications.
Once you've enabled the embedding feature on your Metabase instance, next you'll want to set up individual questions and dashboards for embedding.
## Embedding charts and dashboards
To make a question or dashboard embeddable, click the **Sharing icon** (the box with an arrow pointing up and to the right) at the bottom right of the question.
![Share icon](./images/02-share-icon.png)
For dashboards, the sharing icon is at the top of the dashboard:
![Dashboard sharing icon](./images/dashboard-sharing-icon.png)
Then select **Embed this question in an application**.
![Enable sharing for a question](./images/03-enable-question.png)
You'll see a preview of the question or dashboard as it will appear in your application, as well as a panel showing the code you'll need to insert in your application. You can alternate between the preview and code with the toggle near the top of the page.
![Preview](./images/04-preview.png)
## Publishing your embedded item
In order for the embedding to work, you'll need to hit **Publish**. You'll need to hit the **Publish** button whenever:
- You first set up a chart or dashboard for embedding
- *and* each time you change any embedding settings.
Also, any changes you make to the embedding settings may require you to update the code in your own application so that it matches the latest code sample Metabase generates.
![Code samples for embedding](./images/05-code.png)
Metabase provides code samples for common frontend template languages, as well as some common backend web frameworks and languages. You can also use these code samples as starting points for writing your own versions in other platforms.
If you want to remove the **Powered by Metabase** label, you'll need to upgrade to a [paid plan](https://www.metabase.com/pricing).
## Embedding charts and dashboards with locked parameters
If you wish to have a parameter locked down to prevent your embedding application's end users from seeing other users' data, you can mark parameters as "Locked." This will prevent that parameter from being displayed as a filter widget, so its value must instead be set by the embedding application's server code.
![Locked parameters](./images/06-locked.png)
When using locked Field Filters with multiple selected values, then it is provided as a JSON array. Example:
```
...
params: {
foo: ['Value1', 'Value2'],
},
...
```
## Hiding parameters
If you have parameters that aren't required, but that you'd like to be hidden, instead of marking them as Locked you can use the `hide_parameters` URL option to hide one or more parameters (i.e., prevent it from showing up as a filter widget on screen). You'll want to add this option to the Metabase URL specified in your embedding iframe.
For example, if you have a parameter called "ID," in this example the ID filter widget would be hidden:
```
/dashboard/42#hide_parameters=id
```
If you want, you can also simultaneously assign a parameter a value and hide the widget like this:
```
/dashboard/42?id=7#hide_parameters=id
```
Note that the name of the parameter in the URL should be specified in lower case, and with underscores instead of spaces. So if your parameter was called "Filter for User ZIP Code," you'd write:
```
/dashboard/42#hide_parameters=filter_for_user_zip_code
```
You can specify multiple parameters to hide by separating them with commas, like this:
```
/dashboard/42#hide_parameters=id,customer_name
```
To specify multiple values for filters, though, you'll need to separate them with ampersands (&), like this:
```
/dashboard/42?id=7&customer_name=janet
```
## Resizing dashboards to fit their content
Dashboards are a fixed aspect ratio, so if you'd like to ensure they're automatically sized vertically to fit their contents you can use the [iFrame Resizer](https://github.com/davidjbradshaw/iframe-resizer) script. Metabase serves a copy for convenience:
```
<script src="http://metabase.example.com/app/iframeResizer.js"></script>
<iframe src="http://metabase.example.com/embed/dashboard/TOKEN" onload="iFrameResize({}, this)"></iframe>
```
## Additional parameters
To change the look and feel of the embed, you can add additional parameters to the embedding URL:
- **Bordered**: true or false. Adds a visible border to the embed.
- **Titled**: true or false. Adds or removes the title to the embedding.
- **Theme**: light, transparent, or night. Shows the embedded iframe in light (theme is null), transparent (no background), or night (dark mode).
For example:
```
http://yourmetabaseurl.com/embed/dashboard/a_very_huge_hashed_url#theme=night&hide_parameters=category&titled=true&bordered=false
```
These settings can also be changed under **Style** when previewing the embedded question or dashboard and its code in Metabase.
## Embedding reference applications
To see code examples of how to embed Metabase in applications using a number of common frameworks, check out our [reference implementations](https://github.com/metabase/embedding-reference-apps) on Github.
## Customizing embeds
Paid plans include additional features for [customizing the appearance](./customize-embeds.md) of embedded items.
| | [Public](../questions/sharing/public-links.md) | [Signed](./signed-embedding.md) | [Full-app](./full-app-embedding.md) |
| -----------------------------------------------------------------------------------------------------------| -----------------------------------------------| ------------------------------- | ----------------------------------- |
| Display charts and dashboards | ✅ | ✅ | ✅ |
| Display interactive [filter widgets](https://www.metabase.com/glossary/filter_widget) | ✅ | ✅ | ✅ |
| Restrict data with [locked filters](./signed-embedding-parameters.md#pre-filtering-data-in-a-signed-embed) | ❌ | ✅ | ❌ |
| Restrict data with [sandboxes](../permissions/data-sandboxes.md) | ❌ | ❌ | ✅ |
| Drill-down using the [action menu](https://www.metabase.com/glossary/action_menu) | ❌ | ❌ | ✅ |
| Self-serve via [query builder](https://www.metabase.com/glossary/query_builder) | ❌ | ❌ | ✅ |
## Further reading
- [Embedding track](https://www.metabase.com/learn/embedding) in Learn Metabase.
- [Strategies for delivering customer-facing analytics](https://www.metabase.com/learn/embedding/embedding-overview).
- [Publishing data visualizations to the web](https://www.metabase.com/learn/embedding/embedding-charts-and-dashboards).
- [Multi-tenant self-service analytics](https://www.metabase.com/learn/embedding/multi-tenant-self-service-analytics).
- [Customizing Metabase's appearance](../configuring-metabase/appearance.md).
docs/embedding/signed-embedding-parameters.md 0 → 100644
+ 114
− 0
View file @ 3b4ecc7f
---
title: Parameters for signed embeds
---
# Parameters for signed embeds
Also known as: parameters for standalone embeds.
Parameters are pieces of information that are passed between Metabase and your website via the [embedding URL](./signed-embedding.md#adding-the-embedding-url-to-your-website). You can use parameters to specify how Metabase items should look and behave inside the iframe on your website.
Parameters are added to the end of your embedding URL, like this:
```
your_embedding_url?parameter_name=value
```
## Adding a filter widget to a signed embed
You can add [filter widgets](https://www.metabase.com/glossary/filter_widget) to embedded dashboards or SQL questions.
1. Go to your dashboard or SQL question. Make sure you've set up a [dashboard filter](../dashboards/filters.md) or [SQL variable](../questions/native-editor/sql-parameters.md).
2. Click on the **sharing icon** > **Embed this item in an application**.
3. Under **Parameters**, you'll find the names of your dashboard filters or SQL variables.
4. Select **Editable** for each parameter that should get a filter widget on your embed.
5. Click **Publish** to save your changes.
**Editable** parameters are responsible for passing filter values from the embedded filter widget (displayed on the iframe) through to the filters on your original dashboard or SQL question (in your Metabase).
## Populating an embedded filter widget with a default value
If you want to set a default value for your [embedded filter widget](#adding-a-filter-widget-to-a-signed-embed), you can pass that default value to the corresponding parameter name in the embedding URL. Note that:
- Parameter _names_ are lowercase.
- Parameter _values_ are case-sensitive (they must match your data).
- Spaces should be replaced by underscores.
For example, if your embedded dashboard has a filter called "Breakfast", and you want to set the default value to "Scrambled eggs":
```
your_embedding_url?breakfast=Scrambled_eggs
```
To specify default values for more than one filter, separate them with ampersands (&):
```
your_embedding_url?breakfast=Scrambled_eggs&lunch=Grilled_cheese
```
If the original dashboard's filter widget accepts multiple values (i.e., it's a [dropdown filter](../dashboards/filters.md#choosing-between-a-dropdown-or-autocomplete-for-your-filter), not a text box filter), you can set multiple default values:
```
your_embedding_url?breakfast=Scrambled_eggs&breakfast=Bacon
```
## Pre-filtering data in a signed embed
If you want to display filtered data in an embedded dashboard or SQL question, and _prevent_ people from viewing or changing that filter:
1. Go to your dashboard or SQL question. Make sure you've set up a [dashboard filter](../dashboards/filters.md) or [SQL variable](../questions/native-editor/sql-parameters.md).
2. Click on the **sharing icon** > **Embed this item in an application**.
3. Under **Parameters**, you'll find the names of your dashboard filters or SQL variables.
4. Select **Locked** for each parameter that should pre-filter your data.
5. Add values for the filter under **Preview locked parameters**.
6. Click **Publish** to save your changes.
**Locked** parameters will apply the selected filter values to your original dashboard or SQL question, but they won't be displayed as filter widgets on your embed. You can use locked parameters to display filtered data based on attributes captured by your web server (such as a user's login). See the [reference apps repo](https://github.com/metabase/embedding-reference-apps) for more examples.
Note that you can only add filter values that match the filter type on the _original_ dashboard or SQL question. For example, if you have a text box filter on your original dashboard or SQL question, you'll only be able to add a single filter value to your locked parameter. If you want to provide multiple filter values to the parameter, you'll need to change the original filter to a [dropdown filter](../dashboards/filters.md#choosing-between-a-dropdown-or-autocomplete-for-your-filter) first.
## Hiding filter widgets from a signed embed
If you have a lot of **Editable** parameters (resulting in a lot of filter widgets), you can hide them from your signed embed by adding `hide_parameters` to your embedding URL.
For example, if you want to hide a filter called "Breakfast" from your embedded dashboard:
```
your_embedding_url#hide_parameters=breakfast
```
You can hide multiple filter widgets by separating the parameter names with commas:
```
your_embedding_url#hide_parameters=breakfast,lunch
```
You can also simultaneously assign a parameter a default value _and_ hide its filter widget:
```
your_embedding_url?breakfast=Scrambled_eggs#hide_parameters=breakfast
```
## Customizing the appearance of a signed embed
You can change the appearance of an embedded item by adding parameters with the following values:
| Parameter name | Possible values |
| -------------- | ------------------------ |
| bordered | true, false |
| titled | true, false |
| theme | null, transparent, night |
Preview the changes from your question or dashboard's [embedded appearance settings](./signed-embedding.md#customizing-the-appearance-of-signed-embeds).
For example, the following embedding URL will display an embedded item in dark mode, with its original title, and without a border:
```
your_embedding_url#theme=night&titled=true&bordered=false
```
## Further reading
- [Signed embedding documentation](./signed-embedding.md).
- [Strategies for delivering customer-facing analytics](https://www.metabase.com/learn/embedding/embedding-overview).
- [Publishing data visualizations to the web](https://www.metabase.com/learn/embedding/embedding-charts-and-dashboards).
docs/embedding/signed-embedding.md 0 → 100644
+ 133
− 0
View file @ 3b4ecc7f
---
title: Signed embedding
---
# Signed embedding
Also known as: standalone embedding.
In general, embedding works by displaying a Metabase URL inside an iframe on your website. A **signed embed** (or standalone embed) is an iframe that's secured with a signed JSON Web Token (JWT). The signed JWT will prevent website visitors from poking around in your Metabase through the iframe.
Signed embeds can't be combined with [data sandboxes](../permissions/data-sandboxes.md) because signed JWTs don't create user sessions (server-side sessions).
To restrict data in signed embeds for specific people or groups, set up [locked parameters](./signed-embedding-parameters.md#pre-filtering-data-in-a-signed-embed) instead.
## How signed embedding works
If you want to set up interactive Metabase filters in your iframe, your web server will need to make requests to Metabase for updated data each time a website visitor updates the filter widget.
To ask for updated data from Metabase, your web server will generate a new Metabase [embedding URL](#adding-the-embedding-url-to-your-website). For example, if a website visitor enters the value "true" in an [embedded filter widget](./signed-embedding-parameters.md#adding-a-filter-widget-to-a-signed-embed), your web server will generate a new embedding URL with an extra parameter:
```
your_metabase_embedding_url?filter=true
```
To prevent people from editing the embedding URL to get access to other parts of your Metabase (e.g., by changing the parameter to `filter=company_secrets`), your web server will add a signed JWT to the new embedding URL:
```
your_metabase_embedding_url/your_signed_jwt?filter=true
```
The signed JWT is generated using your [Metabase secret key](#regenerating-the-secret-key). It tells Metabase that the request for filtered data can be trusted, so it's safe to display the results at the new embedding URL.
If you want to embed charts with additional interactive features, like [drill-down](https://www.metabase.com/learn/questions/drill-through) and [self-service querying](../questions/query-builder/introduction.md), see [Full-app embedding](./full-app-embedding.md).
## Enabling the embedding feature in Metabase
1. Go to **Admin settings** > **Embedding in other Applications**.
2. Click **Enable**.
![Enabling Embedding](./images/01-enabling.png)
## Making a question or dashboard embeddable
1. Go to the question or dashboard that you want to embed in your website.
2. Click on the **sharing icon** (square with an arrow pointing to the top right).
3. Select **Embed this item in an application**.
4. Optional: [Preview the appearance of the embed](#customizing-the-appearance-of-signed-embeds).
5. Optional: [Add parameters to the embed](./signed-embedding-parameters.md).
6. Click **Publish**.
![Preview](./images/04-preview.png)
## Adding the embedding URL to your website
The embedding URL for a question or dashboard is the Metabase URL that'll be displayed in your website's iframe. It's generated by your web server using your [Metabase site URL](../configuring-metabase/settings.md#site-url), [signed JWT](#how-signed-embedding-works), and [parameters](./signed-embedding-parameters.md):
```
metabase_site_url/embed/question/your_jwt_token?parameter_name=value
```
Once you've made a question or dashboard [embeddable](#making-a-question-or-dashboard-embeddable), you'll need to put the embedding URL for that question or dashboard on your website:
1. Go to the question or dashboard > **sharing icon** > **Embed this item in an application**.
2. Click **Code**.
3. From the top block, get the sample code for your backend web server:
- Select your web framework from the dropdown menu.
- Copy the code snippet generated by Metabase.
- Paste the code in the file that builds your website.
4. From the bottom block, get the sample code for your frontend:
- Select your template language from the dropdown menu.
- Copy the HTML snippet generated by Metabase.
- Paste the snippet in the HTML document where you want your signed embed to appear.
For more examples, see our [reference apps repo](https://github.com/metabase/embedding-reference-apps).
![Code samples for embedding](./images/05-code.png)
## Editing an embedded question or dashboard
If you change the [parameters](./signed-embedding-parameters.md) of your embedded item:
1. Click **Publish** again.
2. [Update the code](#adding-the-embedding-url-to-your-website) on your server so that it matches the code generated by Metabase (**Code** > top block).
## Disabling embedding for a question or dashboard
You can find a list of all embedded questions and dashboards from **Admin settings** > **Embedding in other Applications**.
1. Go to the embeddable question or dashboard.
2. Click on the **sharing icon** (square with an arrow pointing to the top right).
3. Select **Embed this item in an application**.
4. Click **Unpublish**.
## Customizing the appearance of signed embeds
You can change how an embedded question or dashboard looks in an iframe (which won't change how it looks in your Metabase instance).
1. Optional: Preview the appearance changes from your question or dashboard's embedding settings (**sharing icon** > **Embed this item in an application**).
2. Optional: Click **Code** to find the updated server code snippet in the top block.
3. Change the [parameters](./signed-embedding-parameters.md#customizing-the-appearance-of-a-signed-embed) in your actual server code.
For global appearance settings, such as the colors and fonts used across your entire Metabase instance, see [Customizing Metabase's appearance](../configuring-metabase/appearance.md).
## Removing the "Powered by Metabase" banner
![Powered by Metabase](./images/powered-by-metabase.png)
The banner appears on signed embeds created with the Metabase open source version. You'll need to upgrade to a [paid plan](https://www.metabase.com/pricing) to remove the banner.
## Regenerating the secret key
Your embedding secret key is used to sign JWTs for all of your [embedding URLs](#adding-the-embedding-url-to-your-website). You can find it under **Admin settings** > **Embedding in other Applications**.
**Regenerate key** will create a new secret key, and break any embedding URLs that used the old key.
## Resizing dashboards to fit their content
Dashboards are a fixed aspect ratio, so if you'd like to ensure they're automatically sized vertically to fit their contents you can use the [iFrame Resizer](https://github.com/davidjbradshaw/iframe-resizer) script. Metabase serves a copy for convenience:
```
<script src="http://metabase.example.com/app/iframeResizer.js"></script>
<iframe src="http://metabase.example.com/embed/dashboard/TOKEN" onload="iFrameResize({}, this)"></iframe>
```
## Further reading
- [Parameters for signed embeds](./signed-embedding-parameters.md).
- [Strategies for delivering customer-facing analytics](https://www.metabase.com/learn/embedding/embedding-overview).
- [Publishing data visualizations to the web](https://www.metabase.com/learn/embedding/embedding-charts-and-dashboards).
- [Customizing Metabase's appearance](../configuring-metabase/appearance.md).
docs/embedding/start.md
+ 8
− 16
View file @ 3b4ecc7f
---
title: Dashboards overview
title: Embedding overview
---
# Embedding overview
## [Introduction to embedding](./introduction.md)
## [Introduction](./introduction.md)
How to embed charts and dashboards in applications and websites.
What is embedding, and how does it work?
## [Public links](./public-links.md)
## [Signed embedding](./signed-embedding.md)
Sharing questions using public links.
Also known as standalone embedding. Display interactive charts and dashboards on your website while securing the underlying data.
## [Full-app embedding](./full-app-embedding.md)
How to embed the graphical query builder and more in your application.
Put all of Metabase (including the [query builder](../questions/query-builder/introduction.md#the-query-builder)) in your app to give people secure self-serve access to data.
## [Customize embeds](./customize-embeds.md)
## [Appearance](../configuring-metabase/appearance.md)
Introduction to customizing embedded charts and dashboards.
## [Whitelabeling](./whitelabeling.md)
How to customize the look and feel of embedded charts and dashboards to match your application's branding.
## [Fonts](./fonts.md)
How to customize the fonts in your charts and dashboards.
White label Metabase to match your company logo, colors, and other branding.
docs/paid-features/overview.md
+ 1
− 2
View file @ 3b4ecc7f
......@@ -40,8 +40,7 @@ Paid plans include more ways to manage permissions, including data sandboxing, w
You can embed all of Metabase in your app.
- [Embedding the entire Metabase app in your app](../embedding/full-app-embedding.md)
- [Customizing how Metabase looks with white labeling](../embedding/whitelabeling.md)
- [Customizing embedded items](../embedding//customize-embeds.md)
- [Customizing Metabase's appearance](../configuring-metabase/appearance.md)
## Dashboard subscription customization
......
docs/permissions/application.md
+ 2
− 2
View file @ 3b4ecc7f
......@@ -26,10 +26,10 @@ Settings access defines which groups can view and edit the settings under the Ad
- [Authentication](../people-and-groups/start.md)
- [Maps](../configuring-metabase/custom-maps.md)
- [Localization](../configuring-metabase/localization.md)
- [Public sharing](../embedding/public-links.md)
- [Appearance](../configuring-metabase/appearance.md)
- [Public sharing](../questions/sharing/public-links.md)
- [Embedding in other applications](../embedding/start.md)
- [Caching](../configuring-metabase/caching.md)
- [White labeling](../embedding/whitelabeling.md)
## Monitoring access
......
docs/questions/sharing/answers.md
+ 1
− 1
View file @ 3b4ecc7f
......@@ -68,7 +68,7 @@ Below each edit entry in the timeline, you can click on **Revert** to reinstate
## Sharing questions with public links
If your Metabase administrator has enabled [public sharing](../../embedding/public-links.md) on a saved question or dashboard, you can go to that question or dashboard and click on the sharing icon to find its public links. Public links can be viewed by anyone, even if they don't have access to Metabase. You can also use the public embedding code to embed your question or dashboard in a simple web page or blog post.
If your Metabase administrator has enabled [public sharing](../../questions/sharing/public-links.md) on a saved question or dashboard, you can go to that question or dashboard and click on the sharing icon to find its public links. Public links can be viewed by anyone, even if they don't have access to Metabase. You can also use the public embedding code to embed your question or dashboard in a simple web page or blog post.
![Share icon](../images/share-icon.png)
......
docs/embedding/public-links.md → docs/questions/sharing/public-links.md
+ 23
− 10
View file @ 3b4ecc7f
......@@ -2,30 +2,37 @@
title: Sharing questions using public links
redirect_from:
- /docs/latest/administration-guide/12-public-links
- /docs/latest/embedding/12-public-links
---
## Sharing questions using public links
# Sharing questions using public links
Sometimes you'll want to share a dashboard or question you've saved with someone that isn't a part of your organization or company, or someone who doesn't need access to your full Metabase instance. Metabase lets administrators create public links and simple embeds to let you do just that.
Sometimes you'll want to share a dashboard or question you've saved with someone that isn't a part of your organization or company, or someone who doesn't need access to your full Metabase instance. Metabase lets administrators create public links and [public embeds](#public-embed) to let you do just that.
### Turning public links on
## Turning public links on
![Enable public sharing](./images/enable-public-sharing.png)
![Enable public sharing](../images/enable-public-sharing.png)
First things first, you'll need to go to the Admin Panel and enable public sharing. In the future, you'll see dashboards and questions you've shared listed here, and you'll be able to revoke any public links that you no longer want to be used.
### Enable sharing on your dashboard or saved question
## Enable sharing on your dashboard or saved question
![Enable sharing](./images/enable-links.png)
![Enable sharing](../images/enable-links.png)
Next, exit the Admin Panel and go to question that you want to share, then click on the `Sharing and Embedding` icon in the bottom-right of the screen (it looks like an arrow pointing up and to the right). Then click on the toggle to enable public sharing for this question.
In the case of a dashboard, the button is located on the top right of the page.
### Copy, paste, and share!
## Copy, paste, and share!
Now just copy and share the public link URL with whomever you please. If you want to embed your dashboard or question in a simple web page or blog post, then copy and paste the iframe snippet to your destination of choice.
Copy and share the public link URL with whomever you please. The public link URL will display static results of your question or dashboard, so visitors won't be able to drill-down into the underlying data on their own.
### Assigning values to filters or hiding them via the URL
However, public URLs preserve [custom click behavior](../../dashboards/interactive.md). If you like, you can share specific drill-down views by linking to other questions or dashboards.
## Public embed
If you want to embed the link to your dashboard or question in a simple web page or blog post, copy and paste the iframe snippet to your destination of choice.
## Assigning values to filters or hiding them via the URL
This is a bit more advanced, but if you're embedding a dashboard or question in an iframe and it has one or more filter widgets on it, you can give those filters values and even hide one or more filters by adding some options to the end of the URL. (You could also do this when just sharing a link, but note that if you do that, the person you're sharing the link with could of course directly edit the URL to change the filters' values, or to change which filters are hidden or not.)
......@@ -57,4 +64,10 @@ To specify multiple values for filters, though, you'll need to separate them wit
```
/dashboard/42?id=7&customer_name=janet
```
\ No newline at end of file
```
## Further reading
- [Publishing data visualizations to the web](https://www.metabase.com/learn/embedding/embedding-charts-and-dashboards).
- [Customizing Metabase's appearance](../../configuring-metabase/appearance.md).
- [Embedding introduction](../../embedding/start.md).
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment