# Getting Started : Embedded Analytics

## 📖 Introduction

**Welcome!** If you are here, it means you are ready to **dive into the world of embedded analytics** with [**Toucan**](https://www.toucantoco.com/en/). You want to integrate white-labeled analytics into your product to enrich your offering, impress your clients, and accelerate your roadmap. You are in the right place! 🙌

Whether you are a **new client ❤️ ready to get started** or a **prospect ✨ testing the Free Trial**, we will explore together how to navigate effectively to achieve your goals.

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-4c234e97aa2878132b50f8551cd903f927db806e%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2018.36.47.png?alt=media" alt=""><figcaption><p>Welcome on our Getting Started for Embedded Analytics</p></figcaption></figure>

## 📜 Preface

**Audience**

This guide is for product managers, data analysts, and developers integrating embedded analytics into their software with Toucan. It is for those who want to integrate white-labeled analytics efficiently.

{% hint style="info" %}
**Important Note**

This guide does not fully cover authentication management and embedding charts into your code, which are explained in the linked documentation. These aspects are crucial, but this guide focuses on the key steps to get started with embedded analytics. For more details, refer to the associated documentation.
{% endhint %}

## 🎯 Objective of this *Getting Started*

The goal of this guide is **simple**: to support you step by step **in getting started with embedded analytics.**

Before you begin, it is essential to understand **the major steps**. This guide will present these key steps so that you can ultimately **integrate personalized charts directly into your product or web portal**. 📺

*This is not a click-by-click tutorial* but rather a **general guide to help you get oriented**, giving you the necessary foundations to explore. You will find the associated documentation throughout and at the end of this guide.

You will be guided to see how to:

* Connect to data
* Create variables (to personalize the experience)
* Create customized datasets
* Create contextualized charts
* Embed these charts into your interface while managing secure authentication

Toucan can integrate analytics into your product at **different levels of granularity**, from simple and tailored widgets to full dashboards, while displaying the right data to the right person.

{% hint style="info" %}
You can find documentation about our embedded layouts

* [Tiles](https://docs-v3.toucantoco.com/visualizations-and-layouts/apps/home#title)
* [Stories](https://docs-v3.toucantoco.com/visualizations-and-layouts/apps/stories)
* [Dashboards](https://docs-v3.toucantoco.com/visualizations-and-layouts/apps/dashboard-builder)
* [Apps](https://docs-v3.toucantoco.com/visualizations-and-layouts/embedding/integration/embed-an-app)
  {% endhint %}

You just need to iterate gradually to add more analytics after that.

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-61b2090a4db06a4c9ec7c8d790845aaebeee33ac%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2017.53.34.png?alt=media" alt=""><figcaption><p>Example of Embedded Analytics (3 tiles on the left)</p></figcaption></figure>

## 🚂 Steps to follow when deploying embedded analytics

### 1) Connect to Data 🔗

To start, create a Toucan App, then [go to the **DataHub**](https://docs-v3.toucantoco.com/data-management/datasources-in-toucan) to create a connection to a data source, such as **PostgreSQL**. This step allows you to establish a solid foundation on which you can build your visualizations.

If you prefer, it is also possible to upload a [flat file](https://docs-v3.toucantoco.com/data-management/datasources-in-toucan/managing-files). This first step is crucial as it provides the necessary data for the following steps.

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-9a07dbb8e081b764c8b53eb8ef67e58012723668%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2017.55.44.png?alt=media" alt=""><figcaption><p>DataHub >> Datasource >> Add a Connector or a File</p></figcaption></figure>

### 2) Create Variables (to Personalize the Experience) 🧪

To provide a personalized experience, it is important [to create variables](https://docs-v3.toucantoco.com/data-management/managing-variables-in-toucan/variables-hub) that will help to adapt the content for each user.

First, go to the administration interface via the App Store to create the user attributes that will be used to personalize the experience (you need Admin rights for this). These attributes can be of different types and named as you wish, for example:

* **Client**: To identify data specific to each client.
* **Region**: To adapt the content based on location.
* **First Name**: To personalize the storytelling with the user's first name.

These variables should, of course, align with your Data Model and will likely correspond to columns.

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-e5bddea245f1e3e927507724cf4f350362102dcb%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2017.56.53.png?alt=media" alt=""><figcaption><p>App Store >> Settings >> Users >> Properties</p></figcaption></figure>

Next, return to your Toucan App and go to the **Variable Management menu** (at the top right) of the application itself. Finally, assign default values to these variables to simulate the user experience.

For example:

* **Client**: Apple
* **Region**: California
* **First Name**: Chris

These values will allow you to view the data as if you were a real user carrying these user attribute values, thereby validating the personalization of visualizations in an app-building environment (Toucan studio).

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-f341fc13675b31090c274dce95864f7f99338a8f%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2018.02.46.png?alt=media" alt=""><figcaption><p>App >> Settings >> Variable Management</p></figcaption></figure>

### 3) Create Customized Datasets 🚀

In Toucan, datasets can be saved as Stored (stored in Toucan - [see limitations in the documentation](https://docs-v3.toucantoco.com/data-management/datasets-in-toucan/stored-and-live-datasets)) or Live (leveraging the underlying data source).

{% hint style="info" %}
In embedded analytics, data is often processed in real time, and data is segregated by a “Client Identifier” (or "Product Identifier"), which would be a column in a “[One Big Table](https://medium.com/dbsql-sme-engineering/one-big-table-vs-dimensional-modeling-on-databricks-sql-755fc3ef5dfd)” data model. If the architectural model is different, we can work with you [to find the appropriate solution](https://docs-v3.toucantoco.com/data-management/using-advanced-data-concepts/data-personnalisation-with-user-attributes). We will assume this scenario for this getting started.
{% endhint %}

Data is the foundation of your project. With **YouPrep**, Toucan's data transformation tool, you can adjust data to meet your business needs: grouping data, creating conditional rules, performing joins, etc.

{% hint style="info" %}
Did you know? 👀 YouPrep can even [write the SQL language](https://docs-v3.toucantoco.com/data-management/datasets-in-toucan/preparing-data/youprep-tm-native-sql) for you for certain compatible connectors.
{% endhint %}

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-6516c30a603165d8c97097b63c579168c3d4f7c4%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2018.06.55.png?alt=media" alt=""><figcaption><p>DataHub >> Create a Dataset >> Play with Youprep!</p></figcaption></figure>

For example, you can apply a [**Filter Rows** step](https://docs-v3.toucantoco.com/data-management/datasets-in-toucan/preparing-data/filtering-with-youprep-tm) on the column that helps identify a client A or client B (e.g., "Client"). This filter ensures that only relevant data for each user is retained. Once the dataset is transformed and saved, it can be reused in your application, providing a personalized foundation for visualizations.

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-61cab758a20046bfce785cc5fcd2111934476441%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2018.07.59.png?alt=media" alt=""><figcaption><p>Use a Filter Rows Step >> Filter our column on a Variable (with a default value already defined)</p></figcaption></figure>

By default, Toucan will use the value defined in the Variable Management menu.

In production, however, Toucan will use the user attribute value carried by the [Json Web Token](https://docs-v3.toucantoco.com/visualizations-and-layouts/embedding/authentication) (see step 5).

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-92f4f074378777f52eab94d52360ebc764cd015b%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2018.10.18.png?alt=media" alt=""><figcaption><p>Don't forget to save your dataset (live mode here!)</p></figcaption></figure>

### 4) Create charts powered by storytelling 🎨

Now that your data is prepared, it is time to create contextualized charts. [Create a **story** in a Toucan chapter](https://docs-v3.toucantoco.com/visualizations-and-layouts/apps/stories/creating-a-story), consisting of one or two charts, with contextualization (narrative, tips, glossary), [accompanied by **KPIs**](https://docs-v3.toucantoco.com/visualizations-and-layouts/apps/stories/kpis) and filters.

To create these elements, you can follow the various documentation pages [to enrich your Data Story](https://docs-v3.toucantoco.com/visualizations-and-layouts/apps/stories/narrative)! If you want to move quickly, simply create a chart like a bar chart, leaderboard, or line chart. 😊

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-a0248578ea55dbce3362ee87a08ebaf27f6ba3b9%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2018.13.04.png?alt=media" alt=""><figcaption><p>Chapter >> Create a Story >> Create a chart from your personalized dataset</p></figcaption></figure>

Toucan can [apply filters](https://docs-v3.toucantoco.com/visualizations-and-layouts/apps/filters) to charts via the filter bar at the top, relying on a column from your dataset or another dataset with a column of the same name.

This allows your end users to filter and explore their data!

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-bf85faadce4abee856488bcde5c645e0eaa3cda7%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2018.17.28.png?alt=media" alt=""><figcaption><p>On the top of your story >> Create a filter >> then apply the filter in the UI or in Youprep</p></figcaption></figure>

Finally, do not hesitate to complete the Narrative above the chart to give it meaning and make its definition self-explanatory. Variables tied to user attributes can even be directly integrated into the narrative to make the experience more engaging, such as including the user's first name in the text.

We call ‘templating’ syntaxes including variables to make you text (or data) dynamic depending on the context of use. You can refer to the [Templating documentation](https://docs-v3.toucantoco.com/visualizations-and-layouts/creating-visualizations/advanced-chart-configuration/templating-from-charts-dataset#example-in-a-narrative) for this or the reference to variables.

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-6e96aeb98ce9a4aaf5aa362847393fcb8d5c2eb5%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2018.17.52.png?alt=media" alt=""><figcaption><p>Nice Data Story isn't it?</p></figcaption></figure>

Don't forget to change your colors and logos in the [White Label](https://docs-v3.toucantoco.com/administration/instance-management/customizing-your-instance-whitelabel) and [Customization Menu](https://docs-v3.toucantoco.com/visualizations-and-layouts/apps/customizing-apps).

### 5) Embed Charts in Your Interface with Secure Authentication 👩🏻‍💻

{% hint style="danger" %}
You will probably need a developer to finalize this step if you are a customer. ([cf doc](https://docs-v3.toucantoco.com/visualizations-and-layouts/embedding/authentication))
{% endhint %}

To finalize, it is time to integrate your work directly into your software. Use a Json Web Token (JWT)-based authentication system to dynamically pass user attributes to Toucan. It is like the JWT is an ID card, and the user attributes are the characteristics of a person on the ID card: a number, height, eye color, etc.

Be sure to create [user tokens that carry user attributes](https://docs-v3.toucantoco.com/additional-ressources/tutorials/embed-a-story-with-user-attributes) with the same syntax as defined in the Variable Management section. For instance, if you have a "country" column to filter, it will be easier if your Variable is called "country".

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-bd56406d122a4648c6ef5f869d803a4abd174e7b%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2018.22.42.png?alt=media" alt=""><figcaption><p>For instance: Clement is connected on Breezy, so he can see its own figures compared to Charles!</p></figcaption></figure>

Once the authentication system is in place ([see the associated documentation](https://docs-v3.toucantoco.com/visualizations-and-layouts/embedding/authentication)), don't forget to publish your work in production (Publish Button), then generate an embed by clicking on the "..." in the interface.

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-36672b3e89063e234b97dee8de6b8a2e21a376da%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2018.24.24.png?alt=media" alt=""><figcaption><p>In Production Mode >> Click on the "..." next to a Story >> Embed Story</p></figcaption></figure>

Copy the **web component** into your frontend, place the token, and everything is ready! Each user will thus experience a personalized experience based on their data. Here the token was prepared for this demo.

<figure><img src="https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-523bedbec72cc1725c771868e09ab17882f88a54%2FCapture%20d%E2%80%99e%CC%81cran%202024-10-30%20a%CC%80%2018.25.22.png?alt=media" alt=""><figcaption><p>Tada 🎉 An Awesome Data Story Embedded into your own frontend!</p></figcaption></figure>

Of course you can dig in the [Integration Documentation](https://docs-v3.toucantoco.com/visualizations-and-layouts/embedding/integration) to deep dive in what we can customize.

## 👩🏼‍🏫 Summary

We have explored together the steps to **get started with** **embedded analytics** using Toucan: connecting to data, creating variables and customized datasets, creating contextualized charts, and finally embedding them in your interface while managing secure authentication.

Once these skills are mastered, the Toucan solution will allow you **to add analytics to your product**, without any code, in just a few minutes, **providing a personalized and engaging experience**.

{% hint style="info" %}
There is much more to discover such as the use of our SDK (lien) to deeply integrate Toucan with your product or whitelabeling to blend Toucan viz within your design.
{% endhint %}

## 👋 Outro

The world of analytics is limitless: your clients probably expect standard indicators shared across your product! 👥 You could even address specific personas or offer a paid analytics module as part of your service offering. 💰 Your website could even feature public analytics or a barometer to raise awareness among your audience about certain metrics! 🌎 In short, data is just waiting for you to bring it to life.😊

{% hint style="info" %}
This **Webinar Replay** could help to understand the same Embedded Analytics path also 🎁 It's free!
{% endhint %}

{% embed url="<https://youtu.be/0zfu3JF3X08?si=xHEdojv2guY172CR>" %}

## 📚 Associated Documentation

* [Datasources in Toucan](https://docs-v3.toucantoco.com/data-management/datasources-in-toucan)
* [Dataset in Toucan (live and stored)](https://docs-v3.toucantoco.com/data-management/datasets-in-toucan)
* [Transform data with YouPrep](https://docs-v3.toucantoco.com/data-management/datasets-in-toucan/preparing-data/overview-of-youprep-)
* [Manage variables](https://docs-v3.toucantoco.com/data-management/managing-variables-in-toucan)
* [Tutorial on data variabilization](https://docs-v3.toucantoco.com/additional-ressources/tutorials/embed-a-story-with-user-attributes)
* [Variability based on your software's architecture](https://docs-v3.toucantoco.com/data-management/using-advanced-data-concepts/data-personnalisation-with-user-attributes)
* [Create a story](https://docs-v3.toucantoco.com/visualizations-and-layouts/apps/stories)
* [Filters](https://docs-v3.toucantoco.com/visualizations-and-layouts/apps/filters)
* [Authentication](https://docs-v3.toucantoco.com/visualizations-and-layouts/embedding/authentication)
* [Templating](https://docs-v3.toucantoco.com/visualizations-and-layouts/creating-visualizations/advanced-chart-configuration/templating-from-charts-dataset#example-in-a-narrative)
* [Easy Reference to Variables](https://docs-v3.toucantoco.com/data-management/managing-variables-in-toucan/easy-reference-to-variables)

If you have **any doubts or questions** after reading this Getting Started guide, feel free [to reach out to us](https://docs-v3.toucantoco.com/additional-ressources/support-for-app-builders)! 💌