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

The embed interface lets you configurate 3 options :

  • Expiration Date: The story can be available only for a certain amount of time - by default none is configured.
  • Allowed hosts: Specify which hosts will have access to this embed. You can declare multiple hosts by separating them by a comma : host1, host2. - by default all hosts are allowed (“*”).
  • Use current story state: this toggle lets you decide whether you prefer to freeze the story in its current state (requester, view and date) or if you prefer the embed to use the default configured.
    • Exemple using current story state : my default view is France but my current view is Spain. The generated embed will have the Spain view.
    • When not using current story state the generated embed will have the France view.

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

Here is how to implement a view selector in your application

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

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>

Customizing an embed

Colors

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

color-scheme-interface

color-scheme-interface

Fonts

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

More very soon (Vue,…)