Integration

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.

wc-iframe-pros-cons

wc-iframe-pros-cons

Simple Integration

Using our Web Component it simple as this:

<div>
   <script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}" type="text/javascript"></script>
</div>

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 ?

Important

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

Tip

You can disable the possibility to export embeds for everyone in the "front_config" by setting:
additionalPanel:
   ...
   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

Alias

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.

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="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={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="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={AUTH_TOKEN}&view.country_id=1" type="text/javascript"></script>

Tip

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

Date app requester

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="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={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="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={AUTH_TOKEN}&date.month=Lockdown" type="text/javascript"></script>

Tip

💡 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="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={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="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&compact=true" type="text/javascript"></script>

Forbid compact mode

<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&compact=false" type="text/javascript"></script>

Display staging version

Important

`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="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&stage=staging" type="text/javascript"></script>

I18n

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="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&lang=en" type="text/javascript"></script>

Customizing an embed

Colors

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

color-scheme-interface

color-scheme-interface

You can dynamically change those colors through the embed script.

For example:

<script
      async
      src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}"
      colors="{\"chart-color-0\": \"pink\"}"
      type="text/javascript"
></script>

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

color-scheme-interface-focused

color-scheme-interface-focused

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

Fonts

Note

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. 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

Integration examples with frameworks

Angular 8

Vue

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

Android

Sample code integration

String html = "<iframe style=\"border: 0; overflow: hidden;\" frameBorder=\"0\" height=\"100%\" width=\"100%\" src=\"https://MY_INSTANCE.toucantoco.com/embed.html?id=EMBED_ID\"></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. **
webSettings.setJavascriptEnabled(true);