Embedded analytics

How to leverage Toucan stories on other web platforms

Warning

This is a technical feature intended to be used by Webmasters. The documentation mays not be adequate for non technical users. You shall be confortable with html and javascript.

As a Toucan administrator you can embed stories in your environment.

Why would I need to embed Toucan stories?

  • I’m a product manager leading the development of a new application. Some part of the application will consist in analytics. I’ve to decide whether to build this from scratch or use off the shelf analytics solutions such as Toucan
  • I’m a BI manager who has already deployed Toucan application. I’m searching new ways to distribute informations. One solution could be embedding Toucan stories in other tools such as internal messaging application, stock management tools, etc.

Note

What is a story?

A story is composed of one or two charts and optionnaly a comment, a recommendation and a source. All the navigation elements and the settings panel (on the right of each story) can’t be embedded at the moment.

Pre-requisites

Your Toucan instance can’t build embeds by default (they won’t be accessible).

Please get in touch with your Toucan contact when the embed need arises to udpate your instance configuration.

Embed front deployment configuration
nginx_embed: true nginx_headers: Access-Control-Allow-Origin: “*” Access-Control-Allow-Methods: “GET”

Authentication: Single Sign On vs Public access

By default Toucan embeds are protected by SSO. But you can decide to make your embeds public, that is accessible without authentication.

Configuring a SSO

The authentication method used for an embed corresponds to the authentication that has been set up for the small app used to generate this embed.

So, to configure the SSO of your embeds you have to set up a SSO for the Toucan instance of the small app that you’ll be using to generate embeds.

All the embeds you then create will be protected by this SSO.

Warning

At this time Toucan embeds only support the SAML2 protocol

Sharing public embeds

  1. Ask your Toucan contact to create a public user (PUBLICUSERNAME with password PUBLICUSERPASSWORD)
  2. Go to the user interface and edit this public user. You shall give it “Viewer” access to all small apps from which you want to generate public embeds

After generating your embed you can check that it now contains the public user credentials

The script will be similar to

<script async data-embed-info='{"smallAppId":"XXX","embedType":"story","apiBaseroute":"XXX","credentials":{"username":"PUBLICUSERNAME","password":"PUBLICUSERPASSWORD"},  "embedToken":"MY_EMBED_TOKEN","locale":"en","instanceUrl":"XXX"}' src="XXX" type="text/javascript"></script>

Now this embed is accessible without authentication to everyone.

Embed workflow

Embed workflow example

Embed workflow example

Warning

As you see in the GIF the Toucan story has been created previously with Toucan Studio. If you don’t know how to create a story you shall start learning that first!

  1. Go to the story you wish to embed
  2. Go to the settings panel on the right of the story
  3. Click on “Collaborate”
  4. Click on “Embed story”. You need to have administator rights to access the embed interface.
  5. In the embed interface Click on “Generate embed” to create an embed with the default settings or change them first
  6. Then click on “Copy embed script” and paste the script tag in the container that will contain the story
  7. Once an embed has been created you can edit its configuration or delete it

Embed configuration

Embed interface example

Embed interface example

The embed interface is not aimed at modifying the story configuration. To do that you shall use the Studio.

The embed interface let you play with 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 coma : host1, host2. - by default all hosts are allowed (“*”).
  • Use current story state: this toggle let 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.

Advanced embed configuration - customize state values

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

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

To avoid building and exporting 10 stories using the current story state example, you can manually overwrite state values in the script balise.

Here is an example of an embed script:

<script async data-embed-info='{"smallAppId":"XXX","embedType":"story","apiBaseroute":"XXX","embedToken":"MY_EMBED_TOKEN","locale":"en","instanceUrl":"XXX"}' src="XXX" type="text/javascript"></script>

You are free to add a variables entry in the data-embed-info object. More precisely in our case what you want to do is use the currentUser country to display here the correct data. Let’s say you stored this information in currentUserCountry in your product and you have a country key in your data.

<script async data-embed-info='{"variables":{"requestersManager":{"APP_REPORT_REQUESTER_ID": {"country": "currentUserCountry"}}}, "smallAppId":"XXX","embedType":"story","apiBaseroute":"XXX","embedToken":"MY_EMBED_TOKEN","locale":"en","instanceUrl":"XXX"}' src="XXX" type="text/javascript"></script>

We have added the following snippet: {"variables":{"APP_REPORT_REQUESTER_ID":currentUser.country}

In the Toucan environment you have 2 special requesters:

  • APP_REPORT_REQUESTER_ID: corresponds to the main view of the story
  • APP_DATE_REQUESTER_ID: corresponds to the date navigator

You can also overwrite the values of every requester you’re interested in by using the {REQUESTER_ID: VALUE} syntax. The requester id is available in the studio.

Warning

If you have implemented permissions in your Toucan application they are not used yet in the embeds. But this is something that will be available in the coming months (please see roadmap section below).

Charts availability

At the time of writing only Toucan charts (so not tiles) are available, and 4 charts are not available for the moment:

  • linechart (estimated availability: september 2019)
  • leaderboard centered average (estimated availability: end of 2019)
  • score-card (estimated availability: end of 2019)
  • bullet chart (estimated availability: end of 2019)