Embed Technologies: Web Component & iFrame

At Toucan Toco, we propose two technologies for embedding our solution:

  • Web Component: It's the most recent technology used to embed a component. (more info here)
  • Iframe: It’s today the most common technology used and the oldest too.

Web Components have a built-in fall back mechanism. If we detect that the environment of your user doesn’t support Web Components we will automatically fall back to iframes.

Here are some pros and cons for both technologies.



Simple Integration

Using our Web Component it simple as this:

   <script async src="{EMBED_ID}" type="text/javascript"></script>

All the intelligence is in the launcher, it will append our Web Component to the div.

Embed Manager: how to generate and manage embed scripts ?


Only user with at least the privilege "contribute" can export embedded stories.


You can disable the possibility to export embeds for everyone in the "front_config" by setting:
   embedCharts: false

Note: At the moment, you can only create an embed configuration from the export interface from the Story. Embed Export from Story

The embed interface is not aimed at modifying the story configuration. To do so, you have to use the Studio.

Embed interface example

Embed interface example

Display options

  • Use additionalPanel: Display the Additional Panel
  • Display the Story title: Display the story’s title

Make it public

You can also decide to make it publicly acessible: more info in the authentication chapter


You can set an arbitrary alias for your embed. It’s useful when you have a lot of embeds scripts to manage in differents environments.

Let’s imagine you’re setting to “amazing-embed”, you can then call your script as it is.

<script async src="" type="text/javascript"></script>

How to interact with my embed visualization from my application ?

View (or report ) app requester

In some cases you’ll want to use the same visualization for various users.

For instance an analysis by country, which is similar for your 10 countries but with different data.

To avoid building and exporting 10 different visualizations (one for each), you can manually overwrite view (also called appRequester report) value in the URL. Here is how to implement a view selector in your application

Here is an example of an embed script where I want to display data from point of view “France”.

<script async src="{EMBED_ID}&token={AUTH_TOKEN}&view=France" type="text/javascript"></script>

But generally, your view has several columns because it’s the common referential for all embeds. In that case, you can retrieve your view from a specific column (it should be unique identifier). For example here, if my view requester looks like this:

country_id country
1 France
2 Spain
3 Italy

I can use it there:

<script async src="{EMBED_ID}&token={AUTH_TOKEN}&view.country_id=1" type="text/javascript"></script>


💡 Want to make it dynamic by biding it to a master filter fom your own application ? Follow me here!

Date Selector

Indeed, you can do the same thing for the date range app requester. Here is how to implement it in your application

You can pass down preset values with following synthax:


so when encoding it into an URL it should look like


Let’s take an example. I’ve configured the preset “Today”, “Last Month” and a custom one called “Summer Sales”. Here an exemple for each of this preset value:

# Today
<script async src="{EMBED_ID}&date=%22preset_today%22" type="text/javascript"></script>

# Last Month
<script async src="{EMBED_ID}&date=%22preset_last_month%22" type="text/javascript"></script>

# Summer Sales
<script async src="{EMBED_ID}&date=%22preset_summer_sales%22" type="text/javascript"></script>

Date app requester “dataset based”

Indeed, you can do the same thing for the date app requester. Here is how to implement it in your application

Here is an example of an embed script where I want to display data for December 2020.

<script async src="{EMBED_ID}&token={AUTH_TOKEN}&date=December 2020" type="text/javascript"></script>

As for view app requester, it could happens that you activate the option make all columns available as well. In that case, you can also specify the column on which we want to retrieve the date requester value.

Let’s take an example:

date month year
2020-01-01 January 2020
2020-02-01 February 2020
2020-03-01 Lockdown 2020

And then use it in our script:

<script async src="{EMBED_ID}&token={AUTH_TOKEN}&date.month=Lockdown" type="text/javascript"></script>


💡 Want to make it dynamic by biding it to the date selector’s from your own application ? Follow me here!

Additional Panel

You can programmatically choose to show the additional panel. Don’t know what it is? Learn to configure it there

<script async src="{EMBED_ID}&panel" type="text/javascript"></script>

Compact Mode

Our stories are made to automatically adapt their display to the size of the screens. If a story is inside a small container or displayed on a mobile (a device with small screen), it will be displayed in “compact mode”. You may want to force or forbid the compact mode:

Force compact mode

<script async src="{EMBED_ID}&compact=true" type="text/javascript"></script>

Forbid compact mode

<script async src="{EMBED_ID}&compact=false" type="text/javascript"></script>

Display staging version


`staging` isn't accessible with `view` privilege!

As you should know, our stories have a built-in production/staging versionning. That help you to have control on what it is displayed to your end-users. In order to display this “staging” version, you can set it right on the embed script.

<script async src="{EMBED_ID}&stage=staging" type="text/javascript"></script>


You can specify the used language of your embeds by passing by the “lang” parameter. More info here on how to setup locales on your platform and your application

<script async src="{EMBED_ID}&lang=en" type="text/javascript"></script>

Customizing an embed


You can customize all the colors with a simple interface in Toucan Studio.



You can dynamically change those colors through the embed script.

For example:

      colors='{"chart-color-0": "pink"}'

You can copy/paste the complete theme in the field Short CSS from the Theme Interface to help you.



INTERFACE (Menu, buttons, text)

  • Brand: main-color
  • Discrete Brand: main-color-fade
  • Text: text-color
  • Dark: dark-color

HIGHLIGHTS (Active states, selections)

  • Emphasis: emphasis-color
  • Accent: secondary-emphasis-color
  • Positive: positive-color
  • Warning: warning-color
  • Negative: negative-color
  • Neutral: neutral-color

CHARTS (Series data)

  • Serie #1: chart-color-0
  • Serie #2: chart-color-1
  • Serie #3: chart-color-2
  • Serie #4: chart-color-3
  • Serie #5: chart-color-4
  • Serie #6: chart-color-5

SCALES (Quantified data)

  • Quartile #1: scale-color-0
  • Quartile #2: scale-color-1
  • Quartile #3: scale-color-2
  • Quartile #4: scale-color-3

Custom Series

You can also customize custom data label. Basically, tc-series-colors is a string with data labels in escaped double quotes, followed by the color separate by a space. You can define multiple labels, those groups are separated by commas. The following snippet will color bars with label Level 1 in red and label Level 2 in pink.

      colors='{"tc-series-colors":"\"Level 1\" red, \"Level 2\" pink}'

The result:





Custom CSS is a feature flag that we need to activate. By default the Custom CSS stylesheet is hidden as we’re not providing any support on it. To activate the Custom CSS on your instance please contact us.

For fonts, you can use our “Custom CSS” feature that lets you specify CSS rules within the Theme -> Color Scheme Interface. For now, you can only use a font host online. Let us know if it’s a big limitation for you.

For example, let’s use Lato font to change the labels’ font of my chart: font-family-css-rules

That’s the result font-family-changed-result

NEW - Deep Customization

Do you dream about having a complete control over the style of your embeds? Click here for an example on the Dashboard Builder.


CSS classes can change during the product’s life

Integration examples with frameworks

Angular 8


Same implementation as React. Still need help? Contact us!


Sample code integration

String html = "<iframe style=\"border: 0; overflow: hidden;\" frameBorder=\"0\" height=\"100%\" width=\"100%\" src=\"\"></iframe>";

WebView webView = (WebView)findViewById('VIEW_ID');
webView.setWebViewClient(new WebViewClient());
webView.loadData(html, mimeType: "text/html", encoding: null);

WebSettings webSettings = webView.getSettings();
webSettings.setDomStorageEnabled(true); // **Without this line, the page displays the loading icon indefinitely and the embed never load. **